GitHub Workflows

GitHub Workflows Documentation

This document provides an overview of all GitHub Actions workflows used in the kure project.

Last Updated: 2026-02-20

Workflow Summary

CI Workflow

File: .github/workflows/ci.yml Name: CI

Triggers

• Push to: main, develop, release/*
• Pull requests to: main, develop
• Schedule: 4am UTC daily (catch external changes)
• Manual dispatch

Concurrency

Uses github.sha to avoid duplicate runs:

• Same commit won’t run CI twice (e.g., PR merge → push to main)
• Different commits run independently

concurrency:
  group: ci-${{ github.sha }}
  cancel-in-progress: false

Job Dependency Graph

┌─────────────────┐
│   lint          │  ← Fast checks: go-version, fmt, tidy, vet, lint
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────────┐
│ test  │ │ security  │  ← Tests + govulncheck (parallel)
└───┬───┘ └───────────┘
    │
    ▼
┌───────────────────┐
│ coverage-check    │  ← 80% threshold enforcement
└─────────┬─────────┘
          │
    ┌─────┴─────┐
    ▼           ▼
┌───────┐  ┌────────────┐
│ build │  │ k8s-compat │  ← Build artifacts + K8s matrix
└───┬───┘  └────────────┘
    │
    ▼
┌─────────────────────┐
│ cross-platform      │  ← Only on main/release branches
└─────────┬───────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│ mirror-to-gitlab (main push only, after all checks)         │
└─────────────────────────────────────────────────────────────┘

PR-only jobs (parallel, no blocking):
┌──────────────┐  ┌─────────────────┐  ┌────────────┐
│ rebase-check │  │ analyze-changes │  │ docs-check │
└──────────────┘  └─────────────────┘  └────────────┘

Jobs Detail

Configuration

• Go Version: 1.24.13
• Golangci-lint Version: v1.64.8
• Coverage Threshold: 80%
• K8s Versions: 0.34, 0.35
• Platforms: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64

Features

• gotestfmt - Nice formatted test output
• Fail fast - Jobs depend on validate, so lint failure stops everything
• Artifact sharing - Coverage uploaded as artifact, reused by coverage-check
• PR comments - Coverage report comment on PRs
• Skip draft PRs - if: github.event.pull_request.draft == false
• Sensitive file check - Warn about potential secrets in code
• Matrix fail-fast: false - K8s and cross-platform continue if one fails

Release Workflow

File: .github/workflows/release.yml Name: Release

Triggers

• Push tags: v* (e.g., v1.0.0, v0.1.0-alpha.0)

Jobs

1. test - Full test run with race detection
2. validate - Strict tag format, changelog, and version progression validation
3. goreleaser - Cross-platform builds using GoReleaser v2
4. deploy-docs - Trigger versioned docs deployment (stable tags only)
5. post-release - Go proxy refresh

Configuration

• Go Version: 1.24.13
• Build Tool: GoReleaser v2
• Platforms: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64, windows/arm64
• Tag Format: ^v[0-9]+\.[0-9]+\.[0-9]+(-alpha\.[0-9]+|-beta\.[0-9]+|-rc\.[0-9]+)?$
• Changelog: Required (must have ## v0.1.0 section)

CI Status Check

Release workflow verifies CI passed before releasing:

check-ci:
  name: Verify CI passed
  steps:
    - name: Check CI status for this commit
      run: |
        # Wait up to 5 minutes for CI to complete
        for i in {1..30}; do
          STATUS=$(gh api repos/.../commits/$COMMIT_SHA/status --jq '.state')
          if [ "$STATUS" = "success" ]; then exit 0; fi
          if [ "$STATUS" = "failure" ]; then exit 1; fi
          sleep 10
        done

Release Management

# Preview release plan locally (dry-run)
make release TYPE=alpha

# Create release via CI:
#   Actions > "Create Release" > type=alpha > Run workflow

Auto-Rebase Workflow

File: .github/workflows/auto-rebase.yml Name: Auto-Rebase

Triggers

• Push to main (runs after every merge to main)

Purpose

Automatically rebases all open PRs targeting main when main is updated. This mirrors the GitLab auto-rebase CI template used in other Wharf repositories.

How It Works

Uses peter-evans/rebase@v4 to:

1. Find all open PRs targeting main
2. Rebase each PR branch onto the latest main
3. Force-push the rebased branch (triggers CI re-run)
4. Skip PRs with conflicts (reports them without failing)

Configuration

• Excluded labels: dependencies (Dependabot manages its own branches)
• Excluded drafts: yes (no point rebasing work-in-progress)
• Fork protection: only runs on go-kure/kure (forks lack the required secret)
• Concurrency: cancel-in-progress: true (newer main state supersedes)

Authentication

Requires AUTO_REBASE_PAT repository secret — a fine-grained PAT with:

• Repository: go-kure/kure only
• Permissions: Contents: Read+Write, Pull requests: Read

A PAT is required because pushes made with GITHUB_TOKEN do not trigger subsequent workflow runs. The PAT ensures CI re-runs on rebased branches.

Deploy Docs Workflow

File: .github/workflows/deploy-docs.yml Name: Deploy Docs

Triggers

• Push to main (paths: site/**, docs/**, pkg/**/*.md, examples/**/*.md, README.md, CHANGELOG.md, DEVELOPMENT.md)
• Manual dispatch with inputs: version_slot, version_label, set_latest

