secure-github-actions

Secure GitHub Actions

Create, review, and audit GitHub Actions workflows with supply-chain-safe defaults.

CRITICAL RULES

1. Read the relevant reference files first. When the user's request involves any topic in the reference table below, read those files before doing anything else. Briefly mention which files you are reading so the user can confirm the skill is active.
2. Pin every non-local uses: reference to a full 40-character commit SHA. Treat @v*, @main, @master, branch names, and short SHAs as security debt.
3. Never invent SHAs. Resolve them from GitHub or ask the user; if you cannot verify the right SHA, say so explicitly instead of fabricating one.
4. Do not introduce pull_request_target unless the user explicitly requires it and the workflow never executes untrusted code with secrets or write permissions.
5. Never splice untrusted context directly into shell. Move ${{ github.* }}, ${{ inputs.* }}, and similar values into env: and quote the shell variable.
6. Set explicit least-privilege permissions:. Default to read-only and grant write scopes only to the specific job that needs them.
7. Always run the full audit checklist when asked to "audit", "harden", or "security scan" a repository.
8. Never silently skip a check. If a tool is missing (gitleaks, trufflehog, zizmor), report it and suggest installation.
9. After compaction or context loss, re-read this SKILL and the reference files before continuing.

Operating procedure

For writing or editing workflows

1. Classify the task: new workflow, workflow edit, reusable workflow, or security review.
2. Read references/workflows.md and references/secure-patterns.md.
3. Audit every uses: reference:
   • Local actions like ./.github/actions/foo are fine.
   • Step-level actions and job-level reusable workflows must use full SHAs.
   • Preserve the human release label in a comment (e.g., # v4.3.1).
4. Audit the trust boundary:
   • Prefer pull_request over pull_request_target.
   • Assume forked PR data is untrusted.
   • Avoid exposing secrets or write tokens to untrusted code paths.
5. Audit every run: step:
   • Pass dynamic values through env:.
   • Quote shell variables.
   • Prefer simple shell over adding a new third-party action when either works.
6. Add or update maintenance guardrails:
   • Ensure Dependabot updates the github-actions ecosystem.
   • Call out transitive risk: pinned actions can still reference mutable actions internally.

For full security audits

When asked to "audit", "harden", or "security scan" a repository:

1. Read references/audit-checklist.md.
2. Execute all checks, using subagents to parallelize where possible.
3. Present findings grouped by severity: CRITICAL, HIGH, MEDIUM, LOW.
4. End with a summary table and prioritized action list.

Reference files

Topic	File	Read when...
Workflow hardening patterns	references/workflows.md	Creating, editing, or reviewing workflows
Secure workflow templates	references/secure-patterns.md	Writing new workflows from scratch
Full audit procedure	references/audit-checklist.md	Running a security audit on a repository
SHA pinning automation	references/sha-pinning.md	Pinning actions to commit SHAs

Tools

The audit checks for these tools and reports missing ones:

Tool	Purpose	Install
gitleaks	Scan git history for secrets	brew install gitleaks
trufflehog	Deep secrets scanning with verification	brew install trufflehog
zizmor	Static analysis for GH Actions	brew install woodruffw/tap/zizmor
gh	GitHub CLI for API calls	brew install gh