build-github-workflow

name	build-github-workflow
description	Scaffolds a GitHub Actions workflow — a YAML file under `.github/workflows/` — with top-level least-priv `permissions:`, SHA-pinned `uses:`, per-job `timeout-minutes`, workflow-level `defaults.run.shell: bash`, scoped triggers, `harden-runner` as first step, `set -euo pipefail` in every multi-line `run:`, and deliberate concurrency posture (cancel-in-progress for PR/push, no-cancel for deploy). Use when the user wants to "scaffold a ci workflow", "create a github workflow", or "build a github actions workflow for X". Not for composite actions (`action.yml` — separate primitive), org rulesets, Dependabot configs, or GitHub Apps.
allowed-tools	Read, Write, Edit, Bash, Grep, Glob
argument-hint	[purpose]
user-invocable	true
references	["../../_shared/references/github-workflow-best-practices.md","../../_shared/references/primitive-routing.md"]
license	MIT

Build GitHub Workflow

Scaffold a GitHub Actions workflow: a single YAML file under .github/workflows/ that runs on repository events, holds an explicit permissions / timeout / concurrency / pinning posture, and stays under the Checks-UI-and-required-checks contract. The authoring rubric — anatomy template, authoring principles, patterns that work, anti-patterns — lives in github-workflow-best-practices.md. This skill is the workflow; the principles doc is the rubric.

The scope is a single workflow file. Composite actions, organization rulesets, Dependabot configs, and GitHub Apps are separate primitives.

Workflow sequence: 1. Route → 2. Scope Gate → 3. Elicit → 4. Draft → 5. Safety Check → 6. Review Gate → 7. Save → 8. Test

When to use

Also fires when the user phrases the request as:

• "new deploy workflow"
• "write a release workflow"

1. Route

Confirm a GitHub Actions workflow is the right primitive before asking scaffold questions.

Wrong primitive:

• Composite action (a reusable unit under .github/actions/<name>/ with an action.yml exposing inputs/outputs/runs) — a different rubric (input schemas, runs.using, release tagging). No /build:build-github-action skill exists yet; hand-author.
• Organization ruleset / branch protection config — lives in GitHub settings, not in .github/workflows/.
• Dependabot config (.github/dependabot.yml) — different schema.
• CODEOWNERS — .github/CODEOWNERS, different schema.
• A Claude Code hook — route to /build:build-hook.
• A shell script that runs in CI — the workflow is the trigger; the script goes to /build:build-bash-script and is called from the workflow.

Right primitive (YAML file fired by a repository event, runs jobs on a runner, uses the GITHUB_TOKEN) → proceed to Scope Gate.

2. Scope Gate

Refuse to scaffold — and recommend an alternative — when the request signals one of these:

1. Composite action authoring. Out of scope; hand-author or wait for /build:build-github-action. Do not approximate a composite action shape inside .github/workflows/.
2. pull_request_target + checkout of PR code. Textbook Actions CVE vector. Refuse and explain: this combination has no safe form — fork code executes with base-repo write permissions and secrets. Offer pull_request (no secrets for forks; safe) or pull_request_target without PR checkout as alternatives.
3. @main, @master, or floating semver wildcards for any uses:. Refuse and explain: mutable refs are unreproducible and unsafe. Ask the user for a pinnable SHA or major tag; offer to resolve a SHA via gh api if they approve.
4. Secrets in public-repo fork pull_request workflows. Secrets can't safely reach fork PR code. Refuse and explain; recommend splitting into a pull_request (no secrets) and a merge- or label-triggered workflow (with secrets).
5. Self-hosted runners on public-repo pull_request workflows. PR code would execute on your infrastructure. Refuse and explain.
6. Multi-workflow refactor. This skill scaffolds one file. For splitting an omnibus workflow or introducing reusable workflows across several files, iterate — scaffold one at a time.

If any signal fires, state the signal, name the alternative, and stop. Do not proceed to Elicit.

3. Elicit

If $ARGUMENTS is non-empty, parse it as [purpose] and pre-fill question 1. Otherwise ask, one question at a time:

1. Purpose — one sentence: what does this workflow do? ("Run pytest on pull requests against main", "Deploy the prod service on a v* tag push", "Nightly lockfile audit at 03:00 UTC".) Drives the filename (ci.yml, deploy-prod.yml, audit-locks.yml).

2. Triggers — pick the set deliberately:

