Get started: Quickstart

Get started

Quickstart

Install the GitHub App, pair one Linux server as your agent, add HookCI to Slack, and see your first check on a pull request.

This guide uses the hosted hub at ci.webuno.io. By the end, a pull request on your repository runs its checks on your own server and reports them in GitHub Checks and Slack.

Before you start

  • A Linux server you control, amd64 or arm64, with systemd. It only needs outbound HTTPS to the hub, GitHub, and your package registries. No inbound ports, no SSH.
  • Owner or admin rights on the GitHub account or organization that owns the repository. Only an admin can pair an agent or add HookCI to Slack.
  • A Slack workspace where you can add apps. Enterprise Grid is not supported.
  • sudo on the server.

No .hookci.yml is required. The agent detects Node, Python, Go, Rust, and Docker Compose projects and builds a check list from the project files. See Run checks locally to preview what it detects.

Set it up

  1. Install the GitHub App. Open ci.webuno.io/start, choose Install on GitHub, and pick the account and repositories HookCI may read. GitHub returns you to a hub page that shows a pair token and the commands for your server.

    Illustration. The success page shows a one-time pair token, the install commands, and an Add to Slack button. The status line changes once an agent connects.

  2. Install the agent on your server. Run the install script. It verifies the checksum of the download, verifies the cosign signature if cosign is installed, and sets up the hookci-run user and the systemd units.

    curl -fsSL https://ci.webuno.io/install | sh

  3. Pair the agent. Redeem the token from the hub page. It works once and expires after 15 minutes.

    sudo hookci connect hc_pair_EXAMPLE

    connect saves the agent credential under /var/lib/hookci, checks that the hub accepts it, and starts the agent service. The hub page changes from “Waiting for your agent…” to “Agent connected”.

    build-01
    build-01 recording
$ curl -fsSL https://ci.webuno.io/install | sh
Downloading hookci_linux_amd64.tar.gz
Signature verified

Installed hookci. Next, pair this machine:
  sudo hookci connect <pair-token>
$ sudo hookci connect hc_pair_EXAMPLE
Connected to https://ci.webuno.io as build-01

    Illustration. Install and pair. Output is shortened and the token is a placeholder.

  4. Add HookCI to Slack. On the hub page choose Add to Slack and approve the app in your workspace. Then link your own Slack user to your GitHub account, so HookCI can check your permissions on a repository.

    /hookci me

    Click Link your GitHub account in the reply. The link works once and expires after 10 minutes.

  5. Watch a repository. Invite the bot to a channel, then tell it which repository to post there.

    /invite @hookci
/hookci watch acme/web

    HookCI posts a test message to confirm it can write to the channel. You need write access to the repository on GitHub.

    Illustration. Typing the watch command and the app's reply in a #ci channel.

  6. Open a pull request. Push a branch and open a PR. The hub adds a hookci check to the PR and sends the run to your agent.

    Illustration. The HookCI check on a pull request. Each job appears as its own check, and failures include file and line annotations.

    The same run appears in the Slack channel and is updated in place as jobs finish.

    Illustration. A run message from the @hookci app with one row per job and a link to the logs.

If nothing shows up

  • The hub page stays on “Waiting for your agent…”: run sudo hookci doctor on the server. It checks systemd, cgroups, the hookci-run user, and whether the hub is reachable on port 443.
  • connect says the token is invalid: tokens work once and expire after 15 minutes. Create a new one in Slack App Home with Add agent.
  • The PR check says “No agent paired” or “Agent offline”: the agent is not connected. See Pair an agent.
  • The PR check says “Waiting for approval”: the PR comes from a fork. Approve it as described in Trust and forks.
  • The PR check says “No checks detected”: the repository has no .hookci.yml and nothing the agent recognizes. Add a .hookci.yml.

More fixes are in Troubleshooting.

Where to go next