GitHub Actions CI/CD Guide

Project Context

Current workflows:

• installer-ci.yml: Build → test → E2E test (matrix: ubuntu, debian, fedora, centos containers, macOS)
• release.yml: GoReleaser on version tags

Core Workflow Template

name: CI

on:
  pull_request:
    paths:
      - "component/**"
      - ".github/workflows/ci.yml"
  push:
    branches: [main]
    paths:
      - "component/**"

concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
  cancel-in-progress: true

permissions: {}

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - run: go build -v ./...

Essential Patterns

Concurrency Control

concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
  cancel-in-progress: true

Permissions

permissions: {}  # Top-level default

jobs:
  build:
    permissions:
      contents: read  # Job-level grants

Caching

- uses: actions/cache@v4
  with:
    path: |
      ~/.cache/go-build
      ~/go/pkg/mod
    key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
    restore-keys: |
      ${{ runner.os }}-go-

Artifacts

# Upload
- uses: actions/upload-artifact@v4
  with:
    name: build-artifacts
    path: dist/
    retention-days: 1
    compression-level: 0
    if-no-files-found: error

# Download
- uses: actions/download-artifact@v4
  with:
    name: build-artifacts
    path: dist/

Matrix Builds

strategy:
  fail-fast: false
  matrix:
    include:
      - os: ubuntu-latest
        platform: ubuntu
      - os: ubuntu-latest
        platform: debian
        container: debian:bookworm
      - os: macos-latest
        platform: macos

runs-on: ${{ matrix.os }}
container: ${{ matrix.container }}

When to Read References

testing-patterns.md - E2E tests, interactive testing with expect, platform-specific binary selection, container testing, test isolation

security.md - Permissions beyond read/write, secret handling, input validation, pull_request vs pull_request_target, token security, script injection prevention

optimization.md - Debugging failing workflows, cache optimization, performance tuning, conditional execution, timeout handling, troubleshooting

Common Actions

# Checkout with full history
- uses: actions/checkout@v4
  with:
    fetch-depth: 0

# Setup Go from go.mod
- uses: actions/setup-go@v5
  with:
    go-version-file: go.mod

# GoReleaser build
- uses: goreleaser/goreleaser-action@v6
  with:
    version: latest
    args: build --clean --snapshot
    workdir: installer

Quick Reference

Triggers: push, pull_request, release, workflow_dispatch, schedule

Runners: ubuntu-latest, macos-latest, macos-13, windows-latest

Contexts: ${{ github.event_name }}, ${{ github.ref }}, ${{ github.head_ref }}, ${{ runner.os }}, ${{ matrix.platform }}