Lockfile and pinning
A tag such as actions/checkout@v4 is a pointer that its owner can move. If a workflow references the tag directly, what runs in your CI is whatever the tag points to at that moment, with your repo’s token and secrets in reach. cikick resolves each tag once, records the commit SHA in cikick.lock.json, and renders the SHA into the workflow, so the code that runs only changes when the lockfile changes in a commit someone reviews.
The lockfile
Section titled “The lockfile”{ "actions": { "actions/checkout@v4": { "resolvedAt": "2026-11-22T10:36:56.498Z", "sha": "11d5960a326750d5838078e36cf38b85af677262" }, "actions/setup-node@v4": { "resolvedAt": "2026-11-22T10:36:56.498Z", "sha": "49933ea5288caeca8642d1e84afbd3f7d6820020" } }, "packages": { "@acme/wf-node-ci": "2.0.0" }, "version": 1}actionsis keyed byowner/repo@refexactly as written in the config (pathis not part of the key). Each entry has the resolved commitshaand an ISOresolvedAt.packagesrecords the version of each cikick package (a dependency whosepackage.jsonhas acikickfield) at the last synth.cikick updatecompares it with what is installed.- Keys are sorted and the file ends with a newline, so diffs are minimal and stable.
- Entries for refs no longer used by any workflow are dropped on the next synth.
Commit the lockfile. It is part of what cikick check verifies.
Resolution
Section titled “Resolution”During synth, for each distinct non-SHA owner/repo@ref:
- If the lock already has the key, the recorded SHA is used. A moved tag is not picked up automatically.
- Otherwise the ref is resolved and a new entry is written with the current time.
A ref that is already a 40-character hex SHA bypasses the lock and renders as is (no # ref comment).
The CLI resolves with a FallbackResolver that tries two resolvers in order and throws the last error if both fail:
GitResolver: runsgit ls-remote https://github.com/<owner>/<repo>(30 second timeout) forrefs/tags/<ref>, its dereferenced formrefs/tags/<ref>^{}, andrefs/heads/<ref>. Annotated tags are dereferenced to the commit SHA. Preference order: dereferenced tag, then lightweight tag, then branch, so a tag wins over a branch with the same name. It needsgiton the PATH but no token and no API rate limit.GitHubResolver: callsGET /repos/{owner}/{repo}/commits/{ref}on the GitHub API, usingGITHUB_TOKENas a bearer token if set (anonymous otherwise, which is rate limited). This covers cases wheregit ls-remotefails, such as private action repos that git has no credentials for.
Only github.com is used by the CLI. LockResolver is the third resolver: it answers only from an existing lockfile and throws MissingLockEntryError for anything absent. Synth uses it when no resolver is supplied.
A short SHA (anything not 40 hex characters) is treated as a ref name and will not resolve through git ls-remote.
Commands and flags
Section titled “Commands and flags”| Command | Resolution behaviour |
|---|---|
cikick synth |
Resolves only keys missing from the lock; writes workflows and lock. |
cikick synth --frozen |
Never resolves. If any non-SHA ref is missing from the lock, fails with cikick.lock.json is missing entries (frozen mode): .... |
cikick synth --refresh |
Ignores existing entries and re-resolves every ref. This is how you deliberately move a pin forward. |
cikick lock (--refresh) |
Same resolution as synth, but writes only cikick.lock.json, not the workflows. |
cikick check |
Always frozen. Fails on missing lock entries, on drift (including a lockfile that differs from what synth would write), and on error findings. |
See the CLI reference for the full option list, and CI check guide for wiring check into a pipeline.
What pinning protects against
Section titled “What pinning protects against”- A tag or branch being re-pointed after you adopted it. Whoever controls the action repository (or compromises it) can move
v4to different code. Your workflows keep running the commit that was resolved when the lock entry was created, until you refresh it. - Silent drift between repos. All repos using the same shared package get SHAs from their own lockfile, and
cikick-fleet inventoryflags anyuses:that is not a SHA. - Hand edits. The generated YAML is compared byte for byte by
cikick check, so swapping a SHA in the YAML without the lock changing shows up as drift.
What it does not protect against
Section titled “What it does not protect against”- A bad commit that was pinned from the start. If the code at the SHA was already malicious or vulnerable when you first resolved the tag, pinning preserves it faithfully. Pinning gives you stability, not trust.
- Unreviewed upgrades.
--refresh(or a bot running it) replaces a SHA with whatever the tag points to now. Treat a lockfile diff like a dependency bump: look at what changed between the old and new commit before merging. - Things cikick does not render. An action may itself call other actions or pull a container image internally; those references are inside the action’s repository and are not controlled by your lockfile. Likewise hand-written workflows in the same repo are untouched.
- Docker image references are not resolved by cikick;
docker://refs are passed through. The stock checkrequire-pinned-actionsflagsdocker://refs without an@sha256:digest. See Checks.
Edge cases
Section titled “Edge cases”- The lock key is the ref string, so
actions/checkout@v4andactions/checkout@v4.2.0are separate entries, and the same key used in ten workflows is one entry. - Reusable-workflow calls (
uses: owner/repo/.github/workflows/x.yml@refon a job) are pinned the same way as step actions. - If
git ls-remotefinds nothing and the API call fails, synth stops with the API error; no partial lockfile is written because files are written only after synth completes.