GitHub Actions workflow lockfiles are generally available

[samus-aran]

You can now use GitHub Actions workflow dependency lockfiles in general availability on GitHub Enterprise Cloud, GitHub Enterprise Cloud with data residency, Team, and Free plans. Lockfiles let you keep readable tag and branch references in your workflows while running the exact commits you locked, even if those references move.

This release brings the capabilities introduced in the public preview to general availability:

• Lock your dependencies: Use the gh actions-lock extension for the GitHub CLI to generate .github/workflows/actions.lock for actions, their transitive dependencies, and reusable workflow references.
• Adopt locking gradually: Onboard workflows individually. GitHub Actions requires each dependency of an onboarded workflow to be in the lockfile and runs its recorded commit.
• Keep updates in sync: When Dependabot opens a version update for an action in an onboarded workflow, it also regenerates the matching lockfile entry in the same pull request, without additional configuration.
• Require lockfile: Enterprise, organization, and repository administrators can use the Require lockfile policy to enforce adoption.
• Check for stale lockfiles: Verify that your lockfile is up to date without modifying files, including in a CI check.

Lockfiles help protect against unexpected dependency changes, but they don't determine whether a dependency is safe. Review dependencies before locking them.

Get started

Install the extension from the gh-actions-lock repository, then review and commit the generated lockfile and workflow changes. See workflow dependency lockfiles in GitHub Docs for details and setup instructions.

🌟 Leave a comment!

Share feedback in the comments below or report an issue with the extension.

Tune in for Day 2 of GitHub Universe & check out our round-up post of releases in the Community that need your input ⏭️

[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.

[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.

[sheeeng]

If I have already enabled Require actions to be pinned to a full-length commit SHA in my GitHub repositories, will it break the existing pinned actions? Can I keep existing pinned actions? Will Dependabot continue to update them? Example:

    steps:
      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1

[ebndev]

🆕 Community Manager Update: October 28, 2026

Hi everyone! Thank you so much for leaving feedback. We're happy to announce: GitHub Actions workflow lockfiles are generally available. Please read the updated the discussion above and continue to leave comments if you have additional thoughts.