Configuration: Trust and forks

Configuration

Trust and forks

Decide which pull requests may run code on your server, and how approval works.

A pull request can change .hookci.yml and your scripts, so running it means running its author’s code on your machine. Two settings decide who gets that: checks.trust and checks.forks.

checks:
  trust: collaborators   # collaborators | approve | all
  forks: gated           # gated | never

Settings

Setting Value Meaning
trust collaborators Runs pull requests from repo collaborators only.
trust approve Every pull request waits for an Approve click.
trust all Runs everything. Not recommended for public repos.
forks gated Pull requests from forks need approval.
forks never Pull requests from forks are ignored.

Outcomes

Outcome by pull request author and setting. “Approval” means the run waits until someone clicks Approve run.

trust forks Collaborator PR Fork PR
collaborators gated Runs Waits for approval
collaborators never Runs Ignored
approve gated Waits for approval Waits for approval
approve never Waits for approval Ignored
all gated Runs Waits for approval
all never Runs Ignored

The Approve run flow

When a run needs approval, HookCI does not start it. The Slack message shows the run as awaiting with an Approve run button.

Illustration. A run held for approval. Nothing executes on your agent until someone clicks Approve run.
  1. A pull request arrives from a fork (or any PR under trust: approve).
  2. The hub posts the run to your Slack channel in the awaiting state. The GitHub check stays pending.
  3. A reviewer reads the diff on GitHub, paying attention to changes in .hookci.yml, scripts, and dependency files.
  4. The reviewer clicks Approve run. The hub then routes the job to your agent.

If you never approve, the run never starts. Approving applies to that run; new commits pushed to the pull request need review again.

Recommendations for public repos

  • Use trust: collaborators with forks: gated, or forks: never if you do not need outside contributions checked.
  • Do not use trust: all on a public repository.
  • Keep checks.egress short so a malicious script cannot send data to arbitrary hosts. See Isolation and egress.
  • Do not run --isolation none on a host that checks public pull requests.
  • Use a dedicated machine or VM for the agent. It should hold no credentials you would mind losing.
  • Put real secrets only in jobs that run for trusted code, and list them in redact.
  • Review changes to .hookci.yml before approving: it controls egress hosts and limits.

Related: reference, Slack.