ratchet: Pin and Update CI Actions and Images
ratchet resolves mutable references (action tags, container tags) to their immutable digests and pins them in your CI config, then can update or unpin them on demand.
ratchet is broader than pinact: it pins GitHub Actions, Docker images, and other references across GitHub Actions, GitLab CI, and Cloud Build files, tracking the original ref in a comment so updates stay readable.
What it does
ratchet parses a CI file, finds resolvable references, and rewrites them to a pinned digest with the original tag preserved in a trailing comment. pin freezes, update re-resolves to the latest, check verifies everything is pinned, and unpin restores the human-readable tags.
Common usage
ratchet pin .github/workflows/ci.yml
ratchet check .github/workflows/ci.yml # verify all refs are pinned
ratchet update .github/workflows/ci.yml # bump pins to latest
ratchet unpin .github/workflows/ci.yml # restore tags for editingOptions
| Command | What it does |
|---|---|
| pin <files> | Resolve refs to digests and pin in place |
| check <files> | Verify all refs are pinned; nonzero exit otherwise |
| update <files> | Re-resolve pinned refs to the latest version |
| unpin <files> | Replace pinned digests with the stored tag |
| -parser <name> | actions, cloudbuild, circleci, gitlabci, etc. |
| RATCHET_EXP_KEEP_NEWLINES (env) | Preserve file formatting on rewrite |
In CI
Run ratchet check in a PR gate so unpinned actions or images cannot merge. Because it also pins container images, it complements zizmor findings and covers non-Actions CI systems that pinact does not.
Common errors in CI
ratchet check prints references that are unpinned and exits nonzero. failed to call ref: ... 403 on the container registry or GitHub API means missing auth; set the registry credentials or GITHUB_TOKEN. no parser found means you did not pass the right -parser. Editing a pinned file by hand and re-pinning can produce already pinned notices that are safe.