Securing GitHub Actions Workflows
When to Use
- When GitHub Actions is the CI/CD platform and workflows need hardening against supply chain attacks
- When workflows handle secrets, deploy to production, or have elevated permissions
- When preventing script injection via untrusted PR titles, branch names, or commit messages
- When requiring audit trails and approval gates for workflow modifications
- When third-party actions pose supply chain risk through mutable version tags
Do not use for securing other CI/CD platforms (see platform-specific hardening guides), for application vulnerability scanning (use SAST/DAST), or for secret detection in code (use Gitleaks).
Common Misconfigurations & Verification
- Pinned by tag, not SHA:
actions/checkout@v4 is mutable — a compromised tag pulls attacker code on the next run. Pin to the full 40-char commit SHA (@b4ffde6...) and let Dependabot bump it. Audit with grep -rE 'uses:.*@v[0-9]' across .github/workflows/.
permissions left at default / write-all: with no explicit permissions: block the GITHUB_TOKEN inherits broad write scope. Set permissions: {} at the top and grant contents: read (plus id-token: write only where OIDC is used) per job. Flag any workflow requesting write-all.pull_request_target + checking out PR head: this runs untrusted fork code with secrets and base-repo permissions — the classic exfiltration path. Never actions/checkout with ref: github.event.pull_request.head.sha under pull_request_target; gate on a label and check out the base only.- Script injection via expressions:
run: echo "${{ github.event.pull_request.title }}" lets a crafted title execute commands. Pass untrusted input through env: vars and reference "${PR_TITLE}" in the script.
- Secrets echoed or passed on argv: avoid
echo "$SECRET" and command-line flags; use process substitution or files. Masking only catches exact matches.
- Verify by introducing a finding: open a PR titled
"; echo pwned # (or one that reverts a SHA pin) and confirm actionlint / your gate flags it and the step does not execute the injected command. A workflow that runs clean on a malicious title is still vulnerable.
Prerequisites
- GitHub repository with GitHub Actions enabled
- GitHub organization admin access for organization-level settings
- Understanding of GitHub Actions workflow syntax and events
Workflow
Step 1: Pin Actions to SHA Digests
- uses: actions/checkout@v4
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
commit-message:
prefix: "ci"
Step 2: Minimize GITHUB_TOKEN Permissions
name: CI Pipeline
permissions: {}
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
deploy:
runs-on: ubuntu-latest
needs: build
if: github.ref == 'refs/heads/main'
permissions:
contents: read
deployments: write
id-token: write
steps:
- name: Deploy
run: echo "deploying"
Step 3: Prevent Script Injection
- run: echo "PR title is ${{ github.event.pull_request.title }}"
- name: Process PR
env:
PR_TITLE: ${{ github.event.pull_request.title }}
PR_BODY: ${{ github.event.pull_request.body }}
run: |
echo "PR title is ${PR_TITLE}"
echo "PR body is ${PR_BODY}"
- uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea
with:
script: |
const title = context.payload.pull_request.title;
console.log(`PR title: ${title}`);
Step 4: Secure Fork Pull Request Handling
on:
pull_request:
branches: [main]
on:
pull_request_target:
types: [labeled]
jobs:
safe-job:
if: contains(github.event.pull_request.labels.*.name, 'safe-to-test')
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
Step 5: Protect Secrets and Environment Variables
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- name: Deploy with secret
env:
DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
run: |
# Never echo secrets
# echo "$DEPLOY_KEY" # BAD
deploy-tool --key-file <(echo "$DEPLOY_KEY")
- name: Audit secret access
run: |
# Log that secret was used without exposing it
echo "::notice::Deploy key accessed for production deployment"
Step 6: Implement Workflow Change Controls
.github/workflows/ @security-team @platform-team
.github/actions/ @security-team @platform-team
Key Concepts
| Term | Definition |
|---|
| SHA Pinning | Referencing GitHub Actions by their immutable commit SHA instead of mutable version tags |
| Script Injection | Attack where untrusted input (PR title, branch name) is interpolated into shell commands |
| GITHUB_TOKEN | Automatically generated token with configurable permissions scoped to the current repository |
| pull_request_target | Dangerous event trigger that runs in the base repo context with full permissions on fork PRs |
| Environment Protection | GitHub feature requiring manual approval before jobs accessing an environment can run |
| CODEOWNERS | File defining required reviewers for specific paths including workflow files |
| OIDC Federation | Using GitHub's OIDC token to authenticate to cloud providers without storing long-lived credentials |
Tools & Systems
- Dependabot: Automated dependency updater that keeps pinned action SHAs current
- StepSecurity Harden Runner: GitHub Action that monitors and restricts outbound network calls from workflows
- actionlint: Linter for GitHub Actions workflow files that detects security issues
- allstar: GitHub App by OpenSSF that enforces security policies on repositories
- scorecard: OpenSSF tool that evaluates supply chain security practices including CI/CD
Common Scenarios
Scenario: Preventing Supply Chain Attack via Compromised Third-Party Action
Context: A widely-used GitHub Action is compromised and its v3 tag is updated to include credential-stealing code. Repositories using @v3 automatically pull the malicious version.
Approach:
- Pin all actions to SHA digests immediately across all repositories
- Configure Dependabot for github-actions ecosystem to manage SHA updates
- Restrict GITHUB_TOKEN permissions so even compromised actions have minimal access
- Add StepSecurity harden-runner to detect anomalous outbound network calls
- Review all third-party actions and replace unnecessary ones with inline scripts
- Require CODEOWNERS approval for any changes to .github/workflows/
Pitfalls: SHA pinning without Dependabot means missing legitimate security updates to actions. Overly restrictive permissions can break legitimate workflows. Using pull_request_target for label-based gating still exposes secrets if the workflow checks out PR code.
Output Format
GitHub Actions Security Audit
================================
Repository: org/web-application
Date: 2026-02-23
WORKFLOW ANALYSIS:
Total workflows: 8
Total action references: 34
SHA PINNING:
[FAIL] 12/34 actions use mutable tags instead of SHA digests
- .github/workflows/ci.yml: actions/setup-node@v4
- .github/workflows/deploy.yml: aws-actions/configure-aws-credentials@v4
PERMISSIONS:
[FAIL] 3/8 workflows have no explicit permissions (inherit default)
[WARN] 1/8 workflows request write-all permissions
SCRIPT INJECTION:
[FAIL] 2 workflow steps interpolate user input directly
- .github/workflows/pr-check.yml:23: ${{ github.event.pull_request.title }}
SECRETS:
[PASS] No secrets exposed in workflow logs
[PASS] All production deployments use environment protection
SCORE: 6/10 (Remediate 5 HIGH findings)
