ci-workflows

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. 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

Workflow Standards

Action Versions

| 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

| container-build | Container builds | Yes (if Dockerfile)

| release-please | Automated releases | Yes

| test | Testing and linting | Recommended

Required Elements

| checkout action | v4

| build-push action | v6

| Multi-platform | amd64 + arm64

| Caching | GHA cache enabled

| Permissions | Explicit and minimal

Status Levels

| 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

| 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

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