CI Integration | Specwright
Description: AI-native enterprise documentation platform. Living specs, agent-maintained docs, repo-native knowledge.

Skip to content

# CI Integration ​

Add Specwright validation to your CI/CD pipeline to catch spec drift before it reaches production.

## GitHub Actions ​

### Spec Lint ​

Validate spec format and frontmatter in pull requests:

yaml

    name: Spec Lint

    on:
      pull_request:
        paths:
          - "docs/specs/**"
          - "SPECWRIGHT.yaml"

    jobs:
      lint:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4

          - uses: astral-sh/setup-uv@v4
            with:
              version: "latest"

          - run: uv run specwright lint docs/specs/

### Coverage Gate ​

Block merges when spec coverage drops below a threshold:

yaml

    name: Spec Coverage

    on:
      pull_request:
        branches: [main]

    jobs:
      coverage:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4

          - uses: astral-sh/setup-uv@v4
            with:
              version: "latest"

          - name: Check spec coverage
            run: uv run specwright coverage --min 60

### Config Validation ​

Validate `SPECWRIGHT.yaml` syntax:

yaml

    name: Config Check

    on:
      pull_request:
        paths:
          - "SPECWRIGHT.yaml"

    jobs:
      validate:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4

          - uses: astral-sh/setup-uv@v4
            with:
              version: "latest"

          - run: uv run specwright validate-config

## What Gets Validated ​

### Spec Lint ​

The `specwright lint` command checks:

- Valid YAML frontmatter (required fields: `title`, `status`)
- Valid status values (`draft`, `todo`, `in_progress`, `done`, `blocked`, `deprecated`)
- Section numbering consistency
- Acceptance criteria format (checkbox syntax)
- Status comment syntax (`<!-- specwright:system:... -->`)

### Config Validation ​

The `specwright validate-config` command checks:

- Valid YAML syntax
- Known configuration keys (warns on unknown keys)
- Valid `doc_paths` glob patterns
- Valid ticket system names and project keys

## Combining with Existing CI ​

Add spec checks alongside your existing test and lint jobs:

yaml

    name: CI

    on:
      pull_request:
        branches: [main]

    jobs:
      check:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: astral-sh/setup-uv@v4

          - run: uv sync --extra dev
          - run: uv run ruff check
          - run: uv run pytest
          - run: uv run specwright lint docs/specs/