Pair an agent

An agent is one server running hookci agent that the hub trusts. Pairing exchanges a single-use token for a long-lived credential that the agent keeps on disk. After pairing, the agent connects to the hub by itself and keeps the connection open.

Get a pair token

A pair token starts with hc_pair_. It works once and expires 15 minutes after it is created. You can get one in two places:

• On the hub page right after you install the GitHub App at ci.webuno.io/start. The page shows the token with the commands and waits for your agent to connect.
• In Slack App Home: open the HookCI app, then Add agent. It shows the install and connect commands with a fresh token. You must have linked your GitHub account with /hookci me.

Only an admin of the GitHub account can create a token. The hub limits how many tokens one installation can create per hour, and how many redeem attempts one IP address can make per hour. If you hit a limit, wait and try again.

Install and connect

Install the binary and the systemd units, then redeem the token. Run both on the server that will run your checks.

curl -fsSL https://ci.webuno.io/install | sh
sudo hookci connect hc_pair_EXAMPLE

connect does these things in order:

1. Sends the token and your host details (hostname, OS, architecture, agent version) to the hub and receives an agent id and a credential.
2. Writes the credential to agent.json under /var/lib/hookci, readable by root only.
3. Opens a connection to the hub to check that it accepts the credential.
4. Enables and starts the hookci-agent@ service for your installation. If the service is already running, it restarts it to use the new identity.

$ sudo hookci connect --name build-02 hc_pair_EXAMPLE
Connected to https://ci.webuno.io as build-02
$ sudo hookci doctor
(checks systemd, cgroups, the hookci-run user, and the path to the hub)

build-02 recording
$ sudo hookci connect --name build-02 hc_pair_EXAMPLE
Connected to https://ci.webuno.io as build-02
$ sudo hookci doctor
(checks systemd, cgroups, the hookci-run user, and the path to the hub)

Illustration. Pairing a second server under a chosen name. Output is shortened and the token is a placeholder.

Connect flags

connect refuses to overwrite an existing pairing unless you pass --force. When you give it a known state directory, it checks before redeeming the token, so a refusal does not use up the token.

Check that it is connected

• The hub page changes from “Waiting for your agent…” to “Agent connected”.
• In Slack, /hookci status lists each agent as online or offline with its version and when it was last seen.
• On the server, use systemctl list-units 'hookci-agent@*' to find the service and journalctl -u 'hookci-agent@*' -f to follow its log.

Several agents

Each server you pair is a separate agent with its own credential. How many agents an installation can have depends on your plan; see Pricing.

Repository work goes to the agent the repository is bound to:

• The first agent you pair is bound to every repository in the installation for checks.
• Later agents are not bound automatically. Bind them with /hookci bind.

/hookci bind acme/web build-02
/hookci bind acme/api build-02 checks

/hookci bind <owner/repo> <agent> [checks|deploy:<env>] needs admin access to the repository. The target defaults to checks. Use the agent id if two agents share a name. Each repository and target pair has one agent, and a new bind replaces the old one. Only active agents of the same installation can be bound.

If no agent is bound to a repository, the aggregate check is “action required” and says that no agent runs checks for it. If the bound agent is offline, runs wait for it. See GitHub Checks.

Revoke an agent

Revoke an agent when you retire a server or suspect that its credential leaked.

1. Open the HookCI App Home in Slack.
2. Under Agents, click Revoke next to the agent and confirm.

The agent stops running checks at once and its runs are interrupted. The agent exits with code 3, and the systemd unit does not restart it. The credential no longer works. To use the same server again, pair it with a new token and --force.

Upgrade and remove

When an agent runs an older version than the hub offers, App Home shows “upgrade available” with the command to use:

sudo hookci upgrade

To remove an agent completely, see Upgrade and uninstall, then revoke it in App Home so the hub forgets the credential.

When pairing fails

More in Troubleshooting.