ci-gate.mdx

title	CI gate with the GitHub Action
tag	CI / CD
steps	5
minutes	7
pillars	integrate
description	Block merges when specs drift from code.
order	3

Add the specsync GitHub Action to your workflow and any pull request that introduces spec drift will fail the check — before it merges.

1. Add the action

# .github/workflows/spec-sync.yml
name: specsync check
on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: CorvidLabs/spec-sync@v6.0.0

The action installs specsync, runs specsync check --strict, and annotates any drift directly in the PR diff view.

2. Pin the spec-sync version

Pin the immutable release while validating 6.0.0 so an unintended upstream change cannot break a Friday-afternoon merge:

- uses: CorvidLabs/spec-sync@v6.0.0
  with:
    version: '6.0.0'

The Action follows the spec-sync release cadence — match the version you cargo install locally.

3. Tune the failure threshold

By default, --strict fails on any warning. For teams onboarding spec-sync incrementally, you can start with errors-only:

- uses: CorvidLabs/spec-sync@v6.0.0
  with:
    version: '6.0.0'
    strict: false        # warnings allowed; errors still fail
    score_threshold: 60  # also fail if any spec scores below 60

Drop strict: false once your team is happy with the warning count, and tighten score_threshold as your spec quality improves.

4. Surface drift as PR review comments

Add annotations: true so drift errors render as inline GitHub PR review comments on the source line, not just in the Action log:

- uses: CorvidLabs/spec-sync@v6.0.0
  with:
    version: '6.0.0'
    annotations: true

A PR that adds an undocumented export now shows the comment "undocumented export delete_user — add to specs/api/users.spec.md or run specsync check --fix" pointing at the relevant line. No need to dig through Action logs.

5. Bypass for emergency hotfixes

When you genuinely need to ship a fix without updating the spec (and you're not lying to yourself), opt out per-PR with a label:

- uses: CorvidLabs/spec-sync@v6.0.0
  with:
    version: '6.0.0'
  if: ${{ !contains(github.event.pull_request.labels.*.name, 'skip-specsync') }}

The label adds friction (you have to consciously apply it) without being a hard block. Track the labels — if skip-specsync shows up more than twice a month, the team probably wants a real workflow change, not an escape hatch.