How should we manage GitHub Actions dependencies?

We routinely maintain lockfiles for application dependencies. Building the same source against different packages can cause problems. What about the dependencies in the GitHub Actions workflows that build and deploy that source?

A workflow often uses external actions to check out code, prepare a build environment, authenticate to a cloud service, and deploy artifacts. We accept the code those actions execute as part of our delivery process. Reviewing application code alone does not cover every change that can affect deployment.

An article about GitHub Actions workflow lockfiles prompted us to apply this perspective to a service we operate. Builds and deployments were already automated. We added dependency locking, update proposals, and acceptance rules to that existing process.

A workflow can stay unchanged while its code changes

The uses field usually names an action and a version tag. Tags are readable, but the same name is not guaranteed to keep pointing to the same commit. If the upstream repository moves a tag or branch, a later run can execute different code without any change to our workflow.¹

That distinction matters in deployment automation. Permissions vary by action, but some actions can access source code, build artifacts, or deployment credentials. Changes to external code deserve a place in the process that governs changes to a service.

Our project already used Blacksmith for builds and deployed to the cloud. Alongside improving the execution environment and cache, we needed to manage the external code accepted into that process. Operating a runner and choosing the dependencies it executes are separate responsibilities.

A lockfile makes the code to run part of the review

actions.lock records the commits behind a workflow’s dependency references. An onboarded workflow executes actions using those records. The scope includes actions used by those actions, as well as direct action dependencies.¹

After adoption, we kept readable version references alongside the exact commits to execute. An update pull request can show both the version selected and the code that selection will run. We record that execution baseline in our repository’s history rather than leaving it to the upstream reference’s current state.

Pinning a full commit SHA directly in a workflow is another option. Teams already doing this should compare their existing review and update process with what a lockfile would change. We chose a lockfile to retain readable workflows while maintaining a dependency record.

The boundary matters. Pinning an action commit does not establish that its code is safe. Runner environments, application packages, and tools downloaded during execution still need their own controls. A workflow lockfile covers one part of deployment dependency management.

Keep a path for updating pinned dependencies

Once versions are pinned, someone must decide when and what to change. Leaving them untouched can miss fixes and security updates. Accepting every new version immediately leaves less room to assess compatibility with our environment.

We assigned update proposals to Dependabot. It opens pull requests for review. When it updates an action in a workflow already onboarded to locking, it also updates the corresponding lockfile entry. The version reference and execution commit can be reviewed in the same change.²

The responsibilities are distinct. The lockfile pins the dependencies to use now. Dependabot proposes the next change. Validation and acceptance policies determine whether to adopt that proposal. Locking and updating belong in the same maintenance process.

This lets tools handle some of the work of remembering updates and editing references across workflows. The team can spend review time on a proposed change’s purpose and impact. Measuring any actual reduction in review time requires separate observation.

Define acceptance rules before automating promotion

Automatically receiving an update proposal and automatically releasing it to production require different decisions. A small version-number change does not establish compatibility or safety. Changes to the execution environment, required inputs, and permissions also matter.

We started with patch updates whose scope is narrow and whose supporting evidence can be checked. Major upgrades, changes that require adjustments to usage, and proposals with insufficient evidence remain subject to human review. The contents of a change and our ability to validate it matter more than the patch label.

We also defined the promotion order. The same dependency update is checked in development first, then validated against the production branch before release. We keep unrelated development features outside that promotion. If the candidate changes after review, the revised contents need a fresh decision.

Defining where to stop on failure makes the automation’s responsibility clear. The team should be able to explain how far tools may proceed and when a person must decide. Applying consistent rules to permitted changes came before expanding the range of updates handled automatically.

Adoption clarified the basis and path for changes

The management process changed in the following ways.

Pinning executable dependencies reduces the risk that an unexpected reference move changes the code used in deployment. Keeping a record also makes it easier to trace which action code was selected at a particular point in time.

Updates are reviewed as pull requests. Work that depended on someone remembering to update a version becomes part of the repository’s review process. Each change can retain the reason for accepting or holding it.

Connecting the development and production rules also distinguishes an update’s stage: proposed, under review, applied in development, or released to production. We configured these stages within the same process.³

We now have a basis for explaining which dependencies were selected, why they changed, and how far a change was promoted. We do not yet have measurements that establish improvements in build speed, cost, or incident rates.

Expand adoption to fit your environment

Start by identifying the external actions your workflows use. Understand which code you accept and which permissions it receives, then choose how to pin versions. If full-SHA pinning already works well, compare the additional problems a lockfile would solve.

Introduce validation alongside the lockfile. Differences between workflow references and locked records should be found during pull-request review. The feature is in public preview, so check the supported scope and changes to verification tooling at the time of adoption.⁴

Next, receive update proposals and review them manually. This helps distinguish recurring decisions from changes that need closer attention. Expand automatic promotion to changes with a narrow scope and trustworthy validation results. If development environments or recovery procedures are not ready, adopting locking and update proposals first is a reasonable stopping point.

We applied familiar application dependency-management practices to deployment automation: select the code to execute, receive proposed changes, review them, and promote accepted changes. actions.lock and Dependabot each support a different part of keeping that process in the repository.

801Planet designs dependency management and deployment processes around a service’s operating conditions. If you are reviewing your CI/CD setup, see our Cloud & Infrastructure service.

References