eclipse-tractusx / eclipse-tractusx/eclipse-tractusx.github.io
feat: Introduce TRG 8.06 - GitHub Actions SHA Pinning
- Dominant language
- MDX
- Stars
- 46
- Forks
- 130
- Avg merge
- 10d 19h
- Merged PRs (30d)
- 3
Description
## Summary
This issue proposes a new Release Guideline **TRG 8.06** under the existing *TRG 8 - Security* category.
The guideline mandates that all GitHub Actions referenced in `eclipse-tractusx` workflow files must be pinned to an **immutable commit SHA** rather than a mutable version tag or branch name. It also introduces [zizmor](https://docs.zizmor.sh) as a recommended tool for automated enforcement.
---
## Motivation
Using mutable version tags (e.g. `actions/checkout@v4`) or branch names (e.g. `actions/checkout@main`) in `uses:` references creates a **supply chain attack vector** known as tag-hijacking:
- A compromised or malicious maintainer can silently redirect that tag to point to a different (malicious) commit SHA.
- Downstream workflows that reference the tag will automatically execute the new, potentially harmful code on the next run — with no visible diff in any PR.
- This attack surface applies equally to first-party actions (GitHub), popular marketplace actions, and internal reusable workflows.
Pinning to a full-length commit SHA (`uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2`) makes the reference **immutable**: the SHA is cryptographically bound to a specific tree of code that cannot be silently altered.
This approach is recommended by:
- [GitHub Security Hardening for GitHub Actions](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions)
- [OpenSSF Scorecard](https://securityscorecards.dev/) (`pinned-dependencies` check)
- [StepSecurity / Harden Runner](https://github.com/step-security/harden-runner)
- [SLSA Supply Chain Levels for Software Artifacts](https://slsa.dev)
---
## Related work
This TRG formalizes a security hardening initiative already underway in `sig-infra`:
- [eclipse-tractusx/sig-infra#567](https://github.com/eclipse-tractusx/sig-infra/issues/567) — Umbrella issue: migrate repositories to centralized, SHA-pinned Trivy scanning
- [eclipse-tractusx/sig-infra#569](https://github.com/eclipse-tractusx/sig-infra/issues/569) — Central nightly `zizmor` scanner for the entire `eclipse-tractusx` org
---
## Proposed TRG content (draft)
The following is the proposed content for `docs/release/trg-8/trg-8-06.md`:
---
```markdown
---
title: TRG 8.06 - GitHub Actions SHA Pinning
---
| Status | Created | Post-History |
|--------|-------------|---------------|
| Draft | 01-May-2026 | Initial draft |
## Why
Referencing a GitHub Action by a mutable tag (e.g. `@v4`) or branch name (e.g. `@main`)
is a supply chain risk: a compromised maintainer can silently redirect that tag to a
different commit, which your workflow will then execute with no visible diff in any PR.
Pinning every `uses:` reference to a **full-length commit SHA** makes the dependency
immutable and cryptographically verifiable. This is the approach recommended by GitHub,
OpenSSF Scorecard, and SLSA.
## Description
Every `uses:` reference in a GitHub Actions workflow file inside `eclipse-tractusx`
repositories **must** be pinned to a full-length (40-character) commit SHA.
A human-readable version comment **should** accompany the SHA for maintainability.
### Required format
```yaml
# Instead of:
- uses: actions/checkout@v4 # ❌ mutable tag
- uses: aquasecurity/trivy-action@master # ❌ mutable branch
# Use:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 ✅
- uses: aquasecurity/trivy-action@76071ef0d7ec797419534a183b498b4d6366cf37 # 0.29.0 ✅
```
This applies to:
- All actions from the GitHub Marketplace (`actions/*`, `github/*`, `step-security/*`, etc.)
- All third-party actions (`aquasecurity/*`, `docker/*`, etc.)
- External reusable workflow references
### How to find the correct SHA
For any action at version `vX.Y.Z`, retrieve the commit SHA via the GitHub CLI:
```bash
gh api repos/{owner}/{repo}/git/ref/tags/{tag} --jq '.object.sha'
# Example
gh api repos/actions/checkout/git/ref/tags/v4.2.2 --jq '.object.sha'
```
### Keeping pins up to date
Manually tracking SHA updates is impractical at scale. Use **Dependabot** (see [TRG 8.05](https://eclipse-tractusx.github.io/docs/release/trg-8/trg-8-05))
with the `github-actions` ecosystem enabled. Dependabot will automatically open pull
requests that update SHA pins whenever a new version of an action is released.
```yaml
# .github/dependabot.yml
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
open-pull-requests-limit: 5
```
**Automated checking with zizmor**
[zizmor](https://docs.zizmor.sh) is a static analysis tool for GitHub Actions that
automatically detects unpinned action references (and many other workflow
misconfigurations).
## See also refernces - issues
- [x] https://github.com/eclipse-tractusx/sig-infra/issues/569
- [ ] https://github.com/eclipse-tractusx/sig-infra/issues/567
Contributor guide
Assessment
This issue has not been assessed yet.