github-actions

GitHub Actions CI/CD Engineering Standards

This skill codifies 2026 GitHub Actions best practices — secure supply chains, efficient caching, reusable workflows, and hardened permission models.

1. Security: SHA Pinning (Mandatory)

Pin Every Third-Party Action to a Commit SHA

# ✅ Good: SHA-pinned (immutable, auditable)
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.2.2
- uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde8c81c89c3166c0 # v4.2.0

# ❌ Bad: Tag-pinned (mutable, vulnerable to supply chain attacks)
- uses: actions/checkout@v4
- uses: actions/setup-node@v4

• ALWAYS pin to full-length commit SHAs — tags are mutable and can be hijacked
• ALWAYS add a trailing comment with the version for human readability
• Use tools like step-security/harden-runner or pin-github-action CLI to automate SHA resolution
• Resolve SHA Manually: See templates.md for the gh api command to resolve SHAs.
• Audit quarterly — review all pinned SHAs when updating workflow dependencies

Permission Hardening

# Set restrictive defaults at the workflow level
permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    # Grant specific permissions per-job
    permissions:
      contents: read
      packages: write

• ALWAYS set permissions: at the workflow level — use read-all or specify individually
• NEVER use permissions: write-all — it grants maximum privileges
• Grant write only where needed — per-job, not per-workflow

2. Workflow Structure

Standard CI Template

See templates.md for a complete, production-ready CI workflow template.

Key Structural Rules

• ALWAYS set concurrency with cancel-in-progress: true to prevent stale runs
• Use needs: to create a dependency chain: lint → test → build → deploy
• Use .node-version or .python-version files — never hardcode versions in workflows
• Use --frozen-lockfile — never let CI modify the lock file