GitHub Actions hardening for agent workflows

# AGENTS.md: GitHub Actions hardening

Rules for writing or changing anything under `.github/workflows/`, including workflows that run AI agents on issues
and pull requests. A workflow is code that runs with the repository's tokens and secrets; review it like code.

## Every workflow
- Pin every third-party action to a full commit SHA with the version in a comment:
  `uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1`. Tags and branches can be moved.
  Keep pins current with Dependabot (`package-ecosystem: github-actions`), not by switching back to tags.
- `permissions: {}` at the top, then grant each job only what it needs (`contents: read`, `issues: write`, ...).
- `actions/checkout` with `persist-credentials: false` unless a later step must push.
- Never write `${{ github.event.* }}`, `${{ github.head_ref }}` or other attacker-controllable values inside `run:`.
  Pass them through `env:` and quote the variable: `TITLE: ${{ github.event.issue.title }}` then `"$TITLE"`.
- Secrets only in the steps that need them, through `env:` or `with:`. Never echo them or write them to files that
  are uploaded as artifacts.
- Pin runner images (`ubuntu-24.04`, not `ubuntu-latest`) when reproducibility matters.

## Triggers
- Avoid `pull_request_target` and `workflow_run`. If one is unavoidable, never check out or run the pull request's
  code in that job, and never give it secrets.
- Code from forks runs under `pull_request`, with a read-only token and no secrets. Keep it that way.

## Workflows that run AI agents
- Issue and PR text is untrusted input to the agent. Run the agent job with a read-only token and no write secrets.
- Split "think" from "act": the agent job writes its proposal to an artifact or output; a separate job with narrow
  write permission applies it after checks (labels from a fixed list, comments only, no pushes to default branches).
- Pin agent actions and CLIs to exact versions, and cap spend and turns where the tool supports it.

## Before finishing
- Run the `harden-workflow` skill: `uvx zizmor@1.31.1 --offline .github/workflows` must report no findings, or each
  remaining finding is justified in a comment and the PR description.
- Do not push workflow changes to the default branch or re-run workflows with secrets unless the user asks.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `harden-workflow`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "GitHub Actions hardening for agent workflows" v1.0.0 — https://loadout.jnw-it.com/loadouts/github-actions-hardening/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `harden-workflow`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "GitHub Actions hardening for agent workflows" v1.0.0 — https://loadout.jnw-it.com/loadouts/github-actions-hardening/ -->

---
name: harden-workflow
description: Audit and fix GitHub Actions workflows with zizmor before they are committed. Pins actions to commit SHAs, narrows permissions, removes template injection and unsafe triggers. Use for any change under .github/workflows.
---

# Harden a workflow

Example of the target shape: `references/issue-triage.yml`.

1. Audit offline (no token needed): `uvx zizmor@1.31.1 --offline .github/workflows`. Exit code 0 means no findings.
   With a `GH_TOKEN`, drop `--offline` to enable the online audits (known-vulnerable actions, impostor commits).
2. Fix by audit name:
   - `unpinned-uses`: resolve the SHA for the tag you want with
     `gh api repos/OWNER/REPO/git/ref/tags/TAG --jq .object.sha`. If `.object.type` is `tag` (annotated),
     follow it once more with `gh api repos/OWNER/REPO/git/tags/SHA --jq .object.sha`. Write
     `uses: OWNER/REPO@SHA # TAG`.
   - `template-injection`: move the expression into `env:` and reference `"$VAR"` in the script.
   - `excessive-permissions`: add `permissions: {}` at the top and per-job grants.
   - `artipacked`: set `persist-credentials: false` on checkout.
   - `dangerous-triggers`: switch `pull_request_target` to `pull_request`, or split privileged work into a job that
     never touches PR code.
3. Re-run zizmor until clean. If you must keep a finding, add an inline `# zizmor: ignore[audit-name]` comment with
   the reason, and mention it to the user.
4. Check the workflow still parses: `gh workflow view <file>` on a pushed branch, or `actionlint` if installed.
5. Summarise the changes for the user. Do not push to the default branch yourself.

# Labels new issues from their title. Shows the hardened shape: SHA pins, no default permissions,
# per-job grants, no persisted credentials, untrusted text passed through env.
name: issue-triage
on:
  issues:
    types: [opened]

permissions: {}

jobs:
  triage:
    runs-on: ubuntu-24.04
    timeout-minutes: 5
    permissions:
      contents: read
      issues: write
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - name: Pick a label from a fixed list
        id: pick
        env:
          TITLE: ${{ github.event.issue.title }}
        run: |
          label=question
          case "${TITLE,,}" in
            *bug*|*crash*|*error*) label=bug ;;
            *feature*|*request*) label=enhancement ;;
          esac
          echo "label=$label" >> "$GITHUB_OUTPUT"
      - name: Apply the label
        env:
          GH_TOKEN: ${{ github.token }}
          ISSUE: ${{ github.event.issue.number }}
          LABEL: ${{ steps.pick.outputs.label }}
        run: gh issue edit "$ISSUE" --repo "$GITHUB_REPOSITORY" --add-label "$LABEL"