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.
What cikick check does
Section titled “What cikick check does”- Discovers shared packages and loads
cikick.config.ts, registering the checks the packages ship. - Synthesizes in frozen mode: every non-SHA action ref must already have an entry in
cikick.lock.json; nothing is resolved over the network. - 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.jsonis included, so a stale recorded package version is drift too.seededfiles only count as drift when missing. - Runs all checks (stock ones from
@cikick/policiesplus any shipped by packages) and prints findings. - 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.ymldrift: cikick.lock.jsonERROR [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 NodeCiGenerated files are out of date. Run `npx cikick synth` and commit.The last line goes to stderr and only appears when there is drift.
1. Define the workflow as a construct
Section titled “1. Define the workflow as a construct”Add this to cikick.config.ts (inside your default export function, with Workflow imported from @cikick/core):
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).
2. Synthesize and commit
Section titled “2. Synthesize and commit”npx cikick synthwrote .github/workflows/cikick-check.ymlwrote 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):
# Generated by cikick — do not edit. Run `npx cikick synth`.name: cikick checkon: push: branches: - main pull_request: {}permissions: contents: readjobs: 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 checkThen make the job a required status check in your branch protection or ruleset (the check name is the job’s: check).
Permissions and secrets
Section titled “Permissions and secrets”contents: readis all the job needs. It uses no secrets and noGITHUB_TOKENAPI calls.- Frozen mode means
checknever callsgit ls-remoteor the GitHub API, so it works from locked-down runners as long asnpm cican reach your registry. cikick checkexecutes yourcikick.config.tsand thecikickentry module of every shared package innode_modules. Run it onpull_request(as above), not onpull_request_target, so code from forks does not run with elevated permissions.
Failure messages and fixes
Section titled “Failure messages and fixes”| 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 |
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.
Warnings, errors and enforceAfter
Section titled “Warnings, errors and enforceAfter”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.
Optional: run it before you push
Section titled “Optional: run it before you push”These are suggestions, not cikick features. Add the scripts the cikick init output suggests:
{ "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.
Troubleshooting
Section titled “Troubleshooting”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.