Hosted: GitHub Checks

Hosted

GitHub Checks

The permissions HookCI asks for, the check runs it writes on each commit, how annotations work, and what each action required state means.

HookCI reports to GitHub through the Checks API. It does not use commit statuses. Every run shows up on the pull request and on the commit page as check runs you can require in branch protection.

Illustration. One aggregate check, one check per job, and annotations on the lines that failed.

Permissions

The HookCI GitHub App asks for the least it needs to read repository metadata and write checks.

Permission Access Why
Checks Write Create and update check runs and annotations.
Contents Read Let the agent clone with a short-lived token, and read .hookci.yml.
Pull requests Read See pull request events, the base and head of each PR, and whether it comes from a fork.
Metadata Read List the repositories the installation can see.
Members Read Check that a person who approves a run or binds an agent has the access they claim.

The App subscribes to these events: pull_request, push, check_suite, check_run, and installation_repositories.

The hub never receives your source code from GitHub. The agent clones the repository itself, on your server.

Check runs per commit

Check run Appears when What it shows
hookci Every run The aggregate result of all jobs. Its summary lists each job with its state and duration.
hookci/<job> Each job in the run The job’s current step, result, and annotations. Titles read “Running: “ followed by the step name, with “Step 2 of 5”, then “Took 1m 20s” when done.
hookci/config .hookci.yml exists Always neutral. Titled “Checking .hookci.yml”, then “.hookci.yml is valid” or “.hookci.yml has errors” with the diagnostics.

Deploys do not create check runs. See Deploys.

Aggregate result

Jobs hookci conclusion Title
Any job failed Failure “Failed: lint, test” (the failed job names)
Every job succeeded or was skipped Success The summary lists the jobs
Anything else, such as a stopped run Cancelled The summary says why

When a new commit replaces a run that is still going, the old run is cancelled with “A newer commit replaced this run.”

Annotations

Annotations put a message on a file and line in the pull request diff. A job produces them when you set annotate on it:

version: 1
checks:
  jobs:
    lint:
      run: npx eslint .
      annotate: eslint
    types:
      run: npx tsc --noEmit
      annotate: tsc

The agent parses the output of eslint or tsc and sends the findings to the hub. The hub forwards them to GitHub in batches of 50. A job can show up to 500 annotations. Past that, the check says “Only the first N annotations are shown.”

See .hookci.yml reference for every option on a step.

When the check says action required

Some conditions stop a run before it starts. The aggregate hookci check then ends as “Action required” with a title that names the cause.

Cause What you see Fix
Agent offline The agent has not been seen for 10 minutes. The run starts when it reconnects. On the server, run sudo hookci doctor, then systemctl list-units 'hookci-agent@*'.
No agent paired No agent runs checks for the repository. Pair one at ci.webuno.io/start, or bind one with /hookci bind. See Pair an agent.
Daily run limit reached The installation used its runs for the day. The limit resets at 00:00 UTC. Wait for the reset or change plan. Limits are on Pricing.
Waiting for approval The pull request comes from a fork. Someone with write access approves it. See below.
Fork pull requests disabled The config sets forks: never. Change the policy in .hookci.yml on the base branch.
Installation suspended GitHub suspended the App installation. Unsuspend it in GitHub settings.
No checks detected There is no .hookci.yml and no detectable project files. Add a .hookci.yml or run hookci init.

Fork pull requests

Code from a fork can change what the checks do, so HookCI does not run it without a person’s approval. The check reads “Waiting for approval” and has an Approve run button. The same button appears on the run message in Slack.

  • Approving needs write access to the repository.
  • An approval is for one commit of one pull request. If the author pushes again, the old approval no longer counts and the new commit waits.
  • Retrying a fork run is a new attempt and needs its own approval.
  • On the shared hosted hub, trust: all is refused, so fork pull requests always stay gated.
  • The fork policy is read from .hookci.yml on the base branch, never from the fork. A missing file means “approve”.

The full model is in Trust and forks.

Retry a run

Use Slack. The /hookci retry command starts the next attempt on the bound agent:

/hookci retry acme/web
/hookci retry acme/web 4f9c2ab

The first form retries the latest run of the repository. The second retries that commit. You need write access to the repository. GitHub’s own Re-run button does not start a HookCI run. Its only action is Approve run on gated fork pull requests.

Branch protection

To block merges on a failing run, require the checks in the branch protection rule or ruleset.

  1. Open a pull request so HookCI reports once. GitHub lists a check as selectable only after it has reported.
  2. In Settings, Branches, add hookci to the required checks. To require one job, add hookci/<job> too, for example hookci/test.