CI Workflow Standards

Version: 2025.1

Standard GitHub Actions workflows for CI/CD automation.

Required Workflows

1. Container Build Workflow

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

Multi-platform container build with GHCR publishing:

name: Build Container

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@v4

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

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

  - name: Extract metadata
    id: meta
    uses: docker/metadata-action@v5
    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@v6
    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 release-please-standards skill for details.

3. ArgoCD Auto-merge Workflow (Optional)

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

Auto-merge PRs from ArgoCD Image Updater branches:

name: Auto-merge ArgoCD Image Updater branches

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

permissions: contents: write pull-requests: write

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

  - 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: Tests

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

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

  - name: Setup Node.js
    uses: actions/setup-node@v4
    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@v4
    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: Claude Auto-fix CI Failures

on: workflow_run: # Customize: list the CI workflow names to monitor workflows: ["CI"] 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

Action Version Purpose

actions/checkout v4 Repository checkout

docker/setup-buildx-action v3 Multi-platform builds

docker/login-action v3 Registry authentication

docker/metadata-action v5 Image tagging

docker/build-push-action v6 Container build/push

actions/setup-node v4 Node.js setup

googleapis/release-please-action v4 Release automation

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

Workflow Purpose Required

container-build Container builds Yes (if Dockerfile)

release-please Automated releases Yes

test Testing and linting Recommended

argocd-automerge Auto-merge image updates Optional (if using ArgoCD Image Updater)

claude-auto-fix Automated CI failure remediation Optional

Required Elements

Element Requirement

checkout action v4

build-push action v6

Multi-platform amd64 + arm64

Caching GHA cache enabled

Permissions Explicit and minimal

Status Levels

Status Condition

PASS All required workflows present with compliant config

WARN Workflows present but using older action versions

FAIL Missing required workflows

SKIP Not applicable (no Dockerfile = no container-build)

Secrets Required

Secret Purpose Required

GITHUB_TOKEN Container registry auth Auto-provided

SENTRY_AUTH_TOKEN Source map upload If using Sentry

MY_RELEASE_PLEASE_TOKEN Release PR creation For release-please

CLAUDE_CODE_OAUTH_TOKEN Claude Code Action auth For claude-auto-fix

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