Skip to content

Run cikick check in CI

You will add a workflow that runs npx cikick check on every pull request and push to main, so generated workflows and cikick.lock.json can never be out of date or violate policy on the default branch. The workflow is itself defined with a cikick construct and synthesized like any other.

  1. Discovers shared packages and loads cikick.config.ts, registering the checks the packages ship.
  2. Synthesizes in frozen mode: every non-SHA action ref must already have an entry in cikick.lock.json; nothing is resolved over the network.
  3. Compares the result with the files on disk. Any generated file whose content differs, or that is missing, is reported as drift: <path>. cikick.lock.json is included, so a stale recorded package version is drift too. seeded files only count as drift when missing.
  4. Runs all checks (stock ones from @cikick/policies plus any shipped by packages) and prints findings.
  5. Writes nothing to disk.

Exit code 0 when there is no drift and no error findings; 1 otherwise. warn and info findings are printed but do not fail the command, until a check’s enforceAfter date passes and its warnings become errors.

Output format:

drift: .github/workflows/ci.yml
drift: cikick.lock.json
ERROR [no-pull-request-target-checkout] .github/workflows/pr.yml: job "build" checks out PR head code in a pull_request_target workflow (privileged context)
WARN [@acme/wf-node-ci:nvmrc-min-node] .nvmrc: Node 18 is end-of-life; set nodeVersion >= 20 in NodeCi
Generated files are out of date. Run `npx cikick synth` and commit.

The last line goes to stderr and only appears when there is drift.

Add this to cikick.config.ts (inside your default export function, with Workflow imported from @cikick/core):

cikick.config.ts
import { Workflow, type App } from '@cikick/core';
export default (app: App) => {
// ... your other workflows ...
const check = new Workflow(app, 'cikick-check', {
name: 'cikick check',
on: { push: { branches: ['main'] }, pullRequest: {} },
permissions: { contents: 'read' },
});
const job = check.addJob('check', { runsOn: 'ubuntu-latest', timeoutMinutes: 10 });
job.addStep({ uses: 'actions/checkout@v4' });
job.addStep({ uses: 'actions/setup-node@v4', with: { 'node-version': 22, cache: 'npm' } });
job.addStep({ name: 'Install', run: 'npm ci' });
job.addStep({ name: 'cikick check', run: 'npx cikick check' });
};

Use your own package manager commands if you do not use npm (the example consumer uses pnpm: add a pnpm/action-setup@v4 step before setup-node, cache: pnpm and pnpm install --frozen-lockfile).

Terminal window
npx cikick synth
wrote .github/workflows/cikick-check.yml
wrote cikick.lock.json

(Plus any other files your config generates.) Commit the new workflow and the updated lockfile. Resulting YAML (the SHAs are the ones recorded in the example consumer’s lockfile; yours will be whatever the refs resolved to when you ran synth):

.github/workflows/cikick-check.yml
# Generated by cikick — do not edit. Run `npx cikick synth`.
name: cikick check
on:
push:
branches:
- main
pull_request: {}
permissions:
contents: read
jobs:
check:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
with:
node-version: 22
cache: npm
- name: Install
run: npm ci
- name: cikick check
run: npx cikick check

Then make the job a required status check in your branch protection or ruleset (the check name is the job’s: check).

  • contents: read is all the job needs. It uses no secrets and no GITHUB_TOKEN API calls.
  • Frozen mode means check never calls git ls-remote or the GitHub API, so it works from locked-down runners as long as npm ci can reach your registry.
  • cikick check executes your cikick.config.ts and the cikick entry module of every shared package in node_modules. Run it on pull_request (as above), not on pull_request_target, so code from forks does not run with elevated permissions.
Message Meaning Fix
drift: <path> followed by “Generated files are out of date. Run npx cikick synth and commit.” The file on disk differs from what config + packages + lock generate (hand edit, forgotten re-synth, or a changed package version in the lock). Run npx cikick synth locally and commit the changes.
“cikick.lock.json is missing entries (frozen mode): actions/checkout@v5. Run npx cikick lock and commit the result.” A construct references a ref that has no lock entry. Run npx cikick synth (resolves the ref, rewrites workflows and lock) and commit. npx cikick lock also works but only writes the lockfile.
ERROR [<check-id>] <path>: <message> A check with severity error fired (or a warn passed its enforceAfter date). Fix the cause named in the message; the message usually says how. Re-run npx cikick check.
“No cikick.config.ts (or .js/.mjs) found in . Run npx cikick init.” Wrong working directory. Run from the repository root or pass --dir.

Note the first row: if the only problem is an ERROR finding and not drift, the “out of date” line is not printed, but the exit code is still 1.

Checks have a severity. ERROR findings fail the build immediately. WARN findings are printed and the command still exits 0. A check can carry enforceAfter: '<ISO date>': once the current time is later than that date, its warn findings are reported as ERROR. Package authors use this to give consumers time to migrate. Stock checks from @cikick/policies: require-pinned-actions, require-explicit-permissions, no-pull-request-target-checkout (errors); no-script-injection, require-timeout (warnings). See Checks and the policies reference.

Because warnings are easy to miss in CI logs, read the check output when the date for an enforceAfter approaches, or grep the log for WARN.

These are suggestions, not cikick features. Add the scripts the cikick init output suggests:

package.json
{
"scripts": {
"cikick:synth": "cikick synth",
"cikick:check": "cikick check"
}
}

and, if you use git hooks, a pre-commit or pre-push hook that runs npm run cikick:check. check needs no network and writes nothing, so it is safe to run frequently. A hook that runs cikick synth instead will rewrite files and may need network access for new action refs.

Check passes locally, fails in CI with drift. CI is running with different installed versions (for example a different shared package version than your lockfile of record) or the generated files were not committed. Run npm ci locally and re-run npx cikick check. Commit the output of synth.

Lock drift right after a Renovate bump. cikick.lock.json records the package version from the last synth. If Renovate bumped a package without running cikick update, the recorded version differs from the installed one. Run npx cikick update and commit; see Renovate setup.

Line endings or formatting differences. Comparison is exact string equality with the generated content. Do not run a formatter (Prettier, editorconfig auto-fix) over .github/workflows/*.yml, cikick.lock.json or other generated files; exclude them from formatting.

--dir. All commands take --dir <repo> if the repository is not the working directory. Command reference: cikick CLI.