github-actions-advanced

GitHub Actions Advanced Skill

Expert guidance for designing, writing, debugging, and securing production-grade GitHub Actions workflows.

---

Detailed Guide

Read the detailed guide before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.

When to Use This Skill

• User mentions GitHub Actions, .github/workflows, CI/CD pipelines, runners, jobs, steps, or actions
• User wants to automate builds, tests, deployments, or releases via GitHub
• User asks about matrix builds, reusable workflows, composite actions, or self-hosted runners
• User needs help with OIDC authentication, caching strategies, or secrets management
• User says "my GitHub pipeline is failing" or "set up CI for my repo"
• User asks about workflow security, hardening, or environment protection rules

When NOT to Use This Skill

• The user is working with GitLab CI/CD → recommend gitlab-ci-patterns
• The user is working with CircleCI, Jenkins, or other CI platforms
• The task is purely about Docker image building without GitHub context → recommend docker-expert
• The task is about Kubernetes deployment configuration → recommend kubernetes-architect

---

Security Hardening

1. Always Declare Permissions (Least Privilege)

# Workflow-level default — restrict everything
permissions:
  contents: read

jobs:
  publish:
    # Job-level override — only expand what's needed
    permissions:
      contents: write        # Only for release/publish jobs
      packages: write        # Only for container push jobs
      pull-requests: write   # Only for PR comment jobs
      id-token: write        # Only for OIDC auth jobs

2. Pin Third-Party Actions to Full Commit SHA

# ❌ UNSAFE — tag can be mutated or hijacked
- uses: actions/checkout@v4

# Full SHA prevents tag movement; verify its origin and content (not a safety certification)
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

# Tool to automate SHA pinning:
# npx pin-github-action .github/workflows/*.yml
# or: pip install ratchet && ratchet pin .github/workflows/

3. Prevent Script Injection

# ❌ UNSAFE — attacker controls PR title, which gets expanded in shell
- run: echo "${{ github.event.pull_request.title }}"

# ✅ SAFE — pass through environment variable (shell doesn't evaluate it)
- env:
    PR_TITLE: ${{ github.event.pull_request.title }}
  run: echo "$PR_TITLE"

# ✅ SAFE — expressions in if: conditions are evaluated by Actions, not shell
- if: github.event.pull_request.draft == false
  run: echo "Not a draft"

Never place ${{ ... }} directly inside run: when the value can come from PR metadata, workflow inputs, repository files, matrix JSON, or earlier job outputs. Put it in env: first, validate allowlisted values where possible, and reference the shell variable with quotes.

4. Restrict pull_request_target Usage

# A label/association gate alone does NOT prevent untrusted execution.
# Use this event only for trusted base-code metadata tasks with narrow permissions.
on:
  pull_request_target:
    types: [labeled]

jobs:
  validate:
    # Double-guard: check label name AND author_association
    if: |
      github.event.label.name == 'safe-to-test' &&
      (github.event.pull_request.author_association == 'COLLABORATOR' ||
       github.event.pull_request.author_association == 'MEMBER' ||
       github.event.pull_request.author_association == 'OWNER')

Privileged jobs must not execute PR-controlled code or artifacts regardless of label. Check actor authorization and exact reviewed head for any separately approved action; a push after labeling changes the code. Restrict OIDC audience/subject to the exact repository and branch/environment, with minimal cloud roles. Never promote untrusted caches/artifacts into deployment code.

5. Harden with StepSecurity

# Optional third-party control: review version, permissions, supported runner and telemetry handling before adoption.
- uses: step-security/harden-runner@4d991eb9995541a0b71d1b66f1f98a5f1bef422c  # v2.11.0
  with:
    egress-policy: audit          # Start with 'audit', move to 'block' after confirming allowlist
    allowed-endpoints: >
      api.github.com:443
      registry.npmjs.org:443
      objects.githubusercontent.com:443

---

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Always test reusable workflows in a feature branch before merging to main.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.