ShipGauge

GitHub Gate

Require the ShipGauge Gate check before merge

ShipGauge creates a check run named ShipGauge Gate that you can require on your default branch.

1. Workflow permissions

permissions:
  contents: read
  pull-requests: write
  checks: write

The composite Action enables --status-check by default.

2. Secrets

Repository secrets:

  • SHIPGAUGE_API_KEY
  • SHIPGAUGE_PROJECT_ID

Optional: SHIPGAUGE_BASE_URL for self-hosted.

3. Branch protection

  1. Repository → Settings → Branches → Branch protection rules
  2. Protect main (or your default branch)
  3. Enable Require status checks to pass before merging
  4. Select ShipGauge Gate (exact spelling)
  5. Save

PR comments

The CLI updates an existing ShipGauge comment on re-runs (marker <!-- shipgauge-gate -->) instead of spamming new comments. Needs pull-requests: write.

Bypass label

In .shipgauge/gate.yml:

bypass_label: shipgauge-skip

Add that label on a PR to pass the check with a bypass note (use sparingly).

First run

Without a baseline, the first CI run usually saves baseline and reports success.

Troubleshooting

IssueFix
Check never appearsAdd checks: write
Check not selectableRun the workflow once so the check name exists
Failed to create required check runVerify GITHUB_TOKEN + GITHUB_SHA
No PR commentExpected on non-PR events; need pull-requests: write

Next