How It Works

1. Runs scripts/gen-versions-toml.sh to generate a versioned Hugo config overlay
2. Builds the Hugo site with --config hugo.toml,versions.toml
3. Deploys the built site to a subdirectory of go-kure.github.io

Trigger Matrix

Concurrency

Per-slot concurrency group (deploy-docs-<slot>) prevents race conditions when deploying different versions simultaneously.

Preservation

During deployment, existing version subdirectories (dev/, v*/), CNAME, and .nojekyll are preserved. Only the target slot is replaced.

Manage Docs Workflow

File: .github/workflows/manage-docs.yml Name: Manage Docs

Triggers

• Manual dispatch only with inputs: action, version_slot

Actions

Common Scenarios

# Roll back latest to an older version:
#   Actions > "Manage Docs" > action=set-latest > version_slot=v0.1

# Remove a yanked version:
#   Actions > "Manage Docs" > action=remove-version > version_slot=v0.2

# Rebuild after theme or script changes:
#   Actions > "Manage Docs" > action=rebuild-version > version_slot=dev

Versioned Documentation

The docs site supports multiple documentation versions at different URL paths.

URL Structure

Version Switcher

The Relearn theme provides a native version dropdown in the sidebar. It is configured via params.versions entries in versions.toml, which gen-versions-toml.sh generates from git tags.

How gen-versions-toml.sh Works

# Generate config overlay for a dev build:
./scripts/gen-versions-toml.sh --version dev

# Generate for a stable release:
./scripts/gen-versions-toml.sh --version v0.1.0 --latest v0.1.0

The script:

1. Reads all stable tags (vX.Y.Z without pre-release suffix) from git
2. Deduplicates to minor level (keeps highest patch per vX.Y)
3. Generates site/versions.toml with [params] section and [[params.versions]] entries
4. Marks the latest version with isLatest = true and root baseURL
5. Always includes a “Development” entry pointing to /dev/

WIP Banner

The development version shows a warning banner linking to the latest stable version (if one exists). Stable versions show no banner.

Test Jobs in CI

Test Targets in Makefile

CI vs Pre-commit

Configuration Standards

Go Version

All workflows use Go 1.24.13 consistently, defined via environment variable:

env:
  GO_VERSION: '1.24.13'

Caching

Most workflows use Go module caching:

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

Branch Patterns

• Release branches: release/* (note: not releases/*)
• Development branches: main, develop

Estimated CI Time

Maintenance Notes

• When adding/modifying workflows: Update this document with changes
• Version updates: Run make sync-go-version to update Go version in all files
• Version check: Run make check-go-version to verify consistency
• Action versions: Keep GitHub Actions up to date (currently using v4-v6)

See Also

• Makefile - Local development commands
• mise.toml - Local tool version management
• gen-versions-toml.sh - Versioned docs config generator