Help Shape Workflow Dependency Locking 👋 🔒

[samus-aran]

Actions / Workflow Dependency Locking

TLDR;
This discussion is focused on feedback for:

• the new dependencies: workflow contract
• naming and shape of the lock data
• resolution and enforcement behavior
• the gh actions pin CLI experience

---

Hi everyone 👋

We are designing workflow-level dependency locking for GitHub Actions and we want your opinion before we finalize the shape of it. This was previewed in our 2026 GitHub Actions Security Roadmap earlier this quarter, and it is the first deliverable on that roadmap.

This post focuses on two things:

1. The workflow file contract — a new dependencies: section that records the pinned state of every direct and transitive action your workflow uses.
2. The developer experience — a new gh actions pin CLI command that generates and maintains that section, as well as integration into Dependabot.

• CLI / UX feedback: cli/cli#13314 — RFC: gh actions pin
• This discussion: for the workflow contract, naming, and policy questions below.

Please share thoughts, concerns, and alternative designs. Nothing here is final.

The problem

GitHub Actions has no persistent record of what dependencies a workflow actually resolved when it ran. Resolution happens at runtime, the results are discarded, and there is no way to diff what changed between two runs.

Composite actions make this worse — they embed nested uses: steps that are invisible to the workflow author and only discovered after the top-level action is downloaded by the runner.

Every mature package ecosystem — npm, Cargo, Go modules, Bundler, NuGet — has a lockfile, a manifest, and a deterministic resolver. Actions has none of them.

That gap means:

• No determinism. The same workflow file can produce different runs depending on when it executes.
• No diffability. Dependency changes do not surface in pull requests. A reviewer approving a workflow change has no way to see what actually resolved, or what will resolve.
• No receipts. After a run, there is no committed record of the exact dependency graph that executed. You would have to diff the workflow logs, which is not a real answer.

These problems exist independent of whether action refs are mutable or immutable. Even if every release were immutable tomorrow, without a pinned dependency manifest there is still no committed record, no PR diff, and no transitive visibility.

Mutable refs make the problem more dangerous, supply chain attacks like the tj-actions/changed-files incident silently moved tags to malicious commits. Solving mutability is complementary work on the security roadmap. Dependency pinning gives you a point-in-time resolution: good or bad, it is what you reviewed and checked in.

The impact today:

• You cannot tell, from a PR diff, whether a workflow change pulls in a new transitive action.
• You have no committed record of the SHAs that ran in any given build.
• Your "pinned" workflows that already use SHAs (actions/checkout@abc123…) are unreadable, hard to upgrade, and still expose no transitive dependencies. Additionally, they do not guarantee that the SHA itself exists in the named repository and not an attacker controlled fork.

We want to close that gap, and we want to do it in a way that does not break the workflows you have today.

What we are proposing

We are introducing a dependencies: section in workflow YAML that locks every direct and transitive dependency to an exact commit SHA. Think of it as Go's go.mod + go.sum, but for your workflow, with full reproducibility and auditability.

For the first time, workflows can record the exact commit SHAs of direct and indirect (via composite actions) dependencies, directly in a dependencies: section inside the workflow YAML. The runner verifies and uses those exact resolutions before any job executes.

Note

The CLI is the first phase of the developer experience, not the end state. We are starting here because it gives us a fast surface to validate the workflow contract and the resolution behavior. Once that shape is settled, we plan to extend the experience to other touchpoints, including the workflow editor on github.com, IDE integrations, and Dependabot, so that pinning and updating dependencies feels native wherever you author or review workflows.

Guaranteeing resolution at job run time

What is Actions resolution? It's the behind the scenes process of turning a uses: statement referencing an action into bits on the runner. Today this involves resolving a ref to a sha, applying policies, and downloading the contents of the action. This proposal makes workflows deterministic by shifting the ref-to-sha resolution into the workflow definition itself. What you resolved and pinned is what gets executed, even if the ref no longer points to the same sha. Resolution happens once, via a CLI command, and the result is committed into the workflow file.

The workflow then runs against that locked state on every subsequent run. This aligns with how every mature package ecosystem (npm, Cargo, Go modules, Bundler, NuGet) already works: a manifest you author, a lockfile that pins the resolved graph, and a deterministic resolver that connects the two.

