GitHub Actions Integration

Sigil’s GitHub Actions integration evaluates a pull request, compares it with the baseline, posts a status check, and can enqueue safe PRs when the service is in auto mode and has earned enough trust.

What it does

sigil ci owner/repo#42 --service api --comment --auto-merge

The command runs:

1. sigil eval against the PR ref and merge-base baseline.
2. sigil decide to resolve ALLOW, REVIEW, or BLOCK.
3. A GitHub commit status with a link to the eval report.
4. Optional lossy PR feedback for the authoring agent.
5. Optional merge queue enqueue on ALLOW. Only auto mode can ALLOW, and only once the service has earned MEDIUM trust (see Trust Model).

Minimal workflow

name: sigil
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  evaluate:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      statuses: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install sigil
        run: curl -fsSL https://runsigil.com/install.sh | sh
      - name: Evaluate
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AGE_KEY: ${{ secrets.SIGIL_AGE_KEY }}   # age identity that decrypts holdouts
        run: |
          sigil ci ${{ github.repository }}#${{ github.event.pull_request.number }} \
            --service api \
            --comment \
            --auto-merge

Required permissions

Permission	Why
contents: read	Checkout and resolve refs.
statuses: write	Publish the Sigil decision as a commit status.
pull-requests: write	Post optional lossy feedback comments.

Branch protection

Require the sigil/<service> status check on protected branches after the service has been calibrated. While a service is still in shadow mode, use Sigil as a non-blocking signal and compare decisions with human review outcomes. Shadow is also where a new service earns its first trust level.

Since 0.36.0 a PR that changes Sigil’s own inputs (.sigil/, scenarios/, .github/, action.yml, or CODEOWNERS) always REVIEWs with governance_files_changed. Protect the same paths with CODEOWNERS so those PRs get a security review.

Troubleshooting

Symptom	Check
No status appears	Confirm statuses: write permission and the ref passed to sigil ci.
PR comment fails	Confirm pull-requests: write permission.
Holdouts do not run, or REVIEW says scenarios_not_loaded	Confirm the age identity is exposed as AGE_KEY (or AGE_KEY_FILE). Since 0.36.0 an eval whose holdouts did not load cannot ALLOW.
Merge queue does not enqueue	Confirm the service is in auto mode, has earned MEDIUM trust (sigil trust history), and branch protection allows queue enqueue.
Status reads sigil: decide failed, needs review	sigil decide errored (no ledger, git error, OPA error). sigil ci fails closed; the JSON report carries decide_error.

For setup help, email info@runsigil.com with the workflow file, Sigil version, and sanitized command output.

More detail

Read the full CI Integration guide for config options and command flags.