CI
Commit the generated types and let CI check that they match the CMS. --check regenerates
the file in memory and compares it with the committed one. It writes nothing:
npx headquery generate --check # or: npm run cms:types:check (added by `headquery init`)| Result | Exit code |
|---|---|
| File is up to date | 0 |
| File is out of date or missing | 1 |
| Schema can’t be loaded (CMS down, wrong token, …) | 1 |
When the check fails, run npm run cms:types locally and commit the result.
Where CI gets the schema
CI uses the same schema source as your config file:
- Endpoint (
from: { baseUrl }): CI fetches the schema from a running CMS, usually staging or production. StoreHEADQUERY_BASE_URLandHEADQUERY_SCHEMA_TOKENas CI secrets. The config written byinitreads both from the environment, and real env vars take precedence over.envfiles. - File (
from: "./schema.json"): CI needs no CMS access. The check proves that the generated types match the committedschema.json, but not thatschema.jsonmatches the CMS. To check that as well, see Checking an exported schema file.
The templates below use the endpoint. With a file source, leave out the env/variables
blocks.
GitHub Actions
Runs on pushes and pull requests. Add HEADQUERY_BASE_URL and HEADQUERY_SCHEMA_TOKEN under
Settings → Secrets and variables → Actions. HEADQUERY_BASE_URL isn’t secret, so you can
also store it as a variable (vars.HEADQUERY_BASE_URL).
npm
name: CMS types
on:
push:
branches: [main]
pull_request:
jobs:
check:
runs-on: ubuntu-latest
# Secrets aren't passed to pull requests from forks.
if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run cms:types:check
env:
HEADQUERY_BASE_URL: ${{ secrets.HEADQUERY_BASE_URL }}
HEADQUERY_SCHEMA_TOKEN: ${{ secrets.HEADQUERY_SCHEMA_TOKEN }}If the check already runs inside your existing CI workflow, add only the last step.
Keep the types in sync automatically
Editors change blueprints in the CMS without touching the frontend repo. A scheduled job catches that drift: it regenerates the types against production and opens a pull request when they changed.
name: Sync CMS types
on:
schedule:
- cron: "0 6 * * 1-5" # weekdays at 06:00 UTC
workflow_dispatch:
permissions:
contents: write
pull-requests: write
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run cms:types
env:
HEADQUERY_BASE_URL: ${{ secrets.HEADQUERY_BASE_URL }}
HEADQUERY_SCHEMA_TOKEN: ${{ secrets.HEADQUERY_SCHEMA_TOKEN }}
- uses: peter-evans/create-pull-request@v7
with:
branch: cms-types
title: "chore: update CMS types"
commit-message: "chore: update CMS types"
body: The content model in the CMS changed. Review the diff of the generated types.The action does nothing if the file didn’t change, and updates its open pull request instead of opening a new one. The diff shows exactly which fields changed, and the pull request’s CI run type-checks your code against the new types.
Pull requests created with the default GITHUB_TOKEN don’t trigger other workflows. To run
your CI on them, pass a personal access token or a GitHub App token to the action’s token
input. Repositories may also need Allow GitHub Actions to create and approve pull
requests under Settings → Actions → General.
To only get notified instead, run npm run cms:types:check in the scheduled job: a failed run
sends the usual GitHub notification.
GitLab CI
Runs in merge request pipelines and on the default branch. Add HEADQUERY_BASE_URL and
HEADQUERY_SCHEMA_TOKEN under Settings → CI/CD → Variables; mark the token as
Masked.
npm
cms-types:
image: node:22
cache:
key:
files: [package-lock.json]
paths: [.npm/]
script:
- npm ci --cache .npm --prefer-offline
- npm run cms:types:check
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCHCI/CD variables are available to every job as env vars, so the job needs no variables:
block.
Variables marked Protected are only available on protected branches and tags. If you protect the token, merge request pipelines from unprotected branches get no token and fail with 401. Either leave it unprotected or limit the job to protected branches.
Scheduled drift check
Create a schedule under Build → Pipeline schedules and add a job that only runs there:
cms-types-drift:
image: node:22
script:
- npm ci
- npm run cms:types:check
rules:
- if: $CI_PIPELINE_SOURCE == "schedule"A failed scheduled pipeline notifies its owner. To check production instead of the default
CMS, override HEADQUERY_BASE_URL in the schedule’s variables.
Checking an exported schema file
If the frontend lives in the same repo as the CMS and reads schema.json, CI can export a
fresh schema and check the committed types against it with --from. That catches a
schema.json that wasn’t re-exported after a blueprint change. It needs a working CMS install
in CI. For Statamic (GitHub Actions):
- uses: shivammathur/setup-php@v2
with:
php-version: "8.3"
- run: composer install --no-interaction --no-progress
working-directory: cms
- run: php please headquery:schema --out="$RUNNER_TEMP/schema.json"
working-directory: cms
- run: npm ci
- run: npx headquery generate --check --from "$RUNNER_TEMP/schema.json"Adjust the cms directory to your layout. Don’t compare the exported file with git diff:
it contains a generatedAt timestamp, so it changes on every export.
Monorepos
Run the check in the package that has headquery.config.ts, e.g. with
working-directory: apps/web on the step (GitHub) or cd apps/web in the script (GitLab).
Relative paths in the config resolve against the config file, not against the working
directory.