# Posting task events to Slack

Source: https://codeherder.com/docs/slack/

Connect Slack, add routes that post each task as a card with a thread, get your own task threads as DMs, and approve, answer or unblock from Slack.

CodeHerder posts task events to Slack channels. You connect Slack once, then add a **delivery route** for each channel. A route says which kinds of event go to that channel. Each task gets a card, and every event for the task posts in the card’s thread. You can also act from Slack: approve a task, answer an agent’s question, clear a blocker, or reply in the thread to comment. CodeHerder can also send the threads of your own tasks to you as Slack direct messages. This page takes you from nothing to a posted message.

On a self-hosted server, the operator sets up the Slack app first. See [Setting up the Slack app](https://codeherder.com/docs/slack-app/). Hosted CodeHerder needs no app setup.

## Who can do what

Owners and admins connect Slack, and add, edit, enable, disable and delete routes. Other members can read the routes but not change them. An agent cannot change a route.

Any member with a [linked Slack account](https://codeherder.com/docs/slack/#link-your-slack-account) can use the buttons and thread replies. CodeHerder applies the same permissions as in the web app. A button or reply does nothing you could not do in CodeHerder.

## Connect Slack

1. Open **Admin → Integrations**, then open **Slack** from the provider list.
2. Click **Connect**. A connect page opens. Click **Connect integration**.
3. Slack opens. Approve the request. You return to the Slack page.
4. The badge reads **Connected**. The connection section shows a **Slack workspace** row with your Slack team name. The provider list also names the team.

If the connection fails, you return to the Integrations page (the provider list) with an error notice. Try again.

## Invite the bot

CodeHerder can only post to channels the bot is in. In Slack, open the channel and type `/invite @CodeHerder`. Do this for a private channel too. Once Slack is connected, the Slack page shows an **Invite the bot** panel with the same reminder.

## Add a route

Routes belong to a workspace. You cannot add one in a group. See [Inherited connections](https://codeherder.com/docs/slack/#inherited-connections).

1. On the Slack page, find **Delivery routes**. The panel appears once Slack is connected.
2. Click **New route**.
3. Pick a channel. The list shows public and private channels that have the bot. A private channel shows “(private)”. Archived channels do not appear.
4. Tick one or more categories.
5. Click **Create route**.

A workspace can have one route per channel. To send different events to one channel, put the categories on that one route.

### Categories

- **Task status changes**: a task moves to another stage.
- **Needs a human**: an agent asks a question or waits for input, or a task needs approval or has a blocker.
- **Merged**: a merge request for a task merges.
- **Failures**: a task fails to start, stalls or runs out of budget, a session is lost or hits a provider error, or CI fails.
- **Network access requests**: a system image build waits for an admin to approve a network host. A request that a session raised does not post here.

A route posts only events from its own workspace. One event posts once per route.

## What a message shows

### The task card and its thread

The first event for a task in a channel posts a **task card**. The card shows:

- The task title.
- The person who created the task.
- The stage, as “Stage 2 of 5: name”.
- The status. A blocked task shows **Blocked** and the stage it left. Otherwise the status shows the current stage.
- The spend so far, in dollars.
- An **Open task** link.

Every event for that task then posts as a reply in the card’s thread. The card updates in place when the stage, the status or the spend changes. You do not get a new card for each change.

Each reply has a fixed summary line, such as “A task stalled” or “A merge request merged”. A stage change shows the old and the new stage. A reply also has a **View in CodeHerder** link.

Some replies carry text:

- A question shows its header, the question and the answer options.
- A blocker shows its reason. When the blocker asks a person to act, it also shows **What happened** and **What is needed**.

Everyone in the channel can read this text. Invite only people who may read it.

A message never carries comments, summaries or any other text from the task. Open the link to read those, where CodeHerder checks your access.

A network access message is separate. It names the workspace, the target and the device. It links to **Dashboard** → **Network access approvals** in that workspace. It has no task, stage or buttons, and it posts as its own message, not in a thread. It shows no URL path, header, body or credential.

### The finish reply

When a task reaches a final stage, its thread gets one more reply that starts “Task finished:” and names the stage. The reply lists:

- The task’s merge requests, each marked **(merged)** or **(not merged)**.
- The total cost, in dollars.
- The stages the task completed.

CodeHerder leaves out a line that has no data, such as the merge requests of a task that has none. The card updates to match.

## Act from Slack

Some messages have buttons. A button needs a [linked Slack account](https://codeherder.com/docs/slack/#link-your-slack-account). CodeHerder checks your access before it acts, as in the web app.

| Message | Button | What it does |
| --- | --- | --- |
| A task needs approval | **Approve**, **Reject** | Decides the pending advance. See [Approvals and staying in control](https://codeherder.com/docs/approvals/). |
| An agent asks a question | **Answer** | Opens a form with the options and a text box. Submit sends the answer to the agent. See [When an agent needs your input](https://codeherder.com/docs/agent-input/). |
| A task has a blocker that a person can clear | **Unblock** | Opens a form. Choose an option, or add a note for the agent. Submit clears the blocker. See [Blockers and blocked tasks](https://codeherder.com/docs/blockers/). |

An **Unblock** button does not appear when the blocker needs something else. This covers a question, a network access or approval wait, a dependency, a merge request wait, and a blocker that is already clear.

After you act, the message updates to say who did it, for example “Approved by” or “Answered by” followed by your Slack name. If someone else acted first, the message says so, for example “No longer pending”, “Already answered” or “Already resolved”.

If your Slack account is not linked, Slack asks you to link it first. If your member is disabled, you cannot act.

If a message has no buttons, the server may have buttons turned off. The **Delivery routes** panel then says the server renders no Approve, Reject or Answer buttons. On a self-hosted server, see [Setting up the Slack app](https://codeherder.com/docs/slack-app/#buttons).

## Reply in a task’s thread

A reply in a task’s thread reaches the task. Reply in the thread, not in the channel.

- A reply becomes a **comment** on the task, written by your linked member.
- If the task has exactly one open question, and that question has one part, your reply **answers** it instead. If CodeHerder refuses the answer, it posts your reply as a comment.

Slack shows you a private note that says what happened: the reply answered the question, or it posted to the task as a comment. If you have not linked your Slack account, the note asks you to link it first. CodeHerder turns mentions into plain text and does not expand links. A top-level channel message, an edit and a bot message do nothing.

A reply needs the thread permissions. See [Turn on threads and replies](https://codeherder.com/docs/slack/#turn-on-threads-and-replies). If your workspace requires single sign-on, a reply follows that rule too. See [Single sign-on (SAML and OIDC)](https://codeherder.com/docs/sso/).

## Get your task threads as DMs

CodeHerder can send the thread of a task to you as a Slack direct message. The DM has the same card and replies as the channel thread. It also carries the same buttons, and you can reply in it the same way. See [Act from Slack](https://codeherder.com/docs/slack/#act-from-slack) and [Reply in a task’s thread](https://codeherder.com/docs/slack/#reply-in-a-tasks-thread).

### Who gets a DM

Each task goes to one person: the closest human. That is the person who started the task. If a person did not start it, it is the person who created it. If neither was a person, CodeHerder looks at the task that filed it, or at its parent, and so on up the chain.

You get the DM when all of these hold:

- Slack is connected, with the thread permissions. See [Turn on threads and replies](https://codeherder.com/docs/slack/#turn-on-threads-and-replies).
- You linked your Slack account in that Slack team. See [Link your Slack account](https://codeherder.com/docs/slack/#link-your-slack-account).
- DMs are on for that link. They are on by default.
- You are an active member with a role in the task’s workspace.

A DM never reaches a person who cannot read the task. DMs cover the same events as routes, except network access requests. Routes do not limit them.

### Turn DMs off or on

In **Profile**, find **Slack accounts**. Use the switch in the **Slack DMs** column of the link’s row. Each link has its own switch.

From the CLI, list your links to find the ID, then edit the link:

```
ch slack links
ch slack links edit <linkId> --dm-threads off
ch slack links edit <linkId> --dm-threads on
```

### See DMs that failed

In **Profile**, the **Slack DMs that failed** panel lists each failed DM with its workspace, the event, why it failed and when. The panel says “No failed DMs yet.” when none failed. From the CLI, run `ch slack dms --status failed`.

## Edit, disable or delete a route

Use the buttons on the route’s row.

- **Edit** changes the categories. The channel is fixed. To change the channel, delete the route and add a new one.
- **Disable** stops posting to the channel. **Enable** starts it again. CodeHerder does not send events that happened while the route was off.
- **Delete** removes the route. CodeHerder stops posting to the channel.

## When a route turns off

If Slack refuses a post for one of these reasons, CodeHerder turns the route off. The route’s State column shows the reason:

- “The CodeHerder bot is not in #channel. Invite the bot to #channel, then enable the route.” Run `/invite @CodeHerder` in the channel, then enable the route.
- “Slack cannot find #channel. Pick another channel, or delete this route.” Delete the route and add one for another channel.
- “#channel is archived in Slack. Unarchive it, then enable the route.” Unarchive the channel in Slack, then enable the route.

To see what did not arrive, open **Recent deliveries** and filter by **Failed**. See [Recent deliveries](https://codeherder.com/docs/slack/#recent-deliveries).

CodeHerder retries by itself when Slack is busy or slow. You do not need to act.

## Recent deliveries

The **Recent deliveries** panel shows what each route posted to Slack, newest first. It appears below the routes once Slack is connected, in a workspace. A group does not show it.

Each row has these columns:

- **Channel**: where the message went.
- **Event**: what happened. A failed delivery shows its last error under the event.
- **State**: where the delivery is. See the list below.
- **Attempts**: how many times CodeHerder tried to post.
- **Created**: when the delivery was queued.

Use the **State** filter to narrow the list. The choices are **All**, **Failed**, **Pending**, **Delivered** and **Skipped**. The panel says “No deliveries yet.” until a route posts an event.

### What each state means

- **Pending**: the message is queued, or CodeHerder is waiting to try again.
- **Delivered**: Slack accepted the message.
- **Failed**: CodeHerder stopped trying. Slack refused the post, or the retries ran out. The row shows the last error.
- **Skipped**: CodeHerder did not send the message. The route was off or deleted, Slack was not connected or the connection was off, or the event, task or request no longer applies. CodeHerder does not send a skipped message later.

## When the connection turns off

If someone uninstalls the app or revokes its token in Slack, posting stops. Slack may remove the connection, or CodeHerder may turn it off. If the badge shows **Not connected**, connect again. If it still shows **Connected**, click **Edit connection** on the Slack page. A cleared **Enabled** box means the connection is off. Click **Disconnect**, then connect again. Your routes stay as they were.

## Turn on threads and replies

A connection made before threads and replies existed lacks the thread permissions. It keeps posting one message per event, with no card and no thread. Replies and Slack DMs need the permissions too.

Admins see a prompt on the Slack page: **Reinstall Slack to enable threads and replies.** Click **Reinstall Slack** and approve the new permissions in Slack. Your routes stay as they were. Members see no prompt.

If you run your own Slack app, update it first. See [Add thread replies to an existing app](https://codeherder.com/docs/slack-app/#add-thread-replies-to-an-existing-app).

An inherited connection belongs to a group above your workspace. The prompt then links to the group’s Slack page, and an admin of that group reinstalls.

## Inherited connections

If a group above your workspace connects Slack, every workspace under it can use that connection. The Slack page shows **Connected** and an **Inherited** flag. You cannot edit or disconnect it from the workspace. Each workspace adds its own routes, so each team picks its own channels. On the group’s Slack page, a **Delivery routes** note says routes belong to a workspace. Open a workspace to add routes and see its recent deliveries.

## Use Slack from the CLI

The `ch slack` commands read your Slack data. One command, `ch slack links edit`, changes it. Add, edit and delete routes in the web app.

`ch slack routes` prints the routes of a workspace. The columns are ID, enabled, buttons, channel, categories and reason. The **BUTTONS** column reads `on` or `off`. It shows whether this server renders buttons.

```
ch slack routes
ch slack routes --workspace <workspace> --limit 20
```

`ch slack deliveries` prints the recent deliveries of a workspace, newest first. The columns are ID, created, channel, event, status, attempts and error. Use `--status` to show one state: `pending`, `delivered`, `failed` or `skipped`.

```
ch slack deliveries
ch slack deliveries --status failed --limit 20
```

`ch slack dms` prints your own DM deliveries, newest first. The columns are ID, created, workspace, event, status, attempts and error. It takes the same `--status` values as `ch slack deliveries`. It belongs to you, not to a workspace. See [Get your task threads as DMs](https://codeherder.com/docs/slack/#get-your-task-threads-as-dms).

```
ch slack dms --status failed
```

`ch slack links` prints the Slack accounts you linked to your CodeHerder account. The columns are ID, team, Slack user, DMs and verified. `ch slack links edit <linkId> --dm-threads on|off` turns DMs for one link on or off. You make a link in the web app. See [Link your Slack account](https://codeherder.com/docs/slack/#link-your-slack-account).

Each list command takes `--limit` and `--cursor <token>`. Use `--cursor` to read the next page.

## Link your Slack account

You can link your own Slack account to your CodeHerder account. The link tells CodeHerder which member you are in Slack. Buttons, thread replies and DMs of your task threads need it.

There are two places to link it:

- **Profile.** Open the user menu in the top bar and click **Profile**. Find the **Slack accounts** section. It shows only when the server has a Slack app. Select **Link Slack account**.
- **The Slack page.** Open the Slack page of a workspace. The **Your Slack account** section shows “Linked as” your Slack user, or “Not linked” in the connected Slack team. Click **Link your Slack account**. You return to the Slack page. If you linked a different Slack team, a notice names both teams.

Sign in with Slack when it asks. The **Slack accounts** section then lists your Slack team, your Slack user, whether **Slack DMs** are on and when you linked it.

To remove the link, select **Unlink** on its row in **Profile** and confirm. You can also list your links with `ch slack links`.

## Related guides

- [Setting up the Slack app](https://codeherder.com/docs/slack-app/): create the app on a self-hosted server.
- [Integrations](https://codeherder.com/docs/integrations/): connect, edit and remove any provider.
- [Webhooks](https://codeherder.com/docs/webhooks/): send a signed payload to your own endpoint when you need a custom message.
