GitHub Actions

Use the official ContractHQ GitHub Action to automatically validate data contracts on every pull request. Violations block the merge and the built-in PR bot posts a detailed comment explaining what broke and how to fix it.

How It Works

Step 1 — Add the Repository Secret

Generate a ContractHQ API key with validations:run scope and add it to your GitHub repository:

1. Go to Repository → Settings → Secrets and variables → Actions.
2. Click New repository secret.
3. Name it CONTRACTHQ_TOKEN.
4. Paste your API key and save.

Step 2 — Add the Workflow File

Create .github/workflows/contracthq.yml in your repository:

name: Contract Validation

on:
  pull_request:
    paths:
      - 'contracts/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write  # needed for PR bot comments
    steps:
      - uses: actions/checkout@v4

      - name: Validate Data Contracts
        uses: contracthq/action@v2
        with:
          token: ${{ secrets.CONTRACTHQ_TOKEN }}
          contracts-path: contracts/
          post-comment: true
          fail-on-error: true

Action Inputs Reference

Example PR Bot Comment

Enforcing with Branch Protection

To hard-block merges on contract failures, add the workflow check to your branch protection rules:

1. Go to Repository → Settings → Branches.
2. Edit the protection rule for main (or master).
3. Under Require status checks to pass, search for validate.
4. Enable Require branches to be up to date and save.