/github-actions

name: github-actions
description: Design, review, secure, and debug GitHub Actions workflows — reusable workflows, OIDC federation, SHA pinning, token scoping, promotion orchestration, and CI failure diagnosis.
argument-hint: "[design|security|review|debug] [workflow file path or description]"
title: "GitHub Actions Command"
sidebar_label: "github-actions"
custom_edit_url: null

GitHub Actions Command

Structured guidance for designing, hardening, reviewing, and debugging GitHub Actions workflows.

Activation

/platform-skills:github-actions design    # reusable workflow or job graph design
/platform-skills:github-actions security  # OIDC, SHA pinning, token scoping, secrets hygiene
/platform-skills:github-actions review    # production-readiness checklist for an existing workflow
/platform-skills:github-actions debug     # diagnose a failing workflow or job

---

Interactive Wizard (fires when no mode is provided)

When invoked with no arguments, ask before proceeding:

**Q1 — Mode?**

What do you need?
  1. design    — reusable workflow, job graph, promotion pipeline
  2. security  — OIDC federation, SHA pinning, token scoping, secret hygiene
  3. review    — production-readiness checklist for an existing workflow file
  4. debug     — job failure, permission error, OIDC rejection, missing context

Enter 1–4 or mode name:

**Q2 — Context** (after mode selected):

• **design**: `Describe what the workflow should do — validate, build, promote, deploy?`
• **security**: `Paste the workflow file or describe the auth pattern you are using.`
• **review**: `Paste the workflow file or provide the path.`
• **debug**: `Paste the error output or describe the failure symptom.`

---

Mode: design

**Triggers:** design, build workflow, create pipeline, reusable workflow, job graph, promote, deploy flow

Read `references/github-actions.md` before responding.

Step 1 — Classify the workflow type

| Type | When to use | |---|---| | Reusable workflow (`workflow_call`) | Same job sequence needed across multiple repos or environments | | Composite action | Same step sequence needed within job graphs — use `/platform-skills:composite-actions` | | Standard workflow | One-off or repo-specific, not shared |

Step 2 — Apply the canonical job pattern

Every workflow should follow this job order:

validate → build → [test] → promote → [deploy]

• `validate`: lint, format, policy gates, unit checks — fast, no credentials
• `build`: image or artifact packaging — OIDC to registry
• `promote`: update version pin or overlay in Git — triggers GitOps reconciler
• `deploy`: guarded apply only if not using GitOps

Keep jobs small and named by intent. If a job is hard to name, it is doing too much.

Step 3 — Reusable workflow structure

# .github/workflows/validate.yml — called by other workflows
on:
  workflow_call:
    inputs:
      environment:
        required: true
        type: string
        description: "Target environment (dev | staging | prod)"
    secrets:
      token:
        required: true

jobs:
  validate:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
        with:
          token: ${{ secrets.token }}

Step 4 — Promotion orchestration

Prefer updating Git over imperative deploys:

# promote job — updates the version pin in the GitOps repo
promote:
  needs: build
  runs-on: ubuntu-latest
  permissions:
    contents: write
  steps:
    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
    - name: Update image tag
      env:
        NEW_TAG: ${{ needs.build.outputs.image_tag }}
      run: |
        sed -i "s|image:.*|image: ghcr.io/org/app:${NEW_TAG}|" \
          deploy/overlays/${{ inputs.environment }}/kustomization.yaml
        git config user.email "ci@org.com"
        git config user.name "CI"
        git commit -am "chore: promote app to ${NEW_TAG} in ${{ inputs.environment }}"
        git push

**Handoffs:**

• Extracting repeated steps → `/platform-skills:composite-actions`
• Terraform plan/apply in the workflow → `/platform-skills:terraform`
• GitOps reconciler that picks up the promotion commit → `/platform-skills:gitops`

---

Mode: security

**Triggers:** OIDC, pin, SHA, token, permissions, secrets, secure, harden, federation

Read `references/github-actions.md` before responding.

OIDC federation — AWS

permissions:
  id-token: write    # required for OIDC token request
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@254c19bd240aabef8777f48595e9d2d7b972184b  # v6.2.1
    with:
      role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
      aws-region: eu-north-1

IAM trust policy (scope to repo and branch):

{
  "Condition": {
    "StringLike": {
      "token.actions.githubusercontent.com:sub": "repo:org/repo:ref:refs/heads/main"
    }
  }
}

OIDC federation — Azure

permissions:
  id-token: write
  contents: read

steps:
  - uses: azure/login@532459ea530d8321f2fb9bb10d1e0bcf23869a43  # v3.0.0
    with:
      client-id: ${{ secrets.AZURE_CLIENT_ID }}
      tenant-id: ${{ secrets.AZURE_TENANT_ID }}
      subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

SHA pinning checklist

# Resolve a tag to its current commit SHA
gh api repos/{owner}/{repo}/git/refs/tags/{tag} \
  --jq '.object.sha'

# For actions that use a commit SHA directly (not a tag ref):
gh api repos/{owner}/{repo}/commits/{tag} --jq '.sha'

Add the version as a comment so reviewers can audit without resolving the SHA manually:

uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0

Token scoping — minimum permissions per job

| Job type | Permissions needed | |---|---| | Read-only checkout | `contents: read` | | Push a commit | `contents: write` | | Create or comment on PR | `pu