action-locker

action-locker

action-locker serves as a vital lockfile and storage solution designed specifically for GitHub Actions, ensuring essential actions are secure and reliable. By allowing pinning to a specific SHA, verifying that SHA, and vendoring critical repositories, action-locker enhances CI resilience against supply chain attacks and prevents issues caused by upstream actions disappearing.

Key Features:

Lock That SHA Up

• Secure each action using a pinned SHA, providing a safeguard against malicious code changes often associated with mutable tags. The tool prevents reliance on potentially dangerous references, like @v1, ensuring that workflows remain stable and trustworthy.

Minimum Age Control

• action-locker allows users to specify minimum age requirements for actions before they can be locked. This feature ensures that freshly released actions are automatically avoided unless they are deemed trustworthy. Users can adjust settings for actions they own, thereby reducing risk.

Vendoring Actions for Integrity

• Actions can be vendored, storing them locally and retaining a content integrity hash within the lockfile. This provides a safety net against potential upstream repository deletions or changes, ensuring the exact version can be used moving forward.

How It Works

1. Lock: The command action-locker lock scans your .github/workflows/, resolves references to immutable SHAs, and generates an action-lock.json file that records the action details.

   {
     "version": 1,
     "locked": {
       "actions/checkout@v4": {
         "resolved": "b4ffde65f46336ab88eb53be808477a3936bae11",
         "tag": "v4.1.1",
         "repo": "actions/checkout",
         "locked_at": "2026-03-23T19:00:00Z",
         "integrity": "sha256:…"
       }
     }
   }
   

2. Rewrite: The command action-locker rewrite updates workflow files to use the pinned SHAs while preserving the original tags as comments for clarification.

   - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1
   

3. Vendor: The action-locker vendor command takes snapshots of the actions and records their integrity. By doing so, it ensures that even if the main repository disappears, the exact version of the code remains accessible.

4. Verify: Using action-locker verify, the integrity of the pinned actions is checked in an offline mode, enhancing security and eliminating network dependencies during verification.

5. Update: The action-locker update command checks for new releases of locked actions, requiring human review before any changes are authorized, thus maintaining oversight and control over updates.

Security Mechanisms and Policies

• The tool implements a commit age floor to avoid locking actions that are less than five days old, thereby minimizing the risk of vulnerabilities introduced in fresh releases.
• The lockfile acts as a compliant policy document, allowing for per-prefix exceptions and detailed configurations to fit user needs, streamlining the management of secure workflow practices.

Integration and Testing

• action-locker offers seamless integration into CI systems with minimal setup. Pre-commit hooks can also be utilized to detect unpinned references before they enter the CI pipeline.
• Comprehensive tests are conducted using a variety of methods, ensuring both offline unit tests and live integration tests verify the tool's reliability and performance.

For a thorough understanding and demonstration of the tool's capabilities, refer to the demo repository.

Built by Steph Prime at Old Well Labs, action-locker stands as a robust solution for securing GitHub Actions in development workflows.