Setup

This guide adds two GitHub Actions workflows: one that runs on pull requests to detect breaking changes, and one that handles automated versioning when changes land on main.

---

Prerequisites

Before setting up the GitHub Action, the following are required:

• A repository with at least one spec file (OpenAPI or JSON Schema)
• A contractual.yaml at the repository root
• A .contractual/ directory with at least one snapshot

If those steps are not complete, follow the Quickstart first and commit the resulting files.

Tip

Commit contractual.yaml, .contractual/snapshots/, and .contractual/versions.json to the repository. Do not commit .contractual/changesets/; the Action generates those automatically.

---

Step 1: Create the PR check workflow

Create .github/workflows/contractual-pr.yml:

.github/workflows/contractual-pr.yml

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 }}

Note

The fetch-depth: 0 option is required so Contractual can compare specs against snapshots. The ref: ${{ github.head_ref }} ensures changesets are committed to the PR branch.

---

Step 2: Create the release workflow

Create .github/workflows/contractual-release.yml:

.github/workflows/contractual-release.yml

name: Contractual Release
on:
push:
branches: [main]
paths:


’.contractual/changesets/**’

permissions:
contents: write
pull-requests: write
jobs:
contractual-release:
name: Version contracts
runs-on: ubuntu-latest
steps:


name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0


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

---

Step 3: Commit and push

git add .github/workflows/contractual-pr.yml
git add .github/workflows/contractual-release.yml
git commit -m "chore: add contractual workflows"
git push

---

Step 4: Test with a PR

Create a branch, edit a spec file, and open a pull request:

git checkout -b feat/update-order-schema
# edit a spec file...
git add schemas/order.schema.json
git commit -m "feat: change amount field type"
git push -u origin feat/update-order-schema

The Contractual PR Check workflow will:

1. Run contractual lint to validate schemas
2. Run contractual breaking to compare against the snapshot
3. Post a comment with a diff table
4. Commit a changeset file to the PR branch

---

Step 5: Complete the release

When the PR merges, the changeset lands on main and triggers the release workflow. It:

1. Reads all pending changesets
2. Bumps version numbers
3. Updates snapshots and changelogs
4. Opens a “Version Contracts” pull request

Merge that PR to complete the release. The action then:

1. Creates a git tag for each bumped contract (e.g., orders-api@2.0.0)
2. Creates a GitHub Release with release notes
3. Attaches the spec file as a release asset

See Release Automation for configuration options.

Tip

Multiple PRs can merge between releases. Contractual batches all changesets. If one is minor and another is major, the contract gets a major bump.

---

Required permissions

Permission	Level	Purpose
contents	write	Commit changesets and version bumps
pull-requests	write	Post PR comments and create Version PR

---

Next steps

PR Checks

Configure pr-check mode behavior.

View Guide

Release Automation

Configure release mode and Version PRs.

View Guide