Expert guidance for designing, writing, debugging, and securing production-grade GitHub Actions workflows.
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
Step 1: Understand Context Before Responding
When invoked, first gather context:
# Discover existing workflows in the repo
find .github/workflows -name "*.yml" -o -name "*.yaml" 2>/dev/null | head -20
# Check for composite actions
find .github/actions -name "action.yml" 2>/dev/null
# Detect tech stack (influences runner OS, language setup actions)
ls package.json requirements.txt Gemfile go.mod Cargo.toml pom.xml 2>/dev/null
Then adapt recommendations to:
Existing workflow patterns in the repo
The tech stack and language runtime
Whether this is a monorepo or single-project repo
Whether self-hosted or GitHub-hosted runners are in use
Workflow Structure Reference
name: Workflow Name
on: # Triggers (see Triggers section)
push:
branches: [main]
permissions: # Always declare — principle of least privilege
contents: read
env: # Workflow-level env vars
NODE_VERSION: '20'
concurrency: # Prevent duplicate runs
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true # Cancel older runs for same branch
jobs:
job-id:
name: Human-readable name
runs-on: ubuntu-24.04 # Pin OS version — never use -latest in prod
timeout-minutes: 15 # Always set — prevents runaway jobs
environment: production # Links to GitHub Environment (approvals/secrets)
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
- name: Step name
run: echo "hello"
Triggers (on:)
Common Patterns
on:
push:
branches: [main, 'release/**']
paths-ignore: ['**.md', 'docs/**'] # Skip docs-only changes
pull_request:
types: [opened, synchronize, reopened]
branches: [main]
workflow_dispatch: # Manual trigger with inputs
inputs:
environment:
description: 'Deploy target'
required: true
type: choice
options: [staging, production]
dry-run:
description: 'Dry run only?'
type: boolean
default: false
schedule:
- cron: '0 2 * * 1' # Monday 2am UTC
workflow_call: # Called by other workflows (reusable)
inputs:
image-tag:
type: string
required: true
secrets:
deploy-token:
required: true
release:
types: [published] # Trigger only on published releases
pull_request_target: # Runs with repo secrets — use with care!
types: [labeled] # Gate with label + author_association check
Security Warning:pull_request_target runs with repo secrets. Only use after a maintainer labels the PR. Never check out fork code without explicit sandboxing.
Reusable Workflows
Split large pipelines into composable units stored in .github/workflows/.
Convention: Prefix internal/reusable workflows with _ (e.g., _build.yml).
- name: Generate and mask dynamic token
run: |
TOKEN=$(./scripts/generate-token.sh)
echo "::add-mask::$TOKEN" # Mask in all subsequent logs
echo "DEPLOY_TOKEN=$TOKEN" >> $GITHUB_ENV
Secrets in Composite Actions
# Secrets cannot be passed as inputs to composite actions
# Pass them as env vars instead:
- uses: ./.github/actions/my-action
env:
SECRET_VALUE: ${{ secrets.MY_SECRET }}
Composite Actions
Package reusable step sequences into local actions. No container spin-up, no separate workflow file needed.
# 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
# ✅ SAFE — commit SHA is immutable
- 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
# Only run when a maintainer adds a specific label — prevents untrusted execution
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')
5. Harden with StepSecurity
# Add to every workflow — hardens runner, monitors outbound traffic
- 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
Debugging Techniques
# Enable runner diagnostic logging via repo secrets:
# ACTIONS_RUNNER_DEBUG = true
# ACTIONS_STEP_DEBUG = true
# Dump full GitHub context for inspection
- name: Debug — dump github context
if: runner.debug == '1'
env:
GITHUB_CONTEXT: ${{ toJson(github) }}
run: echo "$GITHUB_CONTEXT" | jq '.'
# Dump all available contexts
- name: Debug — dump all contexts
if: runner.debug == '1'
run: |
echo "github: ${{ toJson(github) }}"
echo "env: ${{ toJson(env) }}"
echo "vars: ${{ toJson(vars) }}"
echo "runner: ${{ toJson(runner) }}"
# SSH into a failing runner for interactive debugging
- uses: mxschmitt/action-tmate@7b04f3521e6b0a9fc56fa8f9f50da4bcfb5fc7b5 # v3.19.0
if: failure() && runner.debug == '1'
with:
limit-access-to-actor: true # Only the workflow triggerer can SSH in
timeout-minutes: 30
# Check what's pre-installed on GitHub-hosted runners
- run: |
echo "=== Tool Versions ==="
node --version
python3 --version
go version
docker --version
echo "=== Disk Space ==="
df -h
echo "=== Memory ==="
free -h