• push — branch list (e.g., [main]), paths: filter if the workflow only cares about a subset.
• pull_request — branch list, types: (default [opened, synchronize, reopened] — name explicitly if different).
• schedule — cron expression (randomize the minute; never 0).
• workflow_dispatch — inputs with type: choice where possible; document each input.
• workflow_call — this becomes a reusable workflow; declare inputs: and secrets:.

Any use of pull_request_target triggers a Scope Gate re-check — return to Step 2.

3. Jobs and dependencies — which work splits across which jobs? Which jobs needs: which? Prefer small jobs with explicit needs: over one large job; parallelism is free, serial jobs block the DAG.

4. Runner — ubuntu-latest (CI) vs pinned ubuntu-24.04 (release / deploy). Ask: "Is this a release or deploy workflow? Pin the runner if yes." Self-hosted requires justification; public-repo pull_request workflows cannot use self-hosted.

5. External actions — full list. For each: full 40-char commit SHA (user provides, or Claude offers to fetch via gh api with user approval). First-party actions/*/github/* may tag-pin (@v4) with an inline comment and Dependabot coverage — otherwise SHA.

6. Deploys? — if yes: target environment: name; required reviewers configured? Promise the user the environment: key will be scaffolded; actual protection rules are a GitHub UI configuration.

7. Cloud authentication — OIDC (provider + role ARN/federated identity) or static secrets (discouraged). If OIDC, scaffold permissions: id-token: write and the federated-credentials step; if static, warn and scaffold with a comment pointing to OIDC migration.

8. Concurrency behavior — cancel-in-progress (default for PR/push workflows) or no-cancel (mandatory for deploy/release — scaffold rejects cancel-in-progress: true on deploys).

9. Artifacts? — names, retention-days. Skip artifact block if none.

10. Save path — must be under .github/workflows/. Default: .github/workflows/<derived-from-purpose>.yml. Confirm the filename.

4. Draft

Produce two artifacts.

Artifact 1: The workflow YAML.

One conditionalized template. Sections marked (if deploy), (if OIDC), (if schedule), (if destructive), (if has-artifacts) are omitted when intake rules them out.

name: <Purpose>                                                 # from Step 3.1

on:
  # <triggers from Step 3.2, scoped with paths/branches/types>
  push:
    branches: [main]
    paths: ['<path-filter>']

permissions:                                                    # top-level least-priv
  contents: read
  # id-token: write                                             # (if OIDC)

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true                                      # (false or omitted for deploy)

defaults:
  run:
    shell: bash

jobs:
  <job-id>:                                                     # kebab-case IDs
    name: <Job Name>
    runs-on: ubuntu-latest                                      # pinned for deploy/release
    timeout-minutes: 20                                         # every job
    # environment: <env-name>                                   # (if deploy)
    # needs: <upstream-job-id>                                  # (if dependent)
    permissions:                                                # (elevate only if job needs it)
      contents: read
    steps:
      - name: Harden runner
        uses: step-security/harden-runner@<SHA>                 # v<N>.<M>.<P>
        with:
          egress-policy: audit

      - name: Checkout
        uses: actions/checkout@<SHA>                            # v<N>
        with:
          persist-credentials: false
          fetch-depth: 1

      # <language setup with built-in caching>
      - name: Setup
        uses: actions/setup-<lang>@<SHA>                        # v<N>
        with:
          <lang>-version: '<version>'
          cache: <ecosystem>

      # <OIDC cloud auth — if Step 3.7 = OIDC>
      # - name: Configure AWS credentials
      #   uses: aws-actions/configure-aws-credentials@<SHA>
      #   with:
      #     role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
      #     aws-region: us-east-1

      - name: <Action>
        env:
          # Route user-controlled context through env, NEVER ${{ }} in run
          PR_TITLE: ${{ github.event.pull_request.title }}
        run: |
          set -euo pipefail
          # <body — extract to a script under .github/scripts/ past ~20 lines>

      # (if has-artifacts)
      - name: Upload artifact
        uses: actions/upload-artifact@<SHA>                     # v<N>
        with:
          name: <artifact-name>
          path: <path>
          retention-days: 7                                     # minimum the workflow needs

Artifact 2: A commit summary — one paragraph naming what the workflow does, what triggers it, what it produces (checks, artifacts, deploys), and the first-run expectation. Used for the commit message or PR description.

Present both artifacts before safety checks.

5. Safety Check

Review the draft against github-workflow-best-practices.md before presenting. Fail any check → revise; the Review Gate is for user approval, not correctness recovery.

Structure:

• Top-level name: present
• Triggers scoped (paths / branches / types named deliberately)
• Top-level permissions: present and is not write-all
• Workflow-level defaults.run.shell: bash
• Concurrency group defined; cancel-in-progress: true iff not a deploy/release workflow
• Every job has name: and timeout-minutes:
• Job/step IDs are kebab-case

Pinning:

• Every uses: is a 40-char commit SHA, or a first-party tag with an inline comment documenting the exemption
• No @main, @master, @v*.*, or other mutable ref
• Any docker:// image has an explicit non-latest tag or @sha256: digest

Safety:

• step-security/harden-runner is the first step of every job (audit or block mode)
• actions/checkout has persist-credentials: false unless a push step is present
• No ${{ github.event.* }} / github.head_ref / inputs.* in any run: block body — user-controlled context routed through env:
• pull_request_target unused, or if used, no PR-ref checkout
• No ${{ secrets.* }} in top-level env:
• No ${{ secrets.* }} in pull_request workflows without source gating
• If public-repo pull_request: no self-hosted runners

Correctness:

• Every multi-line bash run: block starts with set -euo pipefail
• No deprecated commands (::set-output, ::set-env, ::add-path)
• continue-on-error: true present only on steps with an inline comment justifying non-blocking behavior
• needs: explicit between jobs that depend on each other

Deploy-specific (if deploy):

• environment: key present with a name
• Runner pinned (ubuntu-24.04, not ubuntu-latest)
• cancel-in-progress is false or omitted

Artifacts (if has-artifacts):

• Every actions/upload-artifact has explicit name and retention-days

6. Review Gate

Present the workflow YAML and the commit summary. Wait for explicit user approval before writing any file to disk. Write only after this gate passes.

If the user requests changes, revise and re-present. Continue until the user explicitly approves or cancels. Proceed to Save only on explicit approval.

7. Save

Write the approved workflow to the path elicited in Step 3.10 — must be under .github/workflows/. No other save location is valid for this primitive.

Show the commit summary for the user to wire into the commit message or PR description.

8. Test

Offer the audit:

"Run /build:check-github-workflow <path> to audit the scaffolded workflow against actionlint, zizmor, yamllint, shellcheck on extracted run: content, plus the seven judgment dimensions?"

The audit is the canonical follow-on; running it once after scaffold catches anything the Safety Check missed and gives a clean baseline.

Anti-Pattern Guards

1. Scaffolding pull_request_target with PR checkout. Unconditional refuse. There is no safe form of this combination.
2. Scaffolding with @main / @master / @v*.*. Unconditional refuse. Ask for a SHA.
3. Missing top-level permissions:. Default GITHUB_TOKEN is too broad. Every scaffolded workflow has contents: read at minimum at the top level.
4. Missing timeout-minutes: on any job. Default is 360 minutes; every job gets an explicit timeout.
5. User-controlled expressions in run: bodies. Route through env: without exception.
6. cancel-in-progress: true on deploy. Scaffold rejects this combination; the deploy concurrency group omits the cancel flag.
7. Empty REQUIRED_CMDS-equivalent. Whatever the Intake collected, the scaffold uses it — don't scaffold placeholder steps the user didn't ask for (setup-python when the Intake said Node, etc.).

Key Instructions

• Refuse cleanly on any of the six Scope Gate signals. These are hard refuses, not "scaffold-and-warn" cases.
• Save location is always under .github/workflows/. No other path is valid.
• SHA-pin universally, including first-party. First-party tag-pinning is an exception requiring an inline comment and Dependabot coverage.
• Offer to fetch release SHAs via gh api repos/<owner>/<repo>/git/refs/tags/<tag> when the user provides a tag instead of a SHA — with user approval before running gh.
• step-security/harden-runner is the first step of every job — no exceptions; this is the post-tj-actions runtime defense.
• Every multi-line bash run: block starts with set -euo pipefail.
• Write files to disk only after the Review Gate passes.
• Won't scaffold pull_request_target + PR checkout — unconditional refuse.
• Won't scaffold mutable refs (@main, @master, @v*.*) — unconditional refuse.

Handoff

Chainable to: /build:check-github-workflow (audit the scaffolded workflow against actionlint, zizmor, yamllint, shellcheck, and the seven judgment dimensions); /build:build-bash-script if a run: block grew past ~20 lines and wants to become a checked-in script under .github/scripts/.