Skip to Content

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`)
ResultExit code
File is up to date0
File is out of date or missing1
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. Store HEADQUERY_BASE_URL and HEADQUERY_SCHEMA_TOKEN as CI secrets. The config written by init reads both from the environment, and real env vars take precedence over .env files.
  • File (from: "./schema.json"): CI needs no CMS access. The check proves that the generated types match the committed schema.json, but not that schema.json matches 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).

.github/workflows/cms-types.yml
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.

.github/workflows/cms-types-sync.yml
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.

.gitlab-ci.yml
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_BRANCH

CI/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:

.gitlab-ci.yml
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.

Last updated on