--- name: harden-github-actions description: Harden GitHub Actions CI/CD workflows for supply-chain security — SHA-pin actions, least-privilege token permissions, verified toolchain installs, OpenSSF Scorecard, and SLSA provenance. Use when adding or auditing GitHub Actions workflows, before making a repository public, when a supply-chain review flags CI gaps, or when standardizing CI hardening across GitHub projects. GitHub-specific by design — GitLab CI and Forgejo Actions are out of scope. metadata: author: "Georges Martin <jrjsmrtn@gmail.com>" version: "0.1.34" license: MIT ---

# Harden GitHub Actions

Harden GitHub Actions CI/CD workflows against supply-chain attack: pin what runs, minimise what it can do, and verify what it fetches.

> **GitHub-specific by design.** Unlike most orchestration skills, this one is deliberately bound to > one forge. The hardening controls below are not portable concepts wearing GitHub syntax — they are > properties of the GitHub Actions execution model itself: third-party actions resolved by mutable > git ref, an ambient `GITHUB_TOKEN` with **repository-wide default scopes**, and OIDC-backed SLSA > provenance. It has a **sibling**, `harden-gitlab-ci`, which is not a translation of this skill: > GitLab's risks sit in different places (`include:`/CI-Catalog components, and a `CI_JOB_TOKEN` that > defaults to *own-project-only* — so there the work is keeping it scoped, the opposite posture from > here). Forgejo Actions is Actions-compatible in shape but resolves actions against its instance's > configured registry, so pinning guidance does not transfer unchanged (roadmap H9).

## When to Use

- When adding GitHub Actions workflows to a project (after `setup-git-hooks`) - When auditing existing `.github/workflows/` before making a repository public - When a supply-chain review (or the `supply-chain` skill) flags CI hardening gaps - When standardising CI hardening across GitHub projects

**Not for:** GitLab CI — use `harden-gitlab-ci`. Not for Forgejo/Gitea Actions — the controls do not carry over unchanged. Say so rather than approximating.

This skill *hardens* CI workflows. `validate-quality-config` only *reads* CI to confirm parity with local hooks — it does not check pinning, permissions, or provenance. The two are complementary.

## Required Inputs

1. **Workflow files** — the project's `.github/workflows/*.yml` 2. **Release model** — does the project publish artifacts/images/packages (needs provenance + signing), or is it internal-only? 3. **Repository visibility** — public or private (affects Scorecard `publish_results` and OSSF publishing)

## The Threat

A CI job runs third-party code (actions, installed tools) with a `GITHUB_TOKEN` and often OIDC. A mutable action tag (`@v4`) can be repointed to malicious code; an over-privileged token can push commits, publish packages, or exfiltrate secrets; an unverified `curl | sh` install can be swapped upstream. Hardening closes all three: **pin**, **least-privilege**, **verify**.

## Workflow

### Step 1: Inventory and triage

Find every workflow and the hardening gaps in it:

```bash ls .github/workflows/ # Mutable action refs (should be zero — all must be SHA-pinned): grep -rnE 'uses:.*@(v[0-9]|main|master|latest)' .github/workflows/ # Workflows missing a top-level permissions block: for f in .github/workflows/*.yml; do grep -q '^permissions:' "$f" || echo "no permissions: $f"; done # Floating tool versions: grep -rnE 'version:\s*latest|@latest' .github/workflows/ ```

Aim for a clean 3-way split: **`ci.yml`** (lint/test/build on push + PR), **`scorecard.yml`** (OpenSSF Scorecard on a schedule), and — only if the project ships artifacts — **`release.yml`** (SBOM + SLSA provenance + signing).

### Step 2: SHA-pin every action

Pin every `uses:` to a **full 40-character commit SHA** with a trailing `# vX.Y.Z` comment for readability. Never rely on a mutable tag.

```yaml # Good — immutable, human-readable, Dependabot-updatable - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - uses: actions/setup-java@ad2b38190b15e4d6bdf0c97fb4fca8412226d287 # v5.3.0 - uses: gradle/actions/setup-gradle@3f131e8634966bd73d06cc69884922b02e6faf92 # v6.2.0

# Bad — mutable tag, can be repointed upstream - uses: actions/checkout@v4 ```

Resolve a tag to its commit SHA:

```bash gh api repos/actions/checkout/commits/v4.2.2 --jq '.sha' ```

Keep pins current automatically with a Dependabot `github-actions` update block (see `bootstrap-project` / the dependency-update config). Dependabot preserves the `# vX.Y.Z` comment when it bumps a SHA.

**The one sanctioned exception**: reusable workflows that verify their own release tag — notably `slsa-framework/slsa-github-generator` — **must** be referenced by semantic version tag, not SHA (see Step 7). Document the exception in an ADR and in a comment on the line.

### Step 3: Least-privilege token permissions

Set a read-only default at the top of every workflow, then elevate **per job** only where a job genuinely needs to write.

```yaml # top of the workflow permissions: contents: read ```

Elevate narrowly, in the specific job:

```yaml jobs: # OpenSSF Scorecard analysis: permissions: security-events: write # upload the SARIF result id-token: write # publish results to the OSSF API contents: read

# Release provenance / publish provenance: permissions: actions: read # read the workflow path id-token: write # mint the OIDC token for signing contents: write # attach provenance to the release # packages: write # add only if publishing to GHCR / a registry ```

