PR Checks

In pr-check mode, the action runs on pull requests to detect breaking changes, post diff tables, and generate changesets.

What happens on each PR

The Action checks out the branch at the latest commit
contractual lint validates every contract
contractual breaking compares each spec against its snapshot
A PR comment is posted with a diff table
A changeset file is generated and committed to the PR branch
If fail-on-breaking: true and breaking changes are found, the check fails

Workflow

name: Contractual PR Check

on:
  pull_request:
    paths:
      - 'specs/**'
      - 'schemas/**'
      - 'contractual.yaml'

permissions:
  contents: write
  pull-requests: write

jobs:
  contractual-check:
    name: Check contracts
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ github.head_ref }}

      - name: Run Contractual
        uses: contractual-dev/action@v1
        with:
          mode: pr-check
          github-token: ${{ secrets.GITHUB_TOKEN }}

Inputs

Input	Description	Default
`mode`	Must be `pr-check`
`github-token`	Token for PR comments and commits	`${{ github.token }}`
`config-path`	Path to `contractual.yaml`	`./contractual.yaml`
`fail-on-breaking`	Fail if breaking changes detected	`true`
`auto-changeset`	Auto-generate changeset if missing	`true`
`anthropic-api-key`	Anthropic API key for AI explanations

Outputs

Output	Description
`has-breaking`	`'true'` if breaking changes detected
`has-changes`	`'true'` if any spec changes detected
`changeset-created`	`'true'` if a changeset was committed

Customization

Allow breaking changes without failing

- uses: contractual-dev/action@v1
  with:
    mode: pr-check
    fail-on-breaking: false

Use the output for conditional logic:

- uses: contractual-dev/action@v1
  id: check
  with:
    mode: pr-check
    fail-on-breaking: false

- name: Warn on breaking
  if: steps.check.outputs.has-breaking == 'true'
  run: echo "::warning::Breaking changes detected"

Disable auto-changeset

- uses: contractual-dev/action@v1
  with:
    mode: pr-check
    auto-changeset: false

Enable AI explanations

Add the Anthropic API key to get AI-powered change explanations:

- uses: contractual-dev/action@v1
  with:
    mode: pr-check
    anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

Go to Settings > Secrets and variables > Actions
Add ANTHROPIC_API_KEY with the key

Path filtering

Use paths filters to run only when relevant files change:

on:
  pull_request:
    paths:
      - 'specs/**'
      - 'schemas/**'
      - 'contractual.yaml'

For monorepos:

on:
  pull_request:
    paths:
      - 'services/orders/specs/**'
      - 'services/orders/contractual.yaml'

Forked PR limitations

GitHub does not allow fork PRs to have write permissions by default. Options:

Use pull_request_target: runs with base branch permissions (use with caution)
Require contributors to create a branch on the upstream repo
Disable auto-changeset for forks:

- uses: contractual-dev/action@v1
  with:
    mode: pr-check
    auto-changeset: ${{ github.event.pull_request.head.repo.fork == false }}

Next steps

Setup: Initial workflow setup
Release Automation: Configure release mode