Secure GitHub Actions
Create, review, and audit GitHub Actions workflows with supply-chain-safe defaults.
CRITICAL RULES
- 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.
- 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. - 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.
- Do not introduce
pull_request_targetunless the user explicitly requires it and the workflow never executes untrusted code with secrets or write permissions. - Never splice untrusted context directly into shell. Move
${{github.*}},${{inputs.*}}, and similar values intoenv:and quote the shell variable. - Set explicit least-privilege
permissions:. Default to read-only and grant write scopes only to the specific job that needs them. - Always run the full audit checklist when asked to "audit", "harden", or "security scan" a repository.
- Never silently skip a check. If a tool is missing (gitleaks, trufflehog, zizmor), report it and suggest installation.
- After compaction or context loss, re-read this SKILL and the reference files before continuing.
Operating procedure
For writing or editing workflows
- Classify the task: new workflow, workflow edit, reusable workflow, or security review.
- Read references/workflows.md and references/secure-patterns.md.
- 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).
- 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.
- 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.
- 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:
- Read references/audit-checklist.md.
- Execute all checks, using subagents to parallelize where possible.
- Present findings grouped by severity: CRITICAL, HIGH, MEDIUM, LOW.
- 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 |