[jdx]

Part of #167 (section 2, actions.lock: unpinned-uses accepts what the lock pins, and the pin fix does not inline a SHA there).

What

unpinned-uses no longer reports uses: owner/repo@v1 in a workflow when the repository's .github/workflows/actions.lock pins that ref to a full commit for that workflow. The --online pin fix (tag to SHA) is not offered for a step of such a workflow, because a SHA is a ref the lock file has no entry for. A follow-up PR (actions-lock rule that lints the lock file) is based on this branch.

The reader is in its own file, actions_lock.go. It is loaded from the project (Project.actionsLock(), read once per project like the config) and has no effect when the file is absent or cannot be trusted.

The real format (primary sources)

I did not guess the format. It is defined and implemented in public repositories:

• Producer, behaviour: github/gh-actions-lock (README, internal/lockfile/state.go, internal/pipeline/checks/structural.go, internal/workflowfile/workflowfile.go). "Public preview. gh-actions-lock is pre-1.0 ... The lockfile format, command flags, and behavior may change without notice."
• Format and parser: github/actions-lockfile (schema/lockfile-v0.0.3.json, go/pkg/lockfile/{lockfile,compat,pin,uses}.go).
• How CodeQL reads it: github/codeql#22487 (extraction) and #22155 (actions/ql/lib/codeql/actions/Lock.qll, the actions/unpinned-tag query). Their test fixture CWE-829-Lockfile is where the edge cases below come from.
• Roadmap: github/roadmap#1253 (preview) and #1268 (GA); the 2026 security roadmap post describes the idea (it still says the lock lives in the workflow YAML; what shipped is the file). Runner: actions/runner#4546 logs "Running with locked dependencies". zizmor tracks it in zizmor#2371.

What the file is (v0.0.2 and v0.0.3 have this shape; v0.0.3 adds an optional hostname):

version: 'v0.0.3'
workflows:                                   # a workflow path -> the actions its file uses (direct uses only)
    '.github/workflows/ci.yml':
        - 'actions/checkout@v6.0.2'          # "owner/repo@ref", owner and repo lower case, ref as written
dependencies:                                # the dependency graph, one entry per "owner/repo@ref"
    'actions/checkout@v6.0.2':
        ref: 'v6.0.2'                        # equal to the ref of the key (unless the key's ref is a full SHA)
        commit: 'sha1-de0fac2e...'           # sha1-<40 hex> or sha256-<64 hex>
        owner_id: 44036562                   # positive integers; they detect a transferred or re-created repository
        repo_id: 197814629
        uses:                                # only composite actions: their own direct uses (transitive graph)
            - 'actions/cache@v4'

Facts that decide the behaviour, with where I found them:

• Per workflow. "workflows are onboarded to the lockfile on a per-workflow basis" (gh-actions-lock README). The runner holds only listed workflows to it.
• Repository granularity. A pin is owner/repo@ref; a sub action (actions/cache/save) is pinned by its repository (pin.go, and CodeQL's Lock.qll covers nwo + "/" prefixes).
• Case. owner/repo are canonicalised to lower case, the ref is case sensitive (Pin.Canonical); CodeQL's fixture has dtolnay/rust-toolchain@V1 reported while @v1 is accepted.
• Reusable workflows and Docker images. The current gh actions-lock records neither (ParseActionRef returns nil for a workflow file; zizmor#2371: "This currently doesn't replace pinning callable workflow refs"; CodeQL leaves reusable workflows unchanged), so they are judged as before. Some lock files in the wild do list the pin of a reusable workflow (17 of the 47 remote reusable calls of listed workflows in the corpus below), so the next PR counts a listed one as used, but nothing relies on it.
• Local actions. ./ actions are not onboardable; $/path is the in-repo form, "inherently pinned", and the actions that an in-repo action uses are attributed to the workflows that run it (ParsedWorkflow.Refs: "includes refs found inside in-repo $/… actions"). Real lock files confirm it: shun-shobon/littlexml lists jdx/mise-action under ci.yml, which only the composite .github/actions/setup uses.
• A SHA written in uses: is a different ref. checkNotPinned in gh-actions-lock reports a bare SHA with no matching lock entry as not-pinned (it "was never history-checked"). So rewriting a tag to an inline SHA in a listed workflow can make it fail the lock check, which is why the fix is not offered there.
• Versions. The official parser accepts v0.0.1-v0.0.3 and rejects unknown top-level keys. Mine is more tolerant on purpose (unknown keys are ignored) and stricter on versions: only v0.0.2 and v0.0.3 are trusted; any other version (a future one, v0.0.1 whose entries have tag/branch instead of ref) is treated as no lock file, so a format change can only bring findings back, never hide one.

Behaviour

A step uses: owner/repo[/path]@ref of a workflow is accepted when the lock file:

1. lists the workflow under workflows with the pin owner/repo@ref (same ref), and
2. has a dependencies entry for it with the same ref and a full commit digest (sha1- + 40 hex or sha256- + 64 hex).

For a step of a local action (action.yml): every workflow that runs the action (directly or through other local actions, using the existing call graph) must satisfy 1 and 2; an action no workflow runs is not locked.

Unchanged when: no lock file; the file is not YAML or not a mapping; no or an unknown version; workflows/dependencies of the wrong shape; the workflow is not listed; the entry is missing or malformed. Reusable workflow calls and Docker images are always judged as before. New option unpinned-uses.actions-lock (default true) switches the lock file off.

How it was tested

• Unit and fixture tests: actions_lock_test.go (golden testdata/actions_lock/covered.out: sub action, owner case, ref case, other workflow's pin, ref mismatch, non-digest commit, sha256, entry without dependency, unlisted workflow, docker, reusable workflow; plus 18 table cases for unusable files), actions_lock_action_test.go (local actions with one or two callers), actions_lock_fix_test.go (the online fix is withheld in a listed workflow and offered elsewhere).
• go build ./..., go vet ./..., go test -race ./... and hk check --all pass.
• Corpus: the repositories which have a .github/workflows/actions.lock (GitHub code search filename:actions.lock path:.github/workflows finds 363; I cloned 82, at most 4 per owner, because 242 are one account's near-identical repositories). With the lock file ignored (actions-lock: false) unpinned-uses reports 1,307 findings in these repositories, with it 57 (71 of the 82 repositories change). I classified all 57: 7 are Docker images and reusable workflow calls (not recorded by the tool, judged as before); 18 are in action.yml files that no workflow of the repository runs (published actions and test fixtures); 32 are steps of workflows for which the lock file has no exact pin (the lock lists the action at another ref, or not at all). I read the lock files of two of those repositories to confirm that it is staleness and not a reader bug (atomic-works/github-actions-reusable-workflows locks actions/checkout@v3.7.0 and uses @v7.0.1; metadatastician/burble bumped upload-artifact to v7.0.2 and kept v7.0.1 in the lock), and the independent script agrees. I also checked the other side with an independent script (a regexp read of the uses: lines and a YAML read of the lock, no jactionlint code): of 1,258 tag-pinned step uses: lines in these workflows it finds 1,225 pinned and 33 not, and jactionlint reports 32 of the 33 (the 33rd is in a file that generated-files skips by default). No false negative was found.

Not measured

• Whether the runner really enforces the file on a given plan (the sources say the preview is public and describe enforcement for listed workflows, I could not verify which plans enforce it), so the docs say jactionlint trusts the checked-in file.
• The false-positive rate of workflows that are not listed (they are reported as before, which is what the previous behaviour was).
• Lock files of v0.0.1 are not read.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes default pinning policy for repos using actions.lock and alters online fix behavior for locked workflows; malformed lock files are conservatively ignored rather than partially trusted.

Overview
Adds support for GitHub’s technical-preview Actions lock file (.github/workflows/actions.lock) so unpinned-uses treats tag-pinned uses: as satisfied when the lock lists the workflow and pins that owner/repo@ref to a full commit digest.

A new actions_lock.go module parses lockfile v0.0.2/v0.0.3 (unknown versions are ignored so findings never disappear on format changes), caches the result per linter run, and uses the existing call graph so composite local actions are covered only when every workflow that runs them lists the same pins. Reusable workflows and Docker images are unchanged.

unpinned-uses.actions-lock (default true) disables this behavior. For workflows listed in the lock, --online tag→SHA pin fixes are withheld (inline SHAs are a different ref and can fail gh actions-lock verification), with guidance to use gh actions-lock instead.

Docs, JSON schema, zizmor parity notes, and broad tests (golden fixtures, unusable lock cases, cache scope, fix behavior) accompany the linter wiring in RuleEnv, RuleAction, and attachPinFixes.

^{Reviewed by Cursor Bugbot for commit 09c2db5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 25 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Central YAML (base), Organization UI (inherited)
• Review profile: CHILL
• Plan: Advanced
• Run ID: 7abda621-67d0-4d84-b1e8-c1fa18ee585a

📥 Commits

Reviewing files that changed from the base of the PR and between 6d59dcf and 09c2db5.

⛔ Files ignored due to path filters: 3

• testdata/actions_lock/covered.out is excluded by !**/*.out
• testdata/actions_lock/covered/.github/workflows/actions.lock is excluded by !**/*.lock
• testdata/actions_lock/covered_option_off.out is excluded by !**/*.out

📒 Files selected for processing: 18

• actions_lock.go
• actions_lock_action_test.go
• actions_lock_cache_test.go
• actions_lock_fix_test.go
• actions_lock_test.go
• docs/checks.md
• docs/rules.md
• docs/zizmor-parity.md
• linter.go
• online_pin.go
• online_pin_test.go
• rule_action.go
• rule_registry.go
• rule_unpinned_uses.go
• schema/jactionlint-config.json
• testdata/actions_lock/covered/.github/workflows/ci.yml
• testdata/actions_lock/covered/.github/workflows/other.yml
• testdata/actions_lock/covered/.github/workflows/unlisted.yml

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a3f8f92. Configure here.}