Rule of thumb: default `contents: read`; add `id-token: write` only for OIDC signing/publish; add `contents: write` only for jobs that create releases/tags; add `packages: write` only for registry publish; add `security-events: write` only for SARIF upload.

### Step 4: Harden the checkout

On any workflow that runs with elevated permissions or handles releases (Scorecard, release), stop the checkout from leaving credentials on disk:

```yaml - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: persist-credentials: false ```

### Step 5: Verify what you install

Every tool a job installs is attack surface. In order of preference:

1. **SHA-pinned setup action** (best) — toolchains via pinned actions: ```yaml - uses: actions/setup-java@ad2b38190b15e4d6bdf0c97fb4fca8412226d287 # v5.3.0 with: { distribution: temurin, java-version: "21" } - uses: xu-cheng/texlive-action@22c04326a5d855880f9d39bb955138bf11c6df80 # v3 ``` 2. **Pinned version + checksum verification** for a downloaded binary: ```yaml - run: | curl -fsSL -o tool.tar.gz "https://example.com/tool/v1.2.3/tool.tar.gz" echo "abc123... tool.tar.gz" | sha256sum -c - tar xzf tool.tar.gz ``` 3. **Pinned package version** for distro/language packages.

Anti-patterns to eliminate (all seen in real workflows):

```yaml - run: luarocks install luacheck # no version pin - run: apt-get install -y -qq pandoc # unversioned distro package with: { version: latest } # floating action release - run: curl -fsSL https://x/install.sh | sh # unverified remote script — never ```

Digest-pin any container image referenced in a `run`/service step (`image@sha256:…`, not `:latest`); base-image and artifact-checksum hardening for the images themselves belongs to `setup-container-security`.

### Step 6: OpenSSF Scorecard

Add a Scorecard workflow to continuously grade the repo's supply-chain posture. Canonical `scorecard.yml`:

```yaml name: Scorecard on: branch_protection_rule: schedule: - cron: "26 7 * * 1" # weekly, Mondays workflow_dispatch:

permissions: read-all

jobs: analysis: runs-on: ubuntu-latest permissions: security-events: write # upload the SARIF result id-token: write # publish results to the OSSF API contents: read steps: - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: persist-credentials: false - uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3 with: results_file: results.sarif results_format: sarif publish_results: true # requires a PUBLIC repo; keep false while private - uses: github/codeql-action/upload-sarif@dd903d2e4f5405488e5ef1422510ee31c8b32357 # v3 with: sarif_file: results.sarif ```

On a **private** repo set `publish_results: false` — but note that several Scorecard *checks* also fail to run while private (`Resource not accessible by integration`); prefer gating the whole job on visibility so it self-activates at the public gate (see **Step 7b**).

**Scorecard grades the default branch — mind gitflow.** Scorecard's content analysis runs against the repository's **default branch** (a `workflow_dispatch` against another ref is refused with `only default branch is supported` — observed directly). If the project follows the gitflow that `bootstrap-project` sets up, `develop` is the default, so the published score describes the **integration** branch, not the `main` that releases are cut from — the repo is graded on a branch its consumers never fetch. The one documented exception is the **`Branch-Protection`** check, which evaluates a project's *default **and** release* branches (verified against the Scorecard docs); the content-analysis checks (`Pinned-Dependencies`, `Dangerous-Workflow`, `Token-Permissions`, …) do not. Two honest resolutions: accept that `develop` is graded and protect/harden it accordingly, or make `main` the default and treat `develop` as a long-lived branch. Pick one on purpose — this gap lives only where the gitflow recommendation and the Scorecard workflow meet, so neither skill alone would surface it.

### Step 7: Release provenance (if the project ships artifacts)

For projects that publish artifacts/images/packages, attach SLSA build provenance at release. Hash the build outputs, then hand off to the generator — referenced **by tag** (the sanctioned exception to Step 2):

```yaml provenance: # MUST run after the job that creates the release: with upload-assets:true the generator # creates the release itself when absent, racing publish and producing a bare, notesless one. needs: [build, publish] permissions: actions: read id-token: write contents: write # slsa-github-generator MUST be tag-pinned (it verifies its own release tag) — the # documented exception to the SHA-pin rule; record it in an ADR. uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v2.1.0 with: base64-subjects: ${{ needs.build.outputs.hashes }} upload-assets: true ```

Provenance, SBOM (syft), and keyless signing (cosign) at release time are owned by `wrapup-sprint`'s release step — this skill wires the workflow permissions and the tag-pin exception that make them safe. Note the `needs: [build, publish]` above: because `upload-assets: true` makes the generator *create* the release when it runs first, provenance must follow the job that publishes it with changelog notes — the idempotent create-release step is detailed in `wrapup-sprint`.

### Step 7b: Private repositories — gate visibility-sensitive controls

Several controls above behave differently while the repo is private, for **two distinct reasons** — *cannot run* and *should not run* — and neither is obvious until you run them (the failures arrive at the first scheduled Scorecard run and Dependabot's first PR). The honest default is to **self-activate them at the public gate** rather than leave a manual step to remember. Gate the job (or step) on visibility:

```yaml if: ${{ !github.event.repository.private }} # runs only when the repo is public ```

| Con