Slack

Add HookCI to Slack, watch repositories, use every /hookci command, manage agents in App Home, and tune what the run messages and alerts say.

The @hookci app puts each run in a channel, updates it as jobs finish, alerts you when one fails, and lets you manage agents without leaving Slack.

Add HookCI to Slack

Install the GitHub App at ci.webuno.io/start if you have not.
On the hub page, choose Add to Slack and approve the app. You must be an admin of the GitHub account.
Link your Slack user to your GitHub account. Run /hookci me and click the button. The link works once and expires after 10 minutes.
Invite the bot to a channel and watch a repository.

/invite @hookci
/hookci watch acme/web

Illustration. The command and the app's confirmation in a #ci channel.

One Slack workspace connects to one installation. Enterprise Grid is not supported, so install on a single workspace.

Commands

Every command starts with /hookci. A bare /hookci or /hookci help prints one line per command.

Command	What it does	Access needed
`/hookci watch <owner/repo> [quiet] [dm]`	Posts the repository’s run messages in this channel and sends a test message. The bot must already be in the channel.	Write
`/hookci unwatch <owner/repo>`	Stops posting that repository in this channel.	Write
`/hookci status [owner/repo]`	Lists your agents (online or offline, version, last seen) and the last 5 runs of the repository.	Read
`/hookci retry <owner/repo> [sha]`	Re-runs the latest run, or the run of that commit, as the next attempt on the bound agent.	Write
`/hookci bind <owner/repo> <agent> [checks\|deploy:<env>]`	Makes an agent run that target for the repository. The target defaults to `checks`.	Admin
`/hookci me`	Sends a one-use button that links your GitHub account.	None
`/hookci me unlink`	Removes the link.	None
`/hookci export`	Sends a 15 minute download link for a JSON file of your data.	None
`/hookci delete-my-data`	Deletes your GitHub link and author mappings in this workspace.	None
`/hookci help`	Lists the commands.	None

Access levels are GitHub permissions on the repository. For bind, <agent> is the agent name or its id. If two agents share a name, use the id.

watch options

Option	Effect	Default
`quiet`	The run message lists job results, with no reply per job.	`normal`
`dm`	The failure alert goes to the commit author as a direct message instead of the thread.	`channel`

/hookci watch acme/web quiet dm

Slash commands are rate limited per workspace. If you see “too many commands in this workspace”, wait a minute.

Answers you may see

Answer	Meaning
“agent is offline: checks did not run”	`retry` found no connected agent. Start the agent, then retry.
“no agent runs checks for repo; an admin can bind one”	The repository has no binding. See `bind`.
“Invite @hookci back and run /hookci watch again”	The bot lost access to the channel, so HookCI dropped the watch.

What a run looks like

HookCI posts one message per run and edits it in place. It shows the repository, branch, short commit, author, and one row per job with its state and duration. A run has one of these states: Running, Passed, Failed, Cancelled, Skipped, Waiting, Agent offline, or Superseded.

Illustration. Each job has a state and duration. View log opens a signed link that is valid for 15 minutes.

View log opens the job log in your browser through a signed link. The link is valid for 15 minutes and should not be shared.
With logs: local in .hookci.yml, logs never leave your server. The message tells you to read them with hookci logs on the agent.
A new push to the same branch marks the old run Superseded.

Failure alerts

When a run fails, HookCI sends one alert for it. The alert names the failed job and step and shows the last lines of the log with a log link. With alert: channel it goes in the run’s thread. With alert: dm it goes to the commit author by direct message. To reach the author, HookCI matches the Slack user to the GitHub login of the commit, which is why it asks for users:read.email.

Offline agents

If an agent goes offline, its admin gets a direct message with the number of runs waiting for it to reconnect and a pointer to hookci doctor.

Notification settings in `.hookci.yml`

The channel’s watch options set the defaults. A repository can override them in .hookci.yml:

version: 1
notify:
  slack:
    channel: ci-alerts
    on: [failure]
    notify: quiet
    alert: dm

Key	Values	Effect
`channel`	A channel name, with or without `#`	Posts this repository’s run messages here instead of the watched channel. It must be in the same workspace, and the bot must be able to post there.
`on`	`failure`, `success`, `deploy`, `all`	Which outcomes send a notification.
`notify`	`quiet`, `normal`, `verbose`	How much the run message says. `quiet` lists job results in the message. `normal` also replies in the thread for each finished job. `verbose` means `normal`.
`alert`	`channel`, `dm`	Where the failure alert goes.

Settings in .hookci.yml win over the watch options. See the .hookci.yml reference for the full schema.

App Home

Open the HookCI app in Slack and choose the Home tab. If your account is not linked, it asks you to run /hookci me.

Illustration. Agents with status and Revoke, watched repositories, and recent runs.

Section	Shows
Agents	Each agent as online, “offline since” a time, “offline, never connected”, or revoked. Shows “upgrade available” with `sudo hookci upgrade` when a newer version exists.
Add agent	A new pair token with the install and connect commands. The token works once and expires after 15 minutes.
Revoke	A confirmation, then the agent stops at once and its runs are interrupted. Pairing it again needs a new pair token.
Repos	The repositories watched in this workspace, or a hint to run `/hookci watch`.
Recent runs	The latest runs with their states.
Refresh	Reloads the page.

Add agent and Revoke are for admins of the GitHub account. When there is too much to list, App Home says so and points you to /hookci status <owner/repo> for the rest. See Pair an agent.

Approve a fork pull request

A run from a fork waits for approval, and its message says so with an Approve run button.

Illustration. The Approve run button appears only on runs from forks that need a decision.

Click Approve run to start it. You need write access to the repository and a linked GitHub account. The approval covers that commit only. Look at what the pull request changes before you approve, because the run executes the fork’s code on your agent. The message records who approved. The same approval is available on the GitHub check. See Trust and forks.

What the app can access

Bot scope	Used for
`chat:write`	Post and edit run messages and alerts.
`commands`	The `/hookci` slash command.
`channels:read`, `groups:read`	Check that the bot is in a channel before watching it.
`im:write`	Direct messages: failure alerts with `alert: dm` and offline notices.
`users:read`, `users:read.email`	Match Slack users to GitHub logins and commit authors. The email is used only for this.

HookCI handles these Slack events: app_home_opened, app_uninstalled, tokens_revoked, channel_left, and group_left. Removing the Slack app deletes that workspace’s data from the hub within 30 days. More on data in Security and data.

HookCI also plans a Telegram bot with the same run messages. See Telegram.

If something does not work

No messages appear. Run /hookci status <owner/repo>. Check that the repository is watched in this channel and that the bot is a member.
Buttons do nothing for you. Link your account with /hookci me, and check that you have write access on GitHub.
The wrong channel gets messages. A notify.slack.channel in .hookci.yml overrides the watch channel.
Everything is offline. Run sudo hookci doctor on the agent host. See Troubleshooting.