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:

```yaml
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

ci-workflows

CI Workflow Standards

Version: 2025.1

Required Workflows

1. Container Build Workflow