Quickstart: the merge gate in CI (GitHub Action)
Add a merge gate for AI-written code to any repo with an OpenAPI spec or JSON Schema. On every pull request, delimit-ai/delimit-action diffs the spec against the base branch and posts a PR comment with breaking-change classification, semver impact, migration guidance, and a signed, replayable attestation.
Advisory by default. It comments; it never fails your build until you flip it to enforce.
Minimal setup
Zero config — the action auto-detects openapi.yaml / swagger.json in common locations:
- uses: delimit-ai/delimit-action@v1
Full workflow, with an explicit spec path:
name: API Contract Check
on: pull_request
jobs:
delimit:
runs-on: ubuntu-latest
permissions:
pull-requests: write # post the PR comment
id-token: write # sign the attestation (Sigstore keyless)
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: delimit-ai/delimit-action@v1
with:
spec: api/openapi.yamlOr generate a workflow from your repo directly:
npx delimit-cli ci
What lands on the PR
A single comment (updated in place on later pushes):
Breaking API Changes Detected
| Severity | Change | Location |
|---|---|---|
| Critical | endpoint removed | DELETE /pets/{petId} |
| High | type changed (string -> integer) | /pets:GET:200[].id |
Semver: MAJOR · Migration guide: per-change fix steps (collapsed)
Signed attestation — ID, Rekor transparency-log entry, and a delimit.ai/att/<id> permalink any reviewer can verify without trusting the runner.
Plus a governance-gates table (lint, policy, security, deploy readiness), a deterministic secret scan on changed files, and GitHub annotations on violations.
Inputs
| Input | Default | Notes |
|---|---|---|
| spec | auto-detect | Spec path; base-branch version fetched automatically (needs a pull_request event) |
| old_spec / new_spec | — | Explicit pair for advanced setups or non-PR triggers |
| mode | advisory | enforce fails CI on breaking changes |
| fail_on_breaking | false | Boolean alias for mode: enforce |
| policy_file | — | Custom rules, e.g. .delimit/policies.yml |
| attestation | true | Sigstore keyless signing; no-ops gracefully without id-token: write |
| context_aware_severity | false | Opt-in direction-aware severity (e.g. required field added to a response treated as non-breaking) |
| generator_command / generator_artifact | — | Detect drift between a schema generator and its committed output |
| webhook_url | — | Slack/Discord notification on breaking changes |
| github_token | ${{ github.token }} | Token for the PR comment |
Outputs include breaking_changes_detected, semver_bump, attestation_url, and the full JSON report — usable in downstream steps.
Turning on enforcement
When you're ready for the gate to actually gate:
- uses: delimit-ai/delimit-action@v1
with:
spec: api/openapi.yaml
mode: enforceEnforce mode fails CI on breaking changes and on leaked secrets in changed files. Everything else is unchanged.
Notes and limitations
- Fork PRs: GitHub gives fork PRs a read-only token by design, so the comment can't post — the full report is written to the run's Job Summary instead. A
permissions:block cannot override this. - Supported formats: OpenAPI 3.0/3.1, Swagger 2.0, JSON Schema — YAML or JSON. No API keys or external services required.
- Supply-chain-sensitive pipelines:
@v1is a floating tag. Pin the commit SHA and bump on review:
- uses: delimit-ai/delimit-action@<commit-sha>