CodeHerderSearch⌘KRequest access →

Posting task events to 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. 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 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.

  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. 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.
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.
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.

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.

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. If your workspace requires single sign-on, a reply follows that rule too. See Single sign-on (SAML and OIDC).

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 and Reply in a task’s 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.
  • You linked your Slack account in that Slack team. See 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.

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.

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.

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.

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

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.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close