ci-workflows

created	"2025-12-16T00:00:00.000Z"
modified	"2026-07-05T00:00:00.000Z"
reviewed	"2026-06-01T00:00:00.000Z"
name	ci-workflows
description	GitHub Actions workflow standards. Use when checking CI/CD compliance, referencing canonical workflow shapes, or another skill needs workflow structure guidance.
user-invocable	false
allowed-tools	Bash, Read, Write, Edit, Grep, Glob

CI Workflow Standards

When to Use This Skill

Use this skill when...	Use a sibling skill instead when...
You need the canonical GitHub Actions workflow shapes (container build, test, release)	You want to audit or install workflows end-to-end as an interactive workflow — use configure-workflows
You are checking whether existing .github/workflows/*.yml follows the documented conventions	You want pre-built reusable callers wired up — use configure-reusable-workflows
Another skill needs to cite the standard workflow structure	The user asked you to actually create or repair CI workflows

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

Action	Version	Purpose
actions/checkout	v6	Repository checkout
docker/setup-buildx-action	v4	Multi-platform builds
docker/login-action	v4	Registry authentication
docker/metadata-action	v6	Image tagging
docker/build-push-action	v7	Container build/push
actions/setup-node	v6	Node.js setup
googleapis/release-please-action	v5	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	v6
build-push action	v7
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