ci-workflows

CI Workflow Standards

When to Use This Skill

Version: 2025.1

Standard GitHub Actions workflows for CI/CD automation.

Display name convention

Every workflow's name: follows <Domain>: <Action> [<target>] so the GitHub Actions sidebar groups related workflows alphabetically. Quote the value because YAML treats : inside an unquoted scalar as a key separator. See .claude/rules/workflow-naming.md for the canonical rule, the active domain list, and the cross-workflow rename procedure. Mirror the pattern in any workflow you scaffold here.

Required Workflows

1. Container Build Workflow

File: .github/workflows/container-build.yml

Multi-platform container build with GHCR publishing:

name: "Container: Build"

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  release:
    types: [published]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v6

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Log in to Container Registry
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
          build-args: |
            SENTRY_AUTH_TOKEN=${{ secrets.SENTRY_AUTH_TOKEN }}

Key features:

• Multi-platform builds (amd64, arm64)
• GitHub Container Registry (GHCR)
• Semantic version tagging
• Build caching with GitHub Actions cache
• Sentry integration for source maps

2. Release Please Workflow

File: .github/workflows/release-please.yml

See configure-release-please (its REFERENCE.md carries the standard workflow, token, and config templates) for details.

3. ArgoCD Auto-merge Workflow (Optional)

File: .github/workflows/argocd-automerge.yml

Auto-merge PRs from ArgoCD Image Updater branches:

name: "Image Updater: Auto-merge"

on:
  push:
    branches:
      - 'image-updater-**'

permissions:
  contents: write
  pull-requests: write

jobs:
  create-and-merge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Create Pull Request
        id: create-pr
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          PR_URL=$(gh pr create \
            --base main \
            --head "${{ github.ref_name }}" \
            --title "chore(deps): update container image" \
            --body "Automated image update by argocd-image-updater.

          Branch: \`${{ github.ref_name }}\`" \
            2>&1) || true

          if echo "$PR_URL" | grep -q "already exists"; then
            PR_URL=$(gh pr view "${{ github.ref_name }}" --json url -q .url)
          fi

          echo "pr_url=$PR_URL" >> "$GITHUB_OUTPUT"

      - name: Approve PR
        env:
          GH_TOKEN: ${{ secrets.AUTO_MERGE_PAT || secrets.GITHUB_TOKEN }}
        run: gh pr review --approve "${{ github.ref_name }}"
        continue-on-error: true

      - name: Enable auto-merge
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh pr merge --auto --squash "${{ github.ref_name }}"

Key features:

• Triggers on image-updater-** branches from ArgoCD Image Updater
• Creates PR automatically if not exists
• Self-approval with optional PAT (for bypassing GitHub restrictions)
• Squash merge with auto-merge enabled

Prerequisites:

• Enable auto-merge in repository settings
• Optional: AUTO_MERGE_PAT secret for self-approval

4. Test Workflow (Recommended)

File: .github/workflows/test.yml

name: "Test: Suite"

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: '22'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run type check
        run: npm run typecheck

      - name: Run tests
        run: npm run test:coverage

      - name: Upload coverage
        uses: codecov/codecov-action@v6
        with:
          files: ./coverage/lcov.info

5. Claude Auto-Fix Workflow (Optional)

File: .github/workflows/claude-auto-fix.yml

Automated CI failure analysis and remediation using Claude Code Action:

name: "Auto-fix: CI failures"

on:
  workflow_run:
    # Customize: list the CI workflow display names to monitor.
    # The strings here must match the target workflows' `name:` values exactly.
    workflows: ["Test: Suite"]
    types: [completed]
  workflow_dispatch:
    inputs:
      run_id:
        description: "Failed workflow run ID to analyze"
        required: true
        type: string

concurrency:
  group: auto-fix-${{ github.event.workflow_run.head_branch || github.ref_name }}
  cancel-in-progress: false

Key features:

• Triggers on workflow_run completion for monitored workflows
• Gathers failure logs and context automatically
• Deduplication: caps open auto-fix PRs at 3
• Loop prevention: skips commits starting with fix(auto):
• Auto-fixable failures get a fix PR; complex failures get a GitHub issue
• Uses anthropics/claude-code-action@v1 with scoped tool permissions

Prerequisites:

• CLAUDE_CODE_OAUTH_TOKEN secret configured in repository settings
• At least one CI workflow to monitor (customize workflows: list)

For the full template, see the Claude Auto-Fix Workflow Template in configure-workflows.

Workflow Standards

Action Versions

Permissions

Minimal permissions required:

permissions:
  contents: read      # Default for most jobs
  packages: write     # For container push to GHCR
  pull-requests: write  # For release-please PR creation

Triggers

Standard trigger patterns:

# Build on push and PR to main
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

# Also build on release
on:
  release:
    types: [published]

Build Caching

Use GitHub Actions cache for Docker layers:

cache-from: type=gha
cache-to: type=gha,mode=max

Multi-Platform Builds

Build for both amd64 and arm64:

platforms: linux/amd64,linux/arm64

Compliance Requirements

Required Workflows

Required Elements

Status Levels

Secrets Required

Troubleshooting

Build Failing

• Check Dockerfile syntax
• Verify build args are passed correctly
• Check cache invalidation issues

Multi-Platform Issues

• Ensure Dockerfile is platform-agnostic
• Use official multi-arch base images
• Avoid architecture-specific binaries

Cache Not Working

• Verify cache-from and cache-to are set
• Check GitHub Actions cache limits (10GB)
• Consider registry-based caching for large images