Example: a fully resolved workflow

The dependencies: section is generated and maintained by the gh actions pin CLI (see cli/cli#13314 for the RFC). You author the jobs: section as you do today; the CLI walks every uses: reference, recurses into composite action.yml files, and writes the locked graph back into the same file. Demo and example workflow output below:

Demo.mov

name: Happy path

on:
  workflow_dispatch:

jobs:
  lint:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v6
      - uses: nodeselector/actions-test-fixtures/nested-composite@updated

  build:
    uses: nodeselector/actions-test-fixtures/.github/workflows/reusable-build.yml@main

# Automatically generated and managed by gh-actions-pin
dependencies:
  - github.com/actions/checkout@v6:sha1-34e114876b0b11c390a56381ad16ebd13914f8d5
  - github.com/nodeselector/actions-test-fixtures/nested-composite@updated:sha1-ea53476fdc172d8552df5af9658a45a367e4f41d

  # Transitive dependencies (via nodeselector/actions-test-fixtures/nested-composite@updated)
  - github.com/nodeselector/actions-test-fixtures/simple-composite@main:sha1-d010fee89969c44873ca2c1b501905190eb7410d

  # Transitive dependencies (via nodeselector/actions-test-fixtures/simple-composite@main)
  - github.com/nodeselector/actions-test-fixtures-b/simple-echo@main:sha1-92b7b0058bc223c6e9dd4e19ef9247c934ba7637
  - github.com/nodeselector/actions-test-fixtures/simple-node@main:sha1-d010fee89969c44873ca2c1b501905190eb7410d

A few things worth noting in the example above:

• Both direct and transitive entries are present. The lint job declares two direct uses:. The composite at nodeselector/actions-test-fixtures/nested-composite@updated pulls in simple-composite, which in turn pulls in simple-echo and simple-node. All four transitive actions are surfaced explicitly in dependencies:.
• Reusable workflows are first class. The build job uses reusable-build.yml@main, and its dependency graph would be locked the same way.
• Floating refs are preserved alongside the SHA. Each entry keeps the human readable ref (@v4.3.1, @updated, @main) next to the resolved SHA, so reviewers can see what was asked for and what it actually resolved to at the same time.
• The block is CLI managed. The marker comment (# Automatically generated and managed by gh-actions-pin) makes ownership explicit and signals that the section should be regenerated, not hand edited.

What this changes in practice

• Deterministic runs. Every workflow executes exactly what was reviewed.
• Reviewable updates. Dependency changes show up as diffs in pull requests, including transitive ones.
• Fail fast verification. Hash mismatches stop execution before any job runs.
• Full visibility. Composite actions no longer hide nested dependencies.

In your workflows, this means you will be able to:

1. Resolve the dependency graph via the GitHub CLI.
2. Commit the generated lock data into the workflow file itself.
3. Update by rerunning resolution and reviewing the diff in a pull request.

By making dependency resolution explicit, durable, and reviewable, we turn what runs in CI into something you can audit, diff, and trust, without forcing changes on workflows that are happy with the current behavior.

Thanks for reading 🙏

[pinfloyd]

Thank you for opening this discussion.

I think this proposal is important because it addresses a concrete GitHub Actions instance of a broader architectural condition I previously isolated as architectural non-determinism: the reviewed object and the executable object can diverge unless the effective execution context is fixed before execution. Reference: Identical Inputs, Divergent Outcomes: Architectural Non Determinism as a Governance and Liability Risk.
DOI: https://zenodo.org/records/18015154 In the Actions context, the condition appears very clearly: reviewed workflow YAML ≠ effective executable workflow unless direct actions, transitive actions, composite actions, reusable workflows, mutable refs, and resolution state are made explicit before execution. That is why the proposed dependencies: contract looks significant. It turns part of the hidden execution surface into a durable, reviewable, diffable object. But I would frame this as necessary, not sufficient. Once the effective dependency graph is fixed, the next boundary question becomes: should this resolved workflow intent be admitted to execution at all? In other words, dependency locking can make the executable graph externally visible. External pre-execution admission can decide whether that graph, actor, intent, and context should be allowed to become runnable.

So my question is: could GitHub expose the resolved dependencies: graph as an input to policy/security tooling before run admission, so that automation-created or AI-assisted workflow changes can fail closed before any job executes? That would make dependency locking not only a reproducibility mechanism, but a pre-execution admission surface.

[samus-aran]

👀 This is very hard to follow. There may be a valid point here, but it’s buried under jargon. If I can’t quickly understand the ask, others won’t either.

If your question is about exposing the resolved dependency graph in GitHub Actions before execution, please state that clearly upfront. ❤️

Also, linking to a paper isn’t helpful here. Summarise what’s relevant instead of expecting readers to interpret it.

[pinfloyd]

Thanks, that is fair feedback.

My question is simple:

Can GitHub expose the resolved dependency graph before execution, so policy/security tooling can decide whether the workflow should be allowed to run?

The reason I care is this:

A reviewer sees the workflow YAML, but the runner executes the resolved graph: direct actions, transitive actions, composite actions, reusable workflows, refs, and SHAs. If that resolved graph is only known inside the runner at execution time, policy tools cannot reliably evaluate what will actually run before the job starts.

So the useful security surface would be:

workflow YAML + resolved dependency graph → policy check → allow run / block run

That is the part I am asking about.

[Steve-Glass]

Can GitHub expose the resolved dependency graph before execution

This evaluation happens before workflow execution starts. The policy check (future policy for requiring pinning +existing requirements) will happen ahead of time as well. If I understand your question correctly, then I think your proposed order of operations aligns with what we are thinking.

[pinfloyd]

Thanks, that answers the core concern.

Yes, that is the order I meant: resolve what will actually run first, then let policy/security tooling evaluate that resolved execution graph before the workflow starts. The important distinction for me is that the review target should not only be the YAML the author wrote, but the resolved execution surface the runner is about to execute: direct actions, transitive/composite actions, reusable workflows, refs, and SHAs.

If GitHub is thinking in that direction, that seems like the right security boundary.

[martincostello]

First thoughts:

• having the dependencies (and its transitive closure) in the workflow file(s) with the logic is going to be very visually noisy.
• for repos with many workflow files but homogenous versions (everything uses the same version of any given action) that's then magnified and duplicate
• I'd prefer the full graph stored elsewhere like in a package-lock.json, go.mod, Directory.Packages.props, etc.
• Realistically not something I would use instead of SHA-pinning until integrated into dependabot/renovate

[Steve-Glass]

having the dependencies (and its transitive closure) in the workflow file(s) with the logic is going to be very visually noisy.
for repos with many workflow files but homogenous versions (everything uses the same version of any given action) that's then magnified and duplicate. I'd prefer the full graph stored elsewhere like in a package-lock.json, go.mod, Directory.Packages.props, etc.

Appreciate the clear and concise feedback here! Would you prefer they be stored in the .github workflows directory and having all dependencies recorded in one file, or one dependency file for each workflow file?

Realistically not something I would use instead of SHA-pinning until integrated into dependabot/renovate

Totally agree with this. If we are locking dependencies, we need to make upgrading and management easy. This is part of our public preview requirements.

[martincostello]

My personal preference would be for a single lock file.

[fproulx-boostsecurity]

I have personally experimented with this exact idea about 2 years ago with a GitHub Action validating lockfile in .github/ and hard exiting. Others also independently made similar prototypes (https://github.com/gjtorikian/gh-actions-lockfile). Example here https://github.com/gjtorikian/gh-actions-lockfile/blob/main/.github/actions.lock.json

The advantage is that it would be a shared lockfile for several workflows, centralizing the boilerplate and it could be as simple as if the lockfile is present, it indicates you are opting in.

There are some abuse scenarios to consider though. If you get a Pull Request (from or fork - or not) that is proposing changes to your workflows, than would require updating the lockfile in order to run - what happens...

{
  "version": 1,
  "generated": "2025-12-16T21:07:38.752Z",
  "actions": {
    "actions/checkout": [
      {
        "version": "v6",
        "sha": "8e8c483db84b4bee98b60c0593521ed34d9990e8",
        "integrity": "sha256-d414ece895ebce08c818601c45ca8489806731838f8eed6356031b3d1877a7a1",
        "dependencies": []
      },
      {
        "version": "v5",
        "sha": "93cb6efe18208431cddfb8368fd83d5badbf9bfd",
        "integrity": "sha256-9a3223b64964bfd98c02cae27ad016d007f0c228b0274ac471963410ca90aa97",
        "dependencies": []
      }
    ],
...

[provinzkraut]

One major difference between the sha based locking and traditional lockfiles is that the latter often include a hash of the contents of the dependency. While the SHA itself might not be mutated, an action can easily include things that can change, e.g. because they're pulling in external things. So it kinds sounds like the SHA based approach is just kicking the can down the road?

For example, Python's pip (and other tools in the ecosystem interacting with the PyPI package repository), offers a hash checking mode, where you can lock down your versions alongside with the hash of what was actually installed. A future install will then compare this locked hash to the hash of the fetched dependency.

[jsoref]

I don't really see how any of this will work for me.

I'd love for a human to spend some time talking to me, but I also want to talk about other things, so it's a tradeoff.

My stack has (some optional, some not) dependencies from:

1. CPAN (e.g. JSON::PP)
2. Apt (e.g. hunspell, jq)
3. GitHub releases (e.g. tesseract)
4. GitHub actions (e.g. upload-artifact)
5. GitHub tags (Dictionaries)

Many of these dependencies are optional (hunspell is only needed if a workflow asks to use hunspell dictionaries; tesseract is only needed if a workflow asks to check images, ...) or can be provided by the caller (if a dependency is already available and has a satisfactory version, it'll be used as is, e.g. jq -- there's a minimum required version and if the available version is insufficient, another will be retrieved).

Classically, build systems aiming for reproducible builds tended to fail miserably because they neglected to record information about what the OS provided, or about transient dependencies that were satisfiable by some or operation or less pinned clause.

In theory, GitHub's runner images themselves are fully pinned, but almost nothing in the apt world is truly fully pinned, and most apt packages (especially those that use -devel/-dev headers) don't fully pin, which means that the binaries they provided themselves aren't truly reproducible -- but if you rely on a specific signed binary package, you could at least go for "traceable". (I worked on a Debian based linux distribution for 5 years, and quickly learned that the version definitions people imagined did not apply to rebuildable binaries.) -- And I should note that GitHub's runners turned out to be considerably more nondeterministic than people expected (the GitHub Runner itself can significantly influence how a runner image behaves -- ask me how I know).

Would people be interested in providing a way for actions to provide a SBOM/BOM reporting which things they retrieved so that someone who is curious could review that and try to reproduce a build by satisfying the SBOM/BOM contents before running steps? I'm not strictly opposed to providing an SBOM-like thing if someone provided an easy way to do so. (Requiring users to pay for GitHub Advanced Security or requiring : write permissions for workflows in order to produce an SBOM-like thing would be unacceptable, as my workflow needs to work anywhere -- including in pull_request from forks, not just places where people are willing and able to run with : write permissions or to pay 💸 to play.)

Which CPAN package manager would people actually expect developers to use to satisfy the goals presented here?

https://github.com/tokuhirom/anton (died 12 years ago)
https://github.com/skaji/Carl (died 10 years ago)
https://github.com/perl-carton/carton (died 4 years ago?)
https://github.com/miyagawa/Carmel (died 2 years ago?)
serious question, I searched and these were the best I could find

A number of my GitHub action dependencies are runtime selected. e.g., actions/upload-artifact is only used in some cases, and when it isn't used, my action does not download it. A pinning file that forced all possible dependencies to be downloaded even in cases where they weren't used would waste immense amounts of time. -- I work very hard to make my action start quickly -- I took the effort to replace github/codeql-action because it had a really horrible packaging story (they've since fixed it, but I have no intention of adding it as a dependency going forward). Note that Debian/Ubuntu images themselves do not pin the world, and even GitHub kicks packages out to make space (GitHub's setup-java action broke scala at some point and didn't care to fix it when GitHub dropped sbt or something), they just provide the ability to dynamically add packages based on requests (apt-get install). Also fun, apt-get install tends to fail miserably if not preceded by apt-get update because the repositories themselves tend to only retain a limited set of versions and not all versions. -- Requiring me to ship a new version every day isn't reasonable (especially considering that GitHub's dependabot-action can't be bothered to ship a version that supports node24).

Similarly, my action can use any number of external dictionaries (configured by the workflow caller). It does not make sense for me to bundle an infinite number of potential dictionaries into my action or into a dependency lock file (beyond the fact that it's obviously impossible), as the specific dictionaries that a consumer will use will vary based on the consumer. I'm more than happy to provide URLs and SHAs for such files (again, see SBOM), but I can't reasonably inline such content into my action.

@samus-aran I'm open to a call (or a recurring call, I collect these). But, I'd also encourage you to take a look at my action first.

[thehale]

My stack has (some optional, some not) dependencies from CPAN, apt, ...

I guess I understood the proposal to be only specifying a lockfile-type format for Action workflow dependencies (e,g. which version of checkout or setup-python does this workflow use).

I don't think I'd want GitHub Actions to try and pin my CPAN, apt, npm, etc. dependencies -- those efforts (futile as they may be for apt and friends) are better handled within my codebase.

[jsoref]

The problem is that those dependencies all lead to non-deterministic behavior and non reproducible behavior. For instance, periodically, GitHub returns 404 for dictionaries or releases. Heck, Microsoft's apt repositories regularly fail. So if the claim is that this feature should result in reproducible builds, it's smoking a lot.

[ljharb]

Personally, i'd prefer to see the hashes in a separate single lockfile (for the whole repo, and/or per workflow) - for CODEOWNERS control, diff churn, etc.

In other words, like in almost every ecosystem, the dependency manifest should be separate from the lockfile.

[tianon]

Yeah, modifying a canonically human-maintained file in an automated way reliably and consistently is very difficult (Go designed their own full language for it, and it's still got rough edges).

[thehale]

This sounds like a great endeavor! I'm excited for it :D

I will echo the preference for the dependencies block to appear in a separate lockfile.

I'd also prefer to avoid using comments to indicate transitive dependencies.

My motivation comes from two directions:

• Can I look at the lockfile and easily see which direct dependencies would be most meaningful to prune (e.g. to reduce transitive dependency count)?
• Can I use standard YAML parsing to analyze the lockfile? (parsing comments to reconstruct the asserted dependency tree sounds unfortunate).

Maybe a lockfile format like this?

.github/workflows/dependencies.lock

# Automatically generated and managed by gh-actions-pin
<workflow-1.yml>:
  - name: github.com/actions/checkout@v4.3.1:sha1-34e114876b0b11c390a56381ad16ebd13914f8d5
  - name: github.com/nodeselector/actions-test-fixtures/nested-composite@updated:sha1-ea53476fdc172d8552df5af9658a45a367e4f41d
    dependencies:
      - name: github.com/nodeselector/actions-test-fixtures/simple-composite@main:sha1-d010fee89969c44873ca2c1b501905190eb7410d
        dependencies:
          - github.com/nodeselector/actions-test-fixtures-b/simple-echo@main:sha1-92b7b0058bc223c6e9dd4e19ef9247c934ba7637
          - github.com/nodeselector/actions-test-fixtures/simple-node@main:sha1-d010fee89969c44873ca2c1b501905190eb7410d

<workflow-2.yml>:
  - name: ...

_{I don't have meaningful experience building package management ecosystems, so I'm happy to be corrected on the feasibility of this proposed lockfile format. I recognize that a flat list is easier to load than a recursive walk, but a richer structure akin to the one I've sketched here would be helpful.}

[woodruffw]

Speaking as zizmor's maintainer, I think my primary concerns are:

1. It's not clear at all how average users will deal with the visual noise here.
2. It's not clear (yet?) how GitHub will deal with "partial" states here: what happens if a user deletes a single line from the in-file "lockfile"? Does GHA continue in a partially-locked state, or does the action fetch fail? I would expect the latter, but I could easily imagine the former happening accidentally.

Like others, I think I would strongly prefer it if GitHub were to pursue a detached lockfile approach here. Going even further, I think it would be really great if the ultimate lockfile was global across all workflows, and not just per-workflow. In other words, I think it would be really great if there was a single .github/actions.lock.yml (or whatever) file that looked all action references across all workflows, as a matter of single-sourcing.

Finally, I think it would be great for GitHub to ideate (if not necessarily share) long-term plans for making locked resolutions of actions mandatory, rather than opt-in. Users would ideally not have to opt into locking, because the median user won't.

Edit: I'll also echo the sentiment that, whatever GitHub does here, it should not continue the unfortunate trend of communicating important semantic information (like transitive relationships) via non-semantic state (YAML comments). Ideally a lockfile/lock representation here would be an actual machine-readable graph representation like uv.lock, etc.

[bgw]

We're pinning all of our actions in vercel/next.js, and would love to be an early adopter of this feature once it's available. It would be great to be able to combine this with the "Require actions to be pinned to a full-length commit SHA" option.

[hfhbd]

Do you still plan to keep the current behavior of using git as binary repository? If not, and if you plan to finally support an OCI images registry or another file registry, the lock file should also include the origin.

[Fabridev444]

Quick datapoint from the field, hopefully useful for the design.

I have been auditing public .github/workflows/ from a few well-known OSS repos using a 13-rule scanner I maintain (gha-shield — browser/CLI/Action, MIT-pending). Raw outputs are public in REAL-WORLD-AUDITS.md. What the unpinned-action rule sees today across 143 workflow files:

Repo	Workflows	Unpinned actions
prisma/prisma	17	89
vercel/next.js	37	2
oven-sh/bun	30	0 (all SHA-pinned already)
astral-sh/uv	27	0
vitest-dev/vitest	9	0
archestra-ai/archestra	23	0

A few observations that may inform the dependencies: contract design:

1. The distribution is bimodal. Repos either fully SHA-pin (bun, uv, vitest, archestra) or barely pin at all (prisma at 89). There is almost no "half-pinned" middle. This is consistent with the idea that pinning is a culture / tooling decision more than an incremental hygiene one — once a repo has the muscle memory plus Dependabot config it stays pinned, and once it doesn't it stays unpinned. A gh actions pin one-shot import command will help the unpinned cohort cross the threshold.

2. The dependencies: block needs to play well with reusable workflows. Several of the audited repos use uses: ./.github/actions/... (local composite actions) and uses: org/repo/.github/workflows/wf.yml@<sha> (reusable workflows). Each of those itself references third-party actions transitively. If dependencies: is per-file, the transitive closure won't be visible at the caller, which several commenters above also noted. A shared lock file at the repo root (per @martincostello's suggestion) is the cleaner shape for multi-workflow repos — the visual-noise problem is real on repos with 30+ workflow files.

3. SHA pinning is necessary but not sufficient. @provinzkraut's point upthread about the SHA pin not covering transitive runtime fetches is correct. In the four-repo corpus above, I see curl https://example.com/install.sh | bash patterns in astral-sh/uv/test-system.yml (the canonical pyenv installer) — perfectly SHA-pinned actions can still execute remote, unpinned code from inside the run step. A complete pinning story would also need to cover at least the obvious download-then-execute idioms; gh actions pin may want a separate audit pass for those rather than treating them as out-of-scope.

4. permissions: and pinning are entangled. From the same corpus, no-permissions shows up in 8 of 17 prisma workflows — the same workflows that aren't pinning either. It would be worth thinking about whether gh actions pin also nudges the workflow to add a permissions: block when one isn't present (perhaps as a separate warning, not as part of the lock). The two together close the realistic blast surface; either alone leaves the other open.

5. False-positive sensitivity matters more than people expect. The first version of my rule 3 (command injection) over-flagged ${{ github.event.issue.number }} style integer leaves; users tune out a tool that surfaces those alongside real ${{ github.event.pull_request.title }} injections. For gh actions pin --check mode the same will be true: if the diff between resolved and locked SHA fires every Dependabot bump as a violation rather than a normal update, the CLI becomes noise. Worth designing the policy-failure category up front (bumped-by-dependabot vs unexpectedly-changed vs unlocked).

I am happy to feed the raw scan outputs into any spec-review process and to update gha-shield to emit the new dependencies: format once it stabilizes. The 13 rules + harness are open source if any of the rule logic is useful as a reference implementation.

Looking forward to the design landing.

[ljharb]

It would be nice to be able to pin permissions (OCAP-style) separately from SHAs - i'd love to avoid the problems caused by pinning SHAs, allowing free-flowing updates - but lock down the permissions a workflow has, ensuring that if they widen, the update is blocked.