This is a practical build-up guide for creating one large ci.yml that is still readable, maintainable, and tailored to real repositories.

The target outcome:

  • One workflow file handles push, PR open/update, PR close, tags, release publish, manual dispatch, and monthly/nightly schedules.
  • It supports mixed repos: Go, Node, Dart, Flutter, Qt/C++, classic C/Makefile, and Dockerized components.
  • It can run in public mode (broader checks) or private mode (cost-controlled), while keeping default test runners Ubuntu unless cross-OS coverage is explicitly needed.
  • It includes autofix PR creation + cleanup, security checks, artifact fan-out, and release lanes.
  • It accounts for packaging outputs beyond standard app bundles, including source Debian and source RPM pipeline hooks.

The point is not tiny YAML. The point is one intelligent CI/CD platform per repo.

Before the workflow body, add a top-of-file pointer comment so agents and humans know where the generation rules live:

1# Agent rules for generation:
2# https://arran4.com/post/2026/006-Github-CI-and-Deploy/
3# Built using this post as a reference/guide.
4name: CI/CD

Why one file (when multiple files are common)

Multiple files can work, but they drift over time:

  • duplicated setup steps,
  • inconsistent event triggers,
  • fragmented release logic,
  • duplicated policy logic for private/public repos.

A single file gives one policy and one dependency graph. You can still keep complexity sane by:

  1. sectioned jobs,
  2. capability outputs,
  3. profile outputs,
  4. event routing,
  5. reusable local scripts/config files.

Non-negotiable design rules

  1. Event routing first (avoid accidental duplicate work).
  2. Project-type decisions should mostly be install/template-time (human comments + toggles), with lightweight runtime detection as a safety net.
  3. Repo visibility is auto-detected (github.event.repository.private) rather than manually toggled.
  4. Public repos run broader checks by default; private repos are conservative unless manual mode asks for full.
  5. Autofix lanes are language-aware (go fmt/go fix, dart format, flutter format, prettier, etc).
  6. Release lanes are split (GoReleaser, container release, source package release).
  7. Monthly maintenance exists by default.

Step 1: Triggers and modes (copy/paste)

This event model supports normal validation, releases, and cleanup lifecycle.

 1name: CI/CD
 2
 3on:
 4  push:
 5    branches: [main, master]
 6    # semantic version tags + rc/beta snapshots
 7    tags:
 8      - 'v*'
 9      - 'v*.*.*'
10      - 'v*.*.*-rc*'
11      - 'v*.*.*-beta*'
12      - 'test-*'
13  pull_request:
14    types: [opened, synchronize, reopened, ready_for_review, closed]
15    branches: [main, master]
16  release:
17    types: [published]
18  workflow_dispatch:
19    inputs:
20      mode:
21        description: "Pipeline mode"
22        required: true
23        default: "lint-fix"
24        type: choice
25        options:
26          - lint-fix
27          - build
28          - release-major
29          - release-minor
30          - release-patch
31          - release-test
32          - release-rc
33          - release-alpha
34          - monthly-maintenance
35      release_version_override:
36        description: "Optional explicit release version (for example 2.4.0 or 2.4.0-rc.2)"
37        required: false
38        default: ""
39        type: string
40      allow_prs:
41        description: "Allow automation to open pull requests"
42        required: false
43        default: true
44        type: boolean
45  schedule:
46    # preferred heavy monthly run (quota reset strategy)
47    - cron: '17 3 1 * *'
48    # optional nightly lightweight checks
49    - cron: '41 2 * * *'

Why this is better

  • It handles PR close cleanup flows.
  • It supports semantic tags and release candidates.
  • It exposes explicit manual operational modes (lint-fix, build, and explicit release modes (release-major, release-minor, release-patch, release-test, release-rc, release-alpha)).
  • It keeps manual-dispatch states valid by encoding release intent directly into mode values.

Step 1.5: Release mode routing (single-input design)

To avoid invalid manual-dispatch state combinations, keep a single release control surface in mode and one optional release_version_override.

 1  prepare-release-tag:
 2    name: Prepare release tag
 3    needs: [route]
 4    if: ${{ github.event_name == 'workflow_dispatch' && startsWith(inputs.mode, 'release-') }}
 5    runs-on: ubuntu-latest
 6    outputs:
 7      release_tag: ${{ steps.tag.outputs.release_tag }}
 8      next_version: ${{ steps.tag.outputs.next_version }}
 9    steps:
10      - uses: actions/checkout@v4
11        with:
12          fetch-depth: 0
13      - name: Setup git-tag-inc
14        uses: arran4/git-tag-inc-action@v1
15        with:
16          mode: install
17      # Do not also run `go install github.com/arran4/git-tag-inc/...` in this job.
18      # Using both is redundant and has caused avoidable CI drift.
19      - id: tag
20        shell: bash
21        run: |
22          set -euo pipefail
23          git config --global user.name "github-actions[bot]"
24          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
25          MODE="${{ inputs.mode }}"
26          OVERRIDE="${{ inputs.release_version_override }}"
27
28          if [[ -n "$OVERRIDE" ]]; then
29            # Accept "1.2.3" or "v1.2.3" override input.
30            OVERRIDE="${OVERRIDE#v}"
31            next_tag="v$OVERRIDE"
32          else
33            case "$MODE" in
34              release-major) level="major"; suffix="" ;;
35              release-minor) level="minor"; suffix="" ;;
36              release-patch) level="patch"; suffix="" ;;
37              release-test)  level="patch"; suffix="test" ;;
38              release-rc)    level="patch"; suffix="rc" ;;
39              release-alpha) level="patch"; suffix="alpha" ;;
40              *) echo "Unsupported release mode: $MODE"; exit 1 ;;
41            esac
42            if command -v git-tag-inc >/dev/null 2>&1; then
43              # git-tag-inc uses positional commands (patch/major/minor/test/rc...)
44              # and NOT flag forms like -patch.
45              level="${level#-}"
46              args=(-print-version-only "$level")
47              [[ -n "$suffix" ]] && args+=("$suffix")
48              next_tag=$(git-tag-inc "${args[@]}")
49            else
50              # Fallback implementation when git-tag-inc is not available.
51              git fetch --tags --force
52              latest=$(git tag -l 'v*' | sed 's/^v//' | sort -V | tail -n 1)
53              [[ -z "$latest" ]] && latest='0.0.0'
54
55              # Prefer npx semver if available (same pattern used in g2 fixes).
56              if command -v npx >/dev/null 2>&1; then
57                case "$level" in
58                  major) bumped=$(npx --yes semver "$latest" -i major) ;;
59                  minor) bumped=$(npx --yes semver "$latest" -i minor) ;;
60                  *) bumped=$(npx --yes semver "$latest" -i patch) ;;
61                esac
62                next_tag="v${bumped}"
63              else
64                base="${latest%%-*}"
65                IFS='.' read -r maj min pat <<< "$base"
66                case "$level" in
67                  major) maj=$((maj+1)); min=0; pat=0 ;;
68                  minor) min=$((min+1)); pat=0 ;;
69                  *) pat=$((pat+1)) ;;
70                esac
71                next_tag="v${maj}.${min}.${pat}"
72              fi
73
74              if [[ -n "$suffix" ]]; then
75                next_tag="${next_tag}-${suffix}.1"
76              fi
77            fi
78          fi
79
80          # Tagging safety guards to avoid duplicate/invalid release states.
81          [[ "$next_tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([-.][0-9A-Za-z.]+)?$ ]] || {
82            echo "Invalid tag format: $next_tag" >&2
83            exit 1
84          }
85          git fetch --tags --force
86          if git rev-parse "$next_tag" >/dev/null 2>&1; then
87            echo "Tag already exists: $next_tag" >&2
88            echo "Choose a new mode or set release_version_override." >&2
89            exit 1
90          fi
91
92          echo "release_tag=$next_tag" >> "$GITHUB_OUTPUT"
93          clean_tag="${next_tag#v}"; clean_tag="${clean_tag%%-*}"
94          IFS='.' read -r maj min pat <<< "$clean_tag"
95          echo "next_version=${maj:-0}.${min:-0}.$(( ${pat:-0} + 1 ))-SNAPSHOT" >> "$GITHUB_OUTPUT"

With this approach, snapshot/prerelease is inferred from the selected release mode and tag suffix, not from separate toggles. It also fixes common tagging issues by normalizing override input (v prefix optional), validating tag shape, hard-failing on existing tags before publish jobs run, and reminding you to fetch tags before version math. It explicitly installs git-tag-inc via arran4/git-tag-inc-action@v1 (mode: install) and includes fallback bump paths (npx semver, then pure shell semver math) if the binary is not found. Do not double-install with a separate manual go install in the same job. Use git-tag-inc -print-version-only <major|minor|patch> [test|rc|alpha] positional arguments to avoid the recurring argument-format mistake. Never use -patch/-major/-minor as flags; those are invalid. Also configure git user/email in the job before running release tag tooling so CI tag operations do not fail on identity checks.

If your repository keeps a version in source files as well as tags (for example CMakeLists.txt, pubspec.yaml, package.json, or similar), compute the next version from the highest of source version and fetched tag version. That avoids the recurring failure mode where CI bumps from stale source state, reuses an already-published version, and collides on tag creation.

Step 2: Event routing to reduce duplicate runs

You noted a real issue: push + PR can duplicate work. We fix it with routing-first, state-aware if: behavior, but keep an important practical rule: lint/format/vet/test should still appear on PRs so reviewers get direct PR check visibility.

 1concurrency:
 2  # Keep this as a safety net, not the primary dedupe mechanism.
 3  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }}
 4  cancel-in-progress: true
 5
 6permissions:
 7  contents: write
 8  discussions: write
 9  pull-requests: write
10  checks: write
11  packages: write
12  security-events: write
13
14jobs:
15  route:
16    name: Route event
17    runs-on: ubuntu-latest
18    outputs:
19      run_code_checks: ${{ steps.route.outputs.run_code_checks }}
20      run_pr_meta_checks: ${{ steps.route.outputs.run_pr_meta_checks }}
21      run_cleanup: ${{ steps.route.outputs.run_cleanup }}
22      run_release: ${{ steps.route.outputs.run_release }}
23      is_monthly: ${{ steps.route.outputs.is_monthly }}
24      is_nightly: ${{ steps.route.outputs.is_nightly }}
25    steps:
26      - id: route
27        shell: bash
28        run: |
29          set -euo pipefail
30
31          run_code_checks=false
32          run_pr_meta_checks=false
33          run_cleanup=false
34          run_release=false
35          is_monthly=false
36          is_nightly=false
37
38          case "${{ github.event_name }}" in
39            push)
40              run_code_checks=true
41              ;;
42            pull_request)
43              if [[ "${{ github.event.action }}" == "closed" ]]; then
44                run_cleanup=true
45              else
46                run_pr_meta_checks=true
47                # In practice, also run code checks on PRs so lint/fmt/vet/test
48                # show up directly in the PR UI. Use concurrency to collapse churn.
49                run_code_checks=true
50              fi
51              ;;
52            release)
53              run_release=true
54              ;;
55            workflow_dispatch)
56              run_code_checks=true
57              if [[ "${{ inputs.mode }}" == release-* ]]; then
58                run_release=true
59              fi
60              if [[ "${{ inputs.mode }}" == "monthly-maintenance" ]]; then
61                is_monthly=true
62              fi
63              if [[ "${{ inputs.mode }}" == "lint-fix" ]]; then
64                # Manual lint-fix acts as an on-demand nightly-style maintenance pass.
65                is_nightly=true
66              fi
67              ;;
68            schedule)
69              run_code_checks=true
70              if [[ "${{ github.event.schedule }}" == "17 3 1 * *" ]]; then
71                is_monthly=true
72              fi
73              if [[ "${{ github.event.schedule }}" == "41 2 * * *" ]]; then
74                is_nightly=true
75              fi
76              ;;
77          esac
78
79          echo "run_code_checks=$run_code_checks" >> "$GITHUB_OUTPUT"
80          echo "run_pr_meta_checks=$run_pr_meta_checks" >> "$GITHUB_OUTPUT"
81          echo "run_cleanup=$run_cleanup" >> "$GITHUB_OUTPUT"
82          echo "run_release=$run_release" >> "$GITHUB_OUTPUT"
83          echo "is_monthly=$is_monthly" >> "$GITHUB_OUTPUT"
84          echo "is_nightly=$is_nightly" >> "$GITHUB_OUTPUT"

High-confidence manual-dispatch router baseline

If you want a known-good baseline for manual dispatch semantics, use the same three-route-output shape proven in arran4/mlocate_explorer (run_code_checks, run_build, run_release) and then layer project-specific lanes onto it.

 1  route:
 2    name: Event Router
 3    runs-on: ubuntu-latest
 4    outputs:
 5      run_code_checks: ${{ steps.decide.outputs.run_code_checks }}
 6      run_build: ${{ steps.decide.outputs.run_build }}
 7      run_release: ${{ steps.decide.outputs.run_release }}
 8    steps:
 9      - id: decide
10        shell: bash
11        run: |
12          set -euo pipefail
13          if [[ "${{ github.event_name }}" == "pull_request" && "${{ github.event.action }}" == "closed" ]]; then
14            echo "run_code_checks=false" >> "$GITHUB_OUTPUT"
15            echo "run_build=false" >> "$GITHUB_OUTPUT"
16            echo "run_release=false" >> "$GITHUB_OUTPUT"
17            exit 0
18          fi
19
20          echo "run_code_checks=true" >> "$GITHUB_OUTPUT"
21
22          if [[ "${{ github.ref }}" == refs/tags/* || ("${{ github.event_name }}" == "workflow_dispatch" && "${{ inputs.mode }}" != "lint-fix") ]]; then
23            echo "run_build=true" >> "$GITHUB_OUTPUT"
24          else
25            echo "run_build=false" >> "$GITHUB_OUTPUT"
26          fi
27
28          if [[ "${{ github.ref }}" == refs/tags/v* || ("${{ github.event_name }}" == "workflow_dispatch" && startsWith("${{ inputs.mode }}", "release-")) ]]; then
29            echo "run_release=true" >> "$GITHUB_OUTPUT"
30          else
31            echo "run_release=false" >> "$GITHUB_OUTPUT"
32          fi

This gives you predictable manual dispatch behavior: lint-fix runs checks only, build runs build lanes, and release-* runs build + release.

This gives explicit behavior control instead of relying only on cancellation.

Practical rule: keep code checks on both push and pull_request when you want lint/format/vet/test results visible in the PR itself. Let concurrency and event routing reduce churn, rather than hiding the checks from reviewers.

Clarification from a working real-world result (fork-qip style)

A practical setup that matches your intent closely uses these additional rules:

  1. Conditional cancellation for concurrency:
    • cancel in-progress runs on non-main/non-tag refs,
    • avoid cancelling main, master, and tag builds.
  2. Dedicated format job that always runs for Go repos during code-check events:
    • on manual lint-fix, it opens an autofix PR,
    • otherwise it fails with diff output (forcing dev-side formatting).
  3. Separate go-lint, go-test, and go-vet jobs for cleaner diagnostics and release gating.
  4. Release job guarded with !failure() && !cancelled() and needs fan-in.

Copy/paste concurrency pattern from that style:

1concurrency:
2  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
3  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/master' && !startsWith(github.ref, 'refs/tags/') }}

This is stricter and often better than blanket cancel-in-progress: true in busy repos.

Step 3: Project profile decisions (config-time first, minimal runtime checks)

You are right that most tailoring should be done when installing the workflow. Do both:

  • template comments/toggles for expected project types,
  • runtime detection as guard rails.
 1  discover:
 2    name: Discover capabilities and cost profile
 3    needs: route
 4    runs-on: ubuntu-latest
 5    outputs:
 6      profile: ${{ steps.profile.outputs.profile }}
 7      has_go: ${{ steps.detect.outputs.has_go }}
 8      has_node: ${{ steps.detect.outputs.has_node }}
 9      has_dart: ${{ steps.detect.outputs.has_dart }}
10      has_flutter: ${{ steps.detect.outputs.has_flutter }}
11      has_qt_cpp: ${{ steps.detect.outputs.has_qt_cpp }}
12      has_make_c: ${{ steps.detect.outputs.has_make_c }}
13      has_docker: ${{ steps.detect.outputs.has_docker }}
14      has_goreleaser: ${{ steps.detect.outputs.has_goreleaser }}
15      has_dart_or_flutter_tests: ${{ steps.detect.outputs.has_dart_or_flutter_tests }}
16      has_packaging: ${{ steps.detect.outputs.has_packaging }}
17    steps:
18      - uses: actions/checkout@v4
19
20      # Template-time toggles (set these once for the repo; avoid broad auto-detection)
21      # EXPECT_GO=true
22      # EXPECT_NODE=false
23      # EXPECT_DART=false
24      # EXPECT_FLUTTER=false
25      # EXPECT_QT_CPP=false
26      # EXPECT_MAKE_C=false
27      # EXPECT_DOCKER=false
28      # EXPECT_GORELEASER=true
29
30      - id: detect
31        shell: bash
32        run: |
33          set -euo pipefail
34          # Keep this minimal: most language choices should be decided at workflow install/customization time.
35          # Runtime checks stay for optional tests and packaging folders.
36
37          echo "has_go=${EXPECT_GO:-false}" >> "$GITHUB_OUTPUT"
38          echo "has_node=${EXPECT_NODE:-false}" >> "$GITHUB_OUTPUT"
39          echo "has_dart=${EXPECT_DART:-false}" >> "$GITHUB_OUTPUT"
40          echo "has_flutter=${EXPECT_FLUTTER:-false}" >> "$GITHUB_OUTPUT"
41          echo "has_qt_cpp=${EXPECT_QT_CPP:-false}" >> "$GITHUB_OUTPUT"
42          echo "has_make_c=${EXPECT_MAKE_C:-false}" >> "$GITHUB_OUTPUT"
43          echo "has_docker=${EXPECT_DOCKER:-false}" >> "$GITHUB_OUTPUT"
44          echo "has_goreleaser=${EXPECT_GORELEASER:-false}" >> "$GITHUB_OUTPUT"
45
46          ([[ -d test ]] || [[ -d tests ]] || [[ -f pubspec.yaml ]]) && echo "has_dart_or_flutter_tests=true" >> "$GITHUB_OUTPUT" || echo "has_dart_or_flutter_tests=false" >> "$GITHUB_OUTPUT"
47          ([[ -d packaging ]] || [[ -d pkg ]] || [[ -f debian/control ]]) && echo "has_packaging=true" >> "$GITHUB_OUTPUT" || echo "has_packaging=false" >> "$GITHUB_OUTPUT"          
48
49      - id: profile
50        shell: bash
51        run: |
52          set -euo pipefail
53          # repo visibility is authoritative
54          if [[ "${{ github.event.repository.private }}" == "true" ]]; then
55            echo "profile=private" >> "$GITHUB_OUTPUT"
56          else
57            echo "profile=public" >> "$GITHUB_OUTPUT"
58          fi

Why this is not just cost control

Conditional outputs are also for:

  • correctness (only run valid lanes),
  • readability (clear if graph),
  • reliability (fewer false failures in unrelated stacks),
  • maintainability (easy to extend per language).

Step 4: Lint config and tool config files you should keep in repo

A single CI file works best when lint/build settings are stored in repo config files, not inline shell flags.

Recommended baseline:

  • Go: .golangci.yml
  • Node: .eslintrc.*, .prettierrc*
  • Dart/Flutter: analysis_options.yaml
  • C/C++: .clang-format, cppcheck config or suppressions file
  • Gitleaks: .gitleaks.toml
  • GoReleaser: .goreleaser.yml
  • Packaging: packaging/ tree (debian/, .spec, templates)

Example .gitleaks.toml starter:

1title = "repo gitleaks config"
2
3[allowlist]
4description = "global allowlist"
5paths = [
6  '''^docs/''',
7  '''^testdata/'''
8]

Example analysis_options.yaml starter:

 1include: package:flutter_lints/flutter.yaml
 2
 3analyzer:
 4  language:
 5    strict-casts: true
 6
 7linter:
 8  rules:
 9    - avoid_print
10    - prefer_single_quotes

Additional copy/paste config starters:

.golangci.yml

 1run:
 2  timeout: 5m
 3
 4linters:
 5  enable:
 6    - govet
 7    - staticcheck
 8    - errcheck
 9    - ineffassign
10    - revive

.prettierrc.json

1{
2  "semi": false,
3  "singleQuote": true,
4  "printWidth": 100
5}

.clang-format

1BasedOnStyle: LLVM
2IndentWidth: 2
3ColumnLimit: 100

packaging/rpm/app.spec (source rpm compatible starter)

 1Name:           app
 2Version:        %{?version}%{!?version:0.0.0}
 3Release:        1%{?dist}
 4Summary:        App summary
 5License:        MIT
 6Source0:        %{name}-%{version}.tar.gz
 7
 8%description
 9App description.
10
11%prep
12%autosetup
13
14%build
15# build steps here
16
17%install
18mkdir -p %{buildroot}/usr/bin
19
20%files
21/usr/bin/*
22
23%changelog
24* Thu Mar 04 2026 CI Bot <ci@example.com> - %{version}-1
25- Automated source build

Step 5: Security jobs (automatic profile behavior)

 1  gitleaks:
 2    name: Secret scan
 3    needs: [route, discover]
 4    if: ${{ needs.route.outputs.run_cleanup != 'true' && (needs.route.outputs.is_nightly == 'true' || needs.route.outputs.is_monthly == 'true') }}
 5    runs-on: ubuntu-latest
 6    steps:
 7      - uses: actions/checkout@v4
 8        with:
 9          fetch-depth: 0
10      - uses: gitleaks/gitleaks-action@v2
11        env:
12          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
13
14  dependency-review:
15    name: Dependency review (public/full)
16    needs: [route, discover]
17    if: ${{ needs.discover.outputs.profile == 'public' && github.event_name == 'pull_request' && github.event.action != 'closed' }}
18    runs-on: ubuntu-latest
19    steps:
20      - uses: actions/dependency-review-action@v4

Public repos can afford broader checks by default. Private repos keep monthly/full-mode heavy scans.

Leak check policy: run secret/leak scans as part of nightly/monthly maintenance only (including manual lint-fix maintenance dispatch).

Step 5.5: Java/Maven lane (from kagura-style repos)

If a repo has pom.xml, add this lane. It is useful for polyglot repos where Java packaging coexists with Go/Node/others.

 1  java-build-test:
 2    name: Java build/test
 3    needs: [route, discover]
 4    if: ${{ needs.route.outputs.run_code_checks == 'true' && hashFiles('pom.xml') != '' }}
 5    runs-on: ubuntu-latest
 6    steps:
 7      - uses: actions/checkout@v4
 8      - uses: actions/setup-java@v4
 9        with:
10          java-version: '11'
11          distribution: temurin
12          cache: maven
13      - run: mvn spotless:check
14      - run: mvn test -DskipITs=false

This mirrors the style in your referenced workflow and can be chained into release fan-in if Java artifacts are part of your release.

Step 5.6: Hugo Pages integration pattern

If the repository includes a Hugo docs/site directory (example: site/mydocs), add a Pages lane that builds and deploys docs on main/master, tag releases, and manual dispatch.

Key ideas from the referenced workflow:

  • route-level run_pages output (separate from code-check/release output),
  • discovery output has_hugo for conditional execution,
  • workflow permissions include pages: write and id-token: write,
  • split build and deploy jobs (hugo-build -> hugo-deploy),
  • deployment concurrency uses the pages group.

Route/discovery additions (copy/paste)

 1permissions:
 2  contents: write
 3  pull-requests: write
 4  checks: write
 5  packages: write
 6  security-events: write
 7  pages: write
 8  id-token: write
 9
10jobs:
11  route:
12    outputs:
13      run_pages: ${{ steps.route.outputs.run_pages }}
14    steps:
15      - id: route
16        run: |
17          run_pages=false
18          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
19            run_pages=true
20          elif [[ "${{ github.ref }}" == refs/tags/* || "${{ github.ref }}" == "refs/heads/main" || "${{ github.ref }}" == "refs/heads/master" ]]; then
21            run_pages=true
22          fi
23          echo "run_pages=$run_pages" >> "$GITHUB_OUTPUT"          
24
25  discover:
26    outputs:
27      has_hugo: ${{ steps.detect.outputs.has_hugo }}
28    steps:
29      - id: detect
30        run: |
31          [[ -d site/mydocs ]] && echo "has_hugo=true" >> "$GITHUB_OUTPUT" || echo "has_hugo=false" >> "$GITHUB_OUTPUT"

Build + deploy jobs (copy/paste)

 1  hugo-build:
 2    name: Build Hugo site
 3    needs: [route, discover]
 4    if: ${{ needs.discover.outputs.has_hugo == 'true' && needs.route.outputs.run_pages == 'true' }}
 5    runs-on: ubuntu-latest
 6    env:
 7      HUGO_VERSION: 0.123.7
 8    steps:
 9      - name: Install Hugo CLI
10        run: |
11          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
12          sudo dpkg -i ${{ runner.temp }}/hugo.deb          
13      - name: Install Dart Sass
14        run: sudo snap install dart-sass
15      - uses: actions/checkout@v4
16        with:
17          submodules: recursive
18      - id: pages
19        uses: actions/configure-pages@v5
20      - name: Install Node dependencies
21        working-directory: ./site/mydocs
22        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
23      - name: Build with Hugo
24        working-directory: ./site/mydocs
25        env:
26          HUGO_ENVIRONMENT: production
27          HUGO_ENV: production
28        run: |
29          hugo --minify --baseURL "${{ steps.pages.outputs.base_url }}/"          
30      - uses: actions/upload-pages-artifact@v3
31        with:
32          path: ./site/mydocs/public
33
34  hugo-deploy:
35    name: Deploy to GitHub Pages
36    needs: [route, discover, hugo-build]
37    if: ${{ needs.discover.outputs.has_hugo == 'true' && needs.route.outputs.run_pages == 'true' }}
38    runs-on: ubuntu-latest
39    concurrency:
40      group: pages
41      cancel-in-progress: false
42    environment:
43      name: github-pages
44      url: ${{ steps.deployment.outputs.page_url }}
45    steps:
46      - name: Deploy to GitHub Pages
47        id: deployment
48        uses: actions/deploy-pages@v4

This keeps docs/site deployment first-class without mixing it into language build jobs.

Step 6: Go lane (tests, lint, vet, release prep)

Use setup-go built-in caching instead of manual actions/cache.

 1  # Requested baseline snippet (modern versions)
 2  golangci:
 3    name: lint
 4    needs: [route, discover]
 5    if: ${{ needs.discover.outputs.has_go == 'true' && needs.route.outputs.run_code_checks == 'true' }}
 6    runs-on: ubuntu-latest
 7    steps:
 8      - uses: actions/checkout@v5
 9      - uses: actions/setup-go@v6
10        with:
11          go-version-file: go.mod
12      - name: golangci-lint
13        uses: golangci/golangci-lint-action@v9
14        with:
15          version: latest
16
17  go-test:
18    name: Go lint/test (${{ matrix.os }})
19    needs: [route, discover, golangci]
20    if: ${{ needs.discover.outputs.has_go == 'true' && needs.route.outputs.run_code_checks == 'true' }}
21    runs-on: ${{ matrix.os }}
22    strategy:
23      fail-fast: false
24      matrix:
25        # Cost-aware default: Ubuntu only.
26        # Add windows-latest/macos-latest only for true platform-specific behavior.
27        os: [ubuntu-latest]
28    steps:
29      - uses: actions/checkout@v4
30      - uses: actions/setup-go@v6
31        with:
32          go-version-file: go.mod
33          cache: true
34      - name: Test
35        run: go test ./... -v
36
37  go-vet:
38    name: Go vet
39    needs: [route, discover]
40    if: ${{ needs.discover.outputs.has_go == 'true' && needs.route.outputs.run_code_checks == 'true' && needs.discover.outputs.profile == 'public' }}
41    runs-on: ubuntu-latest
42    steps:
43      - uses: actions/checkout@v4
44      - uses: actions/setup-go@v6
45        with:
46          go-version-file: go.mod
47          cache: true
48      - run: go vet ./...
49
50  go-fmt-pr:
51    name: go fmt -> PR (manual dispatch)
52    needs: [route, discover]
53    if: ${{ needs.discover.outputs.has_go == 'true' && github.event_name == 'workflow_dispatch' && inputs.mode == 'lint-fix' && inputs.allow_prs == true }}
54    runs-on: ubuntu-latest
55    steps:
56      - uses: actions/checkout@v4
57      - uses: actions/setup-go@v6
58        with:
59          go-version-file: go.mod
60      - name: Run go fmt
61        run: go fmt ./...
62      - name: Create PR if go fmt changed files
63        env:
64          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
65        run: |
66          set -euo pipefail
67          git diff --quiet && { echo "No fmt changes"; exit 0; }
68          git config user.name "github-actions[bot]"
69          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
70          BRANCH="ci/gofmt/${{ github.run_id }}"
71          git checkout -b "$BRANCH"
72          git add -A
73          git commit -m "ci: go fmt"
74          git push origin "$BRANCH"
75          gh pr create --title "ci: go fmt" --body "Automated go fmt from manual dispatch." --base main --head "$BRANCH" --label "ci-autofix"

This separates lint, test, and vet while keeping a dedicated manual-dispatch go fmt -> PR path.

Recommended behavior (from your working result):

  • Keep format as a required job in normal CI.
  • If mode == lint-fix, auto-open PR with fixes.
  • Otherwise fail the job and print diff so formatting is corrected in source branches.

Optional cross-OS lane (only when it really matters):

 1  go-cross-os-smoke:
 2    name: Go cross-OS smoke (${{ matrix.os }})
 3    needs: [route, discover, golangci]
 4    if: ${{ needs.discover.outputs.has_go == 'true' && needs.route.outputs.run_code_checks == 'true' && (github.event_name == 'workflow_dispatch' && inputs.mode == 'build') }}
 5    runs-on: ${{ matrix.os }}
 6    strategy:
 7      fail-fast: false
 8      matrix:
 9        os: [ubuntu-latest, windows-latest, macos-latest]
10    steps:
11      - uses: actions/checkout@v4
12      - uses: actions/setup-go@v6
13        with:
14          go-version-file: go.mod
15      - run: go build ./...

Step 7: Node lane (tests, lint, source package + versioning integration)

 1  node-lint-test:
 2    name: Node lint/test
 3    needs: [route, discover]
 4    if: ${{ needs.discover.outputs.has_node == 'true' && needs.route.outputs.run_code_checks == 'true' }}
 5    runs-on: ubuntu-latest
 6    steps:
 7      - uses: actions/checkout@v4
 8      - uses: actions/setup-node@v4
 9        with:
10          node-version: '22'
11          cache: 'npm'
12      - run: npm ci
13      - run: npm run lint --if-present
14      - run: npm test --if-present
15      - name: Build source npm package
16        run: npm pack --json > npm-pack-result.json
17
18      - uses: actions/upload-artifact@v4
19        with:
20          name: npm-source-package
21          retention-days: 1
22          path: |
23            *.tgz
24            npm-pack-result.json

Use this baseline with Step 7.5 below as the release/versioning extension for npm publish.

Step 7.5: Node/TS version automation (integrated publish path)

For npm packages, the tsobjectutils workflow has strong production ideas worth reusing:

  • manual bump levels (patch|minor|major|prerelease),
  • optional prerelease creation (-next),
  • compute whether publish is allowed (-next can skip public publish),
  • idempotent tag/release creation (actions/github-script checks if they already exist),
  • publish with correct npm dist-tag (latest vs next),
  • create a PR for the next development iteration version.

Copy/paste control snippet:

 1on:
 2  workflow_dispatch:
 3    inputs:
 4      level:
 5        description: Version Bump Level
 6        required: true
 7        default: patch
 8        type: choice
 9        options: [patch, minor, major, prerelease]
10      create_prerelease:
11        description: Create as prerelease (e.g. -next.0)
12        required: false
13        default: false
14        type: boolean
15
16jobs:
17  version-and-release:
18    runs-on: ubuntu-latest
19    steps:
20      - uses: actions/checkout@v4
21        with:
22          fetch-depth: 0
23      - uses: actions/setup-node@v4
24        with:
25          node-version: '18'
26
27      - name: Manual Version Bump
28        if: github.event_name == 'workflow_dispatch'
29        run: |
30          LEVEL="${{ inputs.level }}"
31          CREATE_PRE="${{ inputs.create_prerelease }}"
32          if [ "$LEVEL" = "prerelease" ]; then
33            npm version prerelease --preid=next --no-git-tag-version
34          elif [ "$CREATE_PRE" = "true" ]; then
35            npm version pre$LEVEL --preid=next --no-git-tag-version
36          else
37            npm version $LEVEL --no-git-tag-version
38          fi          
39
40      - name: Determine npm tag and prerelease state
41        id: versions
42        run: |
43          CURRENT_VERSION=$(node -p "require('./package.json').version")
44          if [[ "$CURRENT_VERSION" == *-* ]]; then
45            echo "npm_tag=next" >> "$GITHUB_OUTPUT"
46            echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
47          else
48            echo "npm_tag=latest" >> "$GITHUB_OUTPUT"
49            echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
50          fi

This pattern reduces accidental duplicate tags/releases and gives predictable npm channel behavior.

Step 8: Dart + Flutter lanes (including libraries)

You asked to include Dart libs and Flutter libs specifically, with analysis.

 1  dart-analyze-test:
 2    name: Dart analyze/test
 3    needs: [route, discover]
 4    if: ${{ needs.discover.outputs.has_dart == 'true' && needs.route.outputs.run_code_checks == 'true' }}
 5    runs-on: ubuntu-latest
 6    steps:
 7      - uses: actions/checkout@v4
 8      - uses: dart-lang/setup-dart@v1
 9      - run: dart --version
10      - run: dart pub get
11      - run: dart format --set-exit-if-changed .
12      - run: dart analyze
13      - run: dart test
14
15  flutter-analyze-test:
16    name: Flutter analyze/test (fast path)
17    needs: [route, discover]
18    if: ${{ needs.discover.outputs.has_flutter == 'true' && needs.route.outputs.run_code_checks == 'true' }}
19    runs-on: ubuntu-latest
20    steps:
21      - uses: actions/checkout@v4
22      - uses: subosito/flutter-action@v2
23        with:
24          channel: stable
25      - run: flutter --version
26      - run: flutter pub get
27      - run: dart format --set-exit-if-changed .
28      - run: flutter analyze
29      - run: flutter test
30
31  flutter-format-pr:
32    name: Flutter format -> PR (manual lint-fix)
33    needs: [route, discover]
34    if: ${{ needs.discover.outputs.has_flutter == 'true' && github.event_name == 'workflow_dispatch' && inputs.mode == 'lint-fix' }}
35    runs-on: ubuntu-latest
36    steps:
37      - uses: actions/checkout@v4
38      - uses: subosito/flutter-action@v2
39        with:
40          channel: stable
41      - run: flutter pub get
42      - id: format
43        run: |
44          dart format .
45          if [[ -n $(git status --porcelain -- '*.dart') ]]; then
46            echo "changes=true" >> "$GITHUB_OUTPUT"
47            git status --porcelain -- '*.dart'
48          else
49            echo "changes=false" >> "$GITHUB_OUTPUT"
50          fi          
51      - name: Open PR with formatting fixes
52        if: steps.format.outputs.changes == 'true' && inputs.allow_prs == true
53        uses: peter-evans/create-pull-request@v7
54        with:
55          token: ${{ secrets.GITHUB_TOKEN }}
56          commit-message: "style: apply dart format"
57          title: "style: apply dart format"
58          body: "Automated PR for Flutter/Dart formatting fixes."
59          branch: "automated/dart-format-${{ github.ref_name }}"
60          base: ${{ github.ref_name }}
61          delete-branch: true
62      - name: Fail if formatting drift exists
63        if: steps.format.outputs.changes == 'true'
64        run: |
65          echo "Formatting drift detected. Fix directly or merge the generated PR."
66          exit 1          
67
68  flutter-build-artifacts:
69    name: Flutter build artifacts (release/monthly only)
70    needs: [route, discover, flutter-analyze-test]
71    if: ${{ needs.discover.outputs.has_flutter == 'true' && (needs.route.outputs.run_release == 'true' || needs.route.outputs.is_monthly == 'true' || (github.event_name == 'workflow_dispatch' && inputs.mode == 'build')) }}
72    runs-on: ubuntu-latest
73    steps:
74      - uses: actions/checkout@v4
75      - uses: subosito/flutter-action@v2
76        with:
77          channel: stable
78      - run: flutter pub get
79      - run: flutter build linux --release
80      - run: flutter build apk --release || true
81
82      - uses: actions/upload-artifact@v4
83        with:
84          name: flutter-release-bundles
85          retention-days: 1
86          path: |
87            build/linux/**
88            build/app/outputs/flutter-apk/*.apk

Fastforge note

Fastforge is optional. Keep it if you want it; remove it if you don’t. The key pattern is to keep release outputs available through independent lanes (flatpak, source packages, container artifacts, GoReleaser outputs) so your pipeline doesn’t depend on a single packaging tool.

Confidence note (tested manual dispatch)

The Flutter manual-dispatch pattern above is based on a working pipeline where mode=lint-fix plus allow_prs has been tested in practice (arran4/mlocate_explorer, commit 9ce9d36). Treat this as a higher-confidence baseline for Flutter than untested snippets, then add platform build lanes (Linux/Windows/macOS) only when your project actually needs cross-OS deliverables.

When you do add cross-OS Flutter builds, follow this same split:

  • keep format/analyze/test as the fast Ubuntu path,
  • gate expensive Linux/Windows/macOS artifact lanes behind run_build or release,
  • upload artifacts per platform and publish only from release-scoped jobs.

Dart release/version-sync pattern (from dartobjectutils)

For Dart-first repos, one practical pattern is:

  1. run dart analyze / dart test,
  2. on manual dispatch, compute the next version (patch|minor|major|manual),
  3. update pubspec.yaml, commit, tag, push,
  4. verify tag version matches pubspec.yaml and auto-fix with PR fallback when direct push fails.

Copy/paste release prep snippet:

 1  dart-release-prep:
 2    name: Dart release prep
 3    if: ${{ github.event_name == 'workflow_dispatch' }}
 4    runs-on: ubuntu-latest
 5    steps:
 6      - uses: actions/checkout@v4
 7        with:
 8          fetch-depth: 0
 9      - uses: dart-lang/setup-dart@v1
10      - name: Compute version and tag
11        env:
12          INCREMENT: ${{ inputs.increment }}
13          MANUAL_VERSION_INPUT: ${{ inputs.manual_version }}
14        run: |
15          set -euo pipefail
16          PUBSPEC_VERSION=$(awk '/^version:/ {print $2}' pubspec.yaml)
17          git fetch --tags
18          HIGHEST_TAG=$(git tag -l "v*" | sed 's/^v//' | sort -V | tail -n 1)
19          [ -z "$HIGHEST_TAG" ] && HIGHEST_TAG="0.0.0"
20
21          CURRENT_VERSION=$(echo -e "$PUBSPEC_VERSION          
22$HIGHEST_TAG" | sort -V | tail -n 1)
23
24          if [ "$INCREMENT" = "manual" ]; then
25            [ -z "$MANUAL_VERSION_INPUT" ] && { echo "manual_version required"; exit 1; }
26            NEW_VERSION="$MANUAL_VERSION_INPUT"
27          else
28            IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
29            case "$INCREMENT" in
30              major) NEW_VERSION="$((MAJOR+1)).0.0" ;;
31              minor) NEW_VERSION="$MAJOR.$((MINOR+1)).0" ;;
32              *) NEW_VERSION="$MAJOR.$MINOR.$((PATCH+1))" ;;
33            esac
34          fi
35
36          sed -i "s/^version: .*/version: $NEW_VERSION/" pubspec.yaml
37          git config user.name "github-actions[bot]"
38          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
39          git checkout -b "release/v$NEW_VERSION"
40          git add pubspec.yaml
41          git commit -m "Bump version to $NEW_VERSION"
42          git tag "v$NEW_VERSION"
43          git push origin "v$NEW_VERSION"
44          git push origin "release/v$NEW_VERSION"

Step 9: Qt/C++ and classic C lane

Include both Qt/CMake and Makefile detection paths.

 1  cpp-qt-build-test:
 2    name: Qt/C++ build
 3    needs: [route, discover]
 4    if: ${{ needs.discover.outputs.has_qt_cpp == 'true' && needs.route.outputs.run_code_checks == 'true' }}
 5    runs-on: ubuntu-latest
 6    steps:
 7      - uses: actions/checkout@v4
 8      - run: sudo apt-get update
 9      - run: sudo apt-get install -y cmake ninja-build build-essential qt6-base-dev qt6-tools-dev clang-format cppcheck
10      - name: Lint style and static checks
11        run: |
12          find . \( -name '*.cpp' -o -name '*.cc' -o -name '*.h' -o -name '*.hpp' \) -print0 | xargs -0 -r clang-format --dry-run --Werror
13          cppcheck --enable=warning,style,performance,portability --error-exitcode=1 .          
14      - run: cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
15      - run: cmake --build build --parallel
16      - run: ctest --test-dir build --output-on-failure
17
18  c-make-build-test:
19    name: Classic C Makefile build
20    needs: [route, discover]
21    if: ${{ needs.discover.outputs.has_make_c == 'true' && needs.route.outputs.run_code_checks == 'true' }}
22    runs-on: ubuntu-latest
23    steps:
24      - uses: actions/checkout@v4
25      - run: make -j"$(nproc)" all
26      - run: make test || true

Step 10: Integrated autofix + PR automation lane

You wanted this wired to real formatters and branch-name guessable behavior.

 1  autofix:
 2    name: Auto-format and open PR
 3    needs: [route, discover]
 4    if: ${{ github.event_name == 'workflow_dispatch' && inputs.mode == 'lint-fix' && inputs.allow_prs == true }}
 5    runs-on: ubuntu-latest
 6    steps:
 7      - uses: actions/checkout@v4
 8
 9      - name: Setup Go (if needed)
10        if: ${{ needs.discover.outputs.has_go == 'true' }}
11        uses: actions/setup-go@v6
12        with:
13          go-version-file: go.mod
14
15      - name: Setup Node (if needed)
16        if: ${{ needs.discover.outputs.has_node == 'true' }}
17        uses: actions/setup-node@v4
18        with:
19          node-version: '22'
20          cache: npm
21
22      - name: Setup Dart/Flutter (if needed)
23        if: ${{ needs.discover.outputs.has_dart == 'true' || needs.discover.outputs.has_flutter == 'true' }}
24        uses: subosito/flutter-action@v2
25        with:
26          channel: stable
27
28      - name: Run autofix formatters
29        shell: bash
30        run: |
31          set -euo pipefail
32          if [[ "${{ needs.discover.outputs.has_go }}" == "true" ]]; then
33            go fix ./... || true
34            go fmt ./... || true
35          fi
36          if [[ "${{ needs.discover.outputs.has_node }}" == "true" ]]; then
37            npm ci || true
38            npx prettier . --write || true
39          fi
40          if [[ "${{ needs.discover.outputs.has_dart }}" == "true" || "${{ needs.discover.outputs.has_flutter }}" == "true" ]]; then
41            dart format . || true
42          fi          
43
44      - name: Create PR if changes exist
45        env:
46          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
47        shell: bash
48        run: |
49          set -euo pipefail
50          if git diff --quiet; then
51            echo "No changes; exiting."
52            exit 0
53          fi
54
55          git config user.name "github-actions[bot]"
56          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
57
58          PARENT_PR="${{ github.event.pull_request.number || 'none' }}"
59          BRANCH="ci/autofix/${{ github.run_id }}-parent-${PARENT_PR}"
60
61          git checkout -b "$BRANCH"
62          git add -A
63          git commit -m "ci: automated formatting fixes"
64          git push origin "$BRANCH"
65
66          gh pr create \
67            --title "ci: automated formatting fixes" \
68            --body "Automated formatting pass. Parent-PR: ${PARENT_PR}" \
69            --base main \
70            --head "$BRANCH" \
71            --label "ci-autofix"

Cleanup on parent PR close (specific)

 1  cleanup-autofix-prs:
 2    name: Cleanup autofix PRs on parent close
 3    needs: [route]
 4    if: ${{ needs.route.outputs.run_cleanup == 'true' }}
 5    runs-on: ubuntu-latest
 6    steps:
 7      - uses: actions/checkout@v4
 8      - env:
 9          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
10          PARENT_PR: ${{ github.event.pull_request.number }}
11        run: |
12          set -euo pipefail
13          gh pr list --state open --search "label:ci-autofix in:title" --json number,headRefName,body | \
14            jq -r '.[] | select(.body | contains("Parent-PR: '"$PARENT_PR"'")) | [.number, .headRefName] | @tsv' | \
15            while IFS=$'\t' read -r pr branch; do
16              gh pr close "$pr" --comment "Closing auto-fix PR because parent PR #$PARENT_PR was closed."
17              git push origin --delete "$branch" || true
18            done

This uses both a label and a guessable branch pattern with parent linkage. Also note the checkout step: if the cleanup job deletes remote branches with git push origin --delete, it needs a repository checkout first.

Repeated gotcha: any git-mutating CI job needs checkout first

If a job runs commands like git push, git push origin --delete, git commit, or branch operations, add checkout as the first step.

1steps:
2  - uses: actions/checkout@v4
3  - run: git push origin --delete "$BRANCH"

Treat this as a hard rule in generated workflows. The same issue repeatedly appears in real repos when cleanup jobs omit checkout.

Step 11: Docker as a release publish step

If repo has Go + Dockerfile or standalone Docker service, build and (optionally) push.

 1  docker-build:
 2    name: Docker build
 3    needs: [route, discover]
 4    if: ${{ needs.discover.outputs.has_docker == 'true' && needs.route.outputs.run_release == 'true' }}
 5    runs-on: ubuntu-latest
 6    steps:
 7      - uses: actions/checkout@v4
 8      - uses: docker/setup-qemu-action@v3
 9      - uses: docker/setup-buildx-action@v3
10      - uses: docker/build-push-action@v6
11        with:
12          context: .
13          file: ${{ hashFiles('Dockerfile.goreleaser') != '' && 'Dockerfile.goreleaser' || 'Dockerfile' }}
14          push: false
15          tags: ghcr.io/${{ github.repository }}:ci-${{ github.run_id }}
16
17  docker-release:
18    name: Docker release
19    needs: [route, discover, docker-build]
20    if: ${{ needs.discover.outputs.has_docker == 'true' && needs.route.outputs.run_release == 'true' }}
21    runs-on: ubuntu-latest
22    permissions:
23      contents: read
24      packages: write
25    steps:
26      - uses: actions/checkout@v4
27      - uses: docker/setup-qemu-action@v3
28      - uses: docker/setup-buildx-action@v3
29      - uses: docker/login-action@v3
30        with:
31          registry: ghcr.io
32          username: ${{ github.actor }}
33          password: ${{ secrets.GITHUB_TOKEN }}
34      - uses: docker/build-push-action@v6
35        with:
36          context: .
37          push: true
38          tags: |
39            ghcr.io/${{ github.repository }}:${{ github.ref_name }}
40            ghcr.io/${{ github.repository }}:latest            
41          platforms: linux/amd64,linux/arm64

Dotfiles/Chezmoi/Docker lessons (high-value niche pattern)

For most app repos, the generic Docker section above is enough. For dotfiles + chezmoi style repos, a few extra checks from a working pipeline are worth copying:

  1. Shell config validity is a real test target (bash/zsh parse checks after apply).
  2. Run chezmoi apply in CI to catch template/rendering regressions early.
  3. Use Docker build-contexts when your Dockerfile expects the repo contents as a named context.
  4. Use docker/metadata-action tag strategy so manual override tags and semver tags stay consistent.
  5. Package and publish a dotfiles archive (chezmoi archive) as a first-class release artifact.

Copy/paste pattern:

 1  shell-check-and-chezmoi-apply:
 2    name: ShellCheck + chezmoi apply
 3    needs: [route]
 4    if: ${{ needs.route.outputs.run_code_checks == 'true' }}
 5    runs-on: ubuntu-latest
 6    steps:
 7      - uses: actions/checkout@v4
 8      - name: Install shellcheck and zsh
 9        run: sudo apt-get update && sudo apt-get install -y shellcheck zsh
10      - name: ShellCheck scripts
11        run: |
12          shopt -s globstar
13          shellcheck **/*.sh          
14      - name: Apply chezmoi source into CI home
15        run: |
16          yes "" | sh -c "$(curl -fsLS get.chezmoi.io)" -- init --no-tty --debug --source=$PWD --apply          
17      - name: Verify rendered shell files parse
18        run: |
19          for f in ~/.bashrc ~/.bash_profile ~/.bash_login ~/.bash_logout ~/.profile; do
20            [[ -f "$f" ]] && bash -n "$f"
21          done
22          for f in ~/.zshrc ~/.zprofile ~/.zlogin ~/.zlogout ~/.zshenv; do
23            [[ -f "$f" ]] && zsh -n "$f"
24          done          
25
26  docker-release:
27    name: Docker release
28    needs: [route]
29    if: ${{ needs.route.outputs.run_release == 'true' }}
30    runs-on: ubuntu-latest
31    steps:
32      - uses: actions/checkout@v4
33      - uses: docker/setup-qemu-action@v3
34      - uses: docker/setup-buildx-action@v3
35      - uses: docker/login-action@v3
36        with:
37          registry: ghcr.io
38          username: ${{ github.actor }}
39          password: ${{ secrets.GITHUB_TOKEN }}
40      - name: Docker metadata
41        id: meta
42        uses: docker/metadata-action@v5
43        with:
44          images: ghcr.io/${{ github.repository_owner }}/dev-dotfiles-debian
45          tags: |
46            type=ref,event=tag
47            type=semver,pattern={{version}}
48            type=semver,pattern={{major}}.{{minor}}
49            type=raw,value=${{ inputs.release_version_override }},enable=${{ inputs.release_version_override != '' }}
50            type=raw,value=latest,enable={{is_default_branch}}            
51      - uses: docker/build-push-action@v6
52        with:
53          context: .
54          build-contexts: dotfiles=.
55          file: containers/dev-dotfiles-debian/Dockerfile
56          push: true
57          tags: ${{ steps.meta.outputs.tags }}
58
59  package-dotfiles:
60    name: Package dotfiles archive
61    needs: [route]
62    if: ${{ needs.route.outputs.run_release == 'true' }}
63    runs-on: ubuntu-latest
64    steps:
65      - uses: actions/checkout@v4
66      - name: Build dotfiles archive
67        run: |
68          yes "" | sh -c "$(curl -fsLS get.chezmoi.io)" -- init --no-tty --debug --source=$PWD --apply
69          ./bin/chezmoi archive --source=$PWD --format zip --output dotfiles.zip          
70      - uses: actions/upload-artifact@v4
71        with:
72          name: dotfiles-archive
73          retention-days: 1
74          path: dotfiles.zip

Treat this as an opt-in lane: niche, but very effective when your repo is configuration-driven.

Step 12: GoReleaser lane (binary + packages)

Important reliability guard (from real-world PR fixes): avoid running GoReleaser on both tag-push and release: published for the same version. If both fire, you can get duplicate upload errors (422 already_exists). Keep GoReleaser scoped to:

  • tag push events (push + refs/tags/v*), or
  • explicit manual release dispatch modes.

If you publish Homebrew formulas, keep the article generic and parameterized, then provide your real tap as an example. For example, a tap can be OWNER/homebrew-tap (your concrete case: arran4/homebrew-tap). For cross-repo updates, set TAP_GITHUB_TOKEN in secrets and wire it to both the workflow env (TAP_GITHUB_TOKEN) and GoReleaser config ({{ .Env.TAP_GITHUB_TOKEN }}), with PR updates enabled and non-draft (draft: false).

Confidence note: the GoReleaser profile used in arran4/go-playerctl (commit 53e2a00) is a strong practical baseline for manual-dispatch releases and should be preferred over purely theoretical snippets when bootstrapping similar Go projects.

Important scope rule: only add binary build/release lanes when the project actually produces binaries. If the repo is a library, config repo, API schema repo, or another non-binary project, keep:

  • tagging,
  • GitHub release creation,
  • release notes generation,
  • discussions,
  • lint/test/vet/fix/security checks,
  • package-manager publication steps that make sense (npm publish, dart pub publish, etc),

and skip binary-specific lanes like GoReleaser builds, app bundle packaging, Homebrew formulas for non-binaries, or Docker image publishing unless the repository genuinely ships those deliverables.

 1  goreleaser:
 2    name: GoReleaser
 3    # In practice, include all quality gates here (for example: go-test, go-vet, go-lint, format).
 4    needs: [route, discover, go-test, prepare-release-tag]
 5    if: ${{ needs.discover.outputs.has_go == 'true' && needs.discover.outputs.has_goreleaser == 'true' && (((github.event_name == 'push') && startsWith(github.ref, 'refs/tags/v')) || (github.event_name == 'workflow_dispatch' && startsWith(inputs.mode, 'release-'))) }}
 6    runs-on: ubuntu-latest
 7    steps:
 8      - uses: actions/checkout@v4
 9        with:
10          fetch-depth: 0
11      - uses: actions/setup-go@v6
12        with:
13          go-version-file: go.mod
14      - name: Tag commit for release (workflow_dispatch)
15        if: ${{ github.event_name == 'workflow_dispatch' && startsWith(inputs.mode, 'release-') }}
16        run: git tag ${{ needs.prepare-release-tag.outputs.release_tag }}
17      - name: Run GoReleaser
18        uses: goreleaser/goreleaser-action@v6
19        with:
20          distribution: goreleaser
21          version: '~> v2'
22          args: >-
23            release --clean
24            ${{ (github.event_name == 'workflow_dispatch' && (inputs.mode == 'release-test' || inputs.mode == 'release-rc' || inputs.mode == 'release-alpha')) && '--snapshot' || '' }}            
25        env:
26          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
27          TAP_GITHUB_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }} # inject secrets.TAP_GITHUB_TOKEN
28          GORELEASER_CURRENT_TAG: ${{ needs.prepare-release-tag.outputs.release_tag }}

For release robustness, use an if: guard like this when aggregating many needs:

Important GoReleaser v2 note: avoid --tag in action args (it can fail with “unknown flag: –tag”). Instead set GORELEASER_CURRENT_TAG in env when you need to force the tag value from a prepared job output. For workflow-dispatch releases, also create the local tag on the checked-out commit before running GoReleaser.

Do/Don’t quick check:

1# ❌ Don't (fails on v2):
2# args: release --clean --tag v0.0.1
3
4# ✅ Do:
5# args: release --clean
6# env:
7#   GORELEASER_CURRENT_TAG: v0.0.1

1if: ${{ !failure() && !cancelled() && needs.route.outputs.run_release == 'true' }}

Example .goreleaser.yml baseline (copy/paste):

If your repo does not emit a binary, do not cargo-cult this whole file. In that case, keep the manual tag/release flow from Step 15 and any relevant package-publish steps, but omit the GoReleaser binary/archive/container sections entirely.

 1project_name: your-project
 2
 3before:
 4  hooks:
 5    - go mod tidy
 6
 7builds:
 8  - id: app
 9    binary: app
10    main: ./cmd/app
11    env:
12      - CGO_ENABLED=0
13
14archives:
15  - formats: [tar.gz]
16    format_overrides:
17      - goos: windows
18        formats: [zip]
19
20checksum:
21  name_template: checksums.txt
22
23dockers:
24  - image_templates:
25      - ghcr.io/OWNER/REPO:{{ .Tag }}
26      - ghcr.io/OWNER/REPO:latest
27    dockerfile: Dockerfile.goreleaser
28    use: buildx
29    goos: linux
30    goarch: [amd64, arm64]
31
32nfpms:
33  - id: linux-packages
34    package_name: app
35    vendor: Your Org
36    homepage: https://example.com
37    maintainer: You <you@example.com>
38    description: App description
39    license: MIT
40    formats:
41      - deb
42      - rpm
43      - apk
44      - archlinux
45    section: default
46    priority: optional
47
48homebrew_casks:
49  -
50    repository:
51      owner: arran4
52      name: homebrew-tap
53      branch: "{{.ProjectName}}-{{.Version}}"
54      token: "{{ .Env.TAP_GITHUB_TOKEN }}"
55      pull_request:
56        enabled: true
57        draft: false
58    commit_author:
59      name: goreleaserbot
60      email: bot@goreleaser.com
61
62scoops:
63  - name: app
64    bucket:
65      owner: OWNER
66      name: scoop-bucket
67
68changelog:
69  sort: asc
70  filters:
71    exclude:
72      - '^docs:'
73      - '^test:'

Important: avoid archive name templates for binaries

Do not set fragile custom archive naming templates for multi-arch binary archives unless you have a very strong reason and a tested collision-proof format.

A proven exception is a template that includes enough uniqueness dimensions (at minimum: project, version, os, arch), like the working go-playerctl pattern.

Why:

  • New architectures (for example windows/arm) can appear over time.
  • A hand-rolled name template that seemed unique can start colliding.
  • Typical failure is archive ... already exists during release.

Recommendation:

  • Keep GoReleaser archive names on defaults.
  • Keep only format_overrides for Windows zip/tar differences.
  • If you ever customize names, include enough dimensions (project, version, os, arch, and architecture variants) and test against the full matrix before release.

Example of a safer template shape used successfully for manual-dispatch releases:

1archives:
2  - formats: [tar.gz]
3    name_template: >-
4      {{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}

Step 13: Source Debian and Source RPM pipelines (separate lane)

You asked for this explicitly: source package generation should be its own lane and file structure.

Recommended repo layout:

 1packaging/
 2  debian/
 3    control
 4    rules
 5    changelog
 6    source/format
 7  rpm/
 8    app.spec
 9  scripts/
10    build-source-deb.sh
11    build-source-rpm.sh

Source Debian lane

 1  source-deb:
 2    name: Build source .dsc/.orig.tar.*
 3    needs: [route, discover]
 4    if: ${{ needs.discover.outputs.has_packaging == 'true' && needs.route.outputs.run_release == 'true' }}
 5    runs-on: ubuntu-latest
 6    steps:
 7      - uses: actions/checkout@v4
 8      - run: sudo apt-get update
 9      - run: sudo apt-get install -y devscripts debhelper build-essential fakeroot
10      - name: Build source Debian package
11        run: |
12          chmod +x packaging/scripts/build-source-deb.sh
13          packaging/scripts/build-source-deb.sh          
14      - uses: actions/upload-artifact@v4
15        with:
16          name: source-deb
17          retention-days: 1
18          path: |
19            dist/deb-source/*.dsc
20            dist/deb-source/*.debian.tar.*
21            dist/deb-source/*.orig.tar.*
22            dist/deb-source/*.changes

Example packaging/scripts/build-source-deb.sh:

 1#!/usr/bin/env bash
 2set -euo pipefail
 3
 4APP_NAME="app"
 5VERSION="${GITHUB_REF_NAME#v}"
 6WORKDIR="/tmp/${APP_NAME}-${VERSION}"
 7OUTDIR="$PWD/dist/deb-source"
 8
 9rm -rf "$WORKDIR"
10mkdir -p "$WORKDIR" "$OUTDIR"
11
12git archive --format=tar.gz --prefix="${APP_NAME}-${VERSION}/" -o "$OUTDIR/${APP_NAME}_${VERSION}.orig.tar.gz" HEAD
13
14tar -xzf "$OUTDIR/${APP_NAME}_${VERSION}.orig.tar.gz" -C /tmp
15cp -r packaging/debian "/tmp/${APP_NAME}-${VERSION}/debian"
16
17(
18  cd "/tmp/${APP_NAME}-${VERSION}"
19  dch --create -v "${VERSION}-1" --package "$APP_NAME" "Automated source release"
20  dpkg-buildpackage -S -sa
21)
22
23mv /tmp/${APP_NAME}_${VERSION}-1* "$OUTDIR/" || true

Source RPM lane

 1  source-rpm:
 2    name: Build source .src.rpm
 3    needs: [route, discover]
 4    if: ${{ needs.discover.outputs.has_packaging == 'true' && needs.route.outputs.run_release == 'true' }}
 5    runs-on: ubuntu-latest
 6    steps:
 7      - uses: actions/checkout@v4
 8      - run: sudo apt-get update
 9      - run: sudo apt-get install -y rpm
10      - name: Build source RPM
11        run: |
12          chmod +x packaging/scripts/build-source-rpm.sh
13          packaging/scripts/build-source-rpm.sh          
14      - uses: actions/upload-artifact@v4
15        with:
16          name: source-rpm
17          retention-days: 1
18          path: dist/rpm-source/*.src.rpm

Example packaging/scripts/build-source-rpm.sh:

 1#!/usr/bin/env bash
 2set -euo pipefail
 3
 4APP_NAME="app"
 5VERSION="${GITHUB_REF_NAME#v}"
 6TOPDIR="$PWD/.rpmbuild"
 7OUTDIR="$PWD/dist/rpm-source"
 8
 9mkdir -p "$TOPDIR"/{BUILD,RPMS,SOURCES,SPECS,SRPMS} "$OUTDIR"
10
11git archive --format=tar.gz --prefix="${APP_NAME}-${VERSION}/" -o "$TOPDIR/SOURCES/${APP_NAME}-${VERSION}.tar.gz" HEAD
12cp packaging/rpm/app.spec "$TOPDIR/SPECS/"
13
14rpmbuild \
15  --define "_topdir $TOPDIR" \
16  --define "version $VERSION" \
17  -bs "$TOPDIR/SPECS/app.spec"
18
19cp "$TOPDIR/SRPMS"/*.src.rpm "$OUTDIR/"

This is intentionally independent from fastforge/GoReleaser so source package publishing is never blocked by app-bundle tooling changes.

Step 14: Flatpak and optional app-store packaging lane

For Flutter/Qt desktop apps, keep a manual lane. If Flutter build artifacts were produced earlier, this lane can package those; if not, it can run from source directly.

 1  flatpak-build:
 2    name: Flatpak package
 3    needs: [route, discover]
 4    if: ${{ needs.route.outputs.run_release == 'true' && (needs.discover.outputs.has_flutter == 'true' || needs.discover.outputs.has_qt_cpp == 'true') }}
 5    runs-on: ubuntu-latest
 6    steps:
 7      - uses: actions/checkout@v4
 8      - run: sudo apt-get update
 9      - run: sudo apt-get install -y flatpak flatpak-builder
10      - name: Build Flatpak
11        run: |
12          flatpak-builder --force-clean build-dir packaging/flatpak/app.yaml          
13      - uses: actions/upload-artifact@v4
14        with:
15          name: flatpak-bundle
16          retention-days: 1
17          path: build-dir

Step 15: Release fan-in and publish stages

Use multiple deploy stages (package -> publish -> promote).

Manual release creation pattern (gh-release script style)

When you manually create releases, the arran4/dotfiles executable_gh-release.sh flow is a strong pattern, and it closes a common guide gap: generated release notes + discussion creation should be first-class:

  • verify default GitHub repo context exists,
  • compute version with git-tag-inc (-print-version-only),
  • create and push tags with retry,
  • create GitHub release with --generate-notes,
  • use a default discussion category of Announcements (safe for default discussion setups), with graceful fallback when permissions/discussions prevent linking,
  • mark prerelease automatically for test|alpha|beta|rc increments.
  • fetch tags and compare the highest tag version against the source-controlled version before bumping, so release automation never bumps from stale in-repo version text.

You can keep this as a local operator script and wire equivalent logic in CI manual-dispatch mode.

Copy/paste CI step style:

 1  manual-gh-release:
 2    name: Manual release creation
 3    needs: [prepare-release-tag]
 4    if: ${{ github.event_name == 'workflow_dispatch' && startsWith(inputs.mode, 'release-') }}
 5    runs-on: ubuntu-latest
 6    permissions:
 7      contents: write
 8      discussions: write
 9    steps:
10      - uses: actions/checkout@v4
11        with:
12          fetch-depth: 0
13      - name: Sync version source with highest existing tag first
14        run: |
15          set -euo pipefail
16          git fetch --tags --force
17          # For repos with a source-controlled version, bump it to the release version
18          # and commit it before tagging (so the tag includes the bump).
19          # Example for CMake:
20          # RELEASE_VERSION="${{ needs.prepare-release-tag.outputs.release_tag }}"
21          # RELEASE_VERSION="${RELEASE_VERSION#v}"
22          # sed -i -E "s/(project\([^ ]+ VERSION )[^ )]+/\1$RELEASE_VERSION/" CMakeLists.txt
23          # git add CMakeLists.txt
24          # git commit -m "chore: bump release version to $RELEASE_VERSION"          
25      - name: Push prepared tag (retry)
26        env:
27          TAG: ${{ needs.prepare-release-tag.outputs.release_tag }}
28        run: |
29          set -euo pipefail
30          git tag "$TAG"
31          git push origin "$TAG" || { sleep 2; git push origin "$TAG"; }          
32      - name: Create release with generated notes + discussion
33        env:
34          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
35          TAG: ${{ needs.prepare-release-tag.outputs.release_tag }}
36        run: |
37          set -euo pipefail
38          prerelease=""
39          case "${{ inputs.mode }}" in
40            release-test|release-rc|release-alpha) prerelease="--prerelease" ;;
41          esac
42
43          discussion_arg="--discussion-category Announcements"
44
45          # Permissions/discussions can block discussion linking in some repos.
46          # Fall back to plain release creation if category linking fails.
47          if [[ -n "$prerelease" ]]; then
48            gh release create "$TAG" --generate-notes $prerelease || true
49          else
50            gh release create "$TAG" --generate-notes $discussion_arg || \
51              gh release create "$TAG" --generate-notes
52          fi

Guide requirement: if you include a manual release lane, include both generated notes (--generate-notes) and discussion-category selection fallback logic so the LLM-generated workflow does not omit release discussions in repositories that use them. Use a fixed default discussion category (Announcements) and fall back to plain gh release create --generate-notes when permissions or discussions configuration block category linking. When running in Actions, set permissions.discussions: write (plus contents: write) for this lane.

To avoid duplicate release work, keep artifact publishers scoped by event (for example GoReleaser on tag-push/manual only, not release: published).

Integrate language publishers in the same publish stage:

  • Go binaries: GoReleaser publish (GitHub releases + packages)
  • Node/TS libraries: npm publish with latest/next dist-tags
  • Dart/Flutter libraries: dart pub publish (or dry-run in non-release modes)
  • Docker: release-only buildx push to GHCR, but only if the repo actually ships an image
  • Non-binary repos: tag + GitHub release + generated notes + discussion flow, without inventing binary artifacts
  • Versioned source repos: fetch tags and bump from the maximum of source version and latest tag, not just the checked-in version text
 1  publish-draft:
 2    name: Publish draft release assets
 3    needs:
 4      - goreleaser
 5      - source-deb
 6      - source-rpm
 7      - docker-release
 8    if: ${{ needs.route.outputs.run_release == 'true' }}
 9    runs-on: ubuntu-latest
10    steps:
11      - name: Collect artifacts
12        uses: actions/download-artifact@v4
13        with:
14          path: dist-release
15      - name: Publish draft GitHub release
16        uses: softprops/action-gh-release@v2
17        with:
18          draft: true
19          files: dist-release/**
20        env:
21          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
22
23  promote-release:
24    name: Promote draft to published
25    needs: [publish-draft]
26    if: ${{ github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && startsWith(inputs.mode, 'release-')) }}
27    runs-on: ubuntu-latest
28    steps:
29      - name: Release promoted via upstream process
30        run: echo "Promotion step placeholder (gh api patch release draft=false)"

Optional: Prepare next development version PR after release

This pattern from the referenced workflow is useful for repos that keep -SNAPSHOT / development versions in source control.

 1  prepare-next-version-pr:
 2    name: Prepare next development iteration PR
 3    needs: [publish-draft]
 4    if: ${{ github.event_name == 'workflow_dispatch' && (startsWith(inputs.mode, 'release-') || inputs.mode == 'release-test') }}
 5    runs-on: ubuntu-latest
 6    steps:
 7      - uses: actions/checkout@v4
 8      - name: Bump to next version and open PR
 9        env:
10          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
11        run: |
12          set -euo pipefail
13          NEXT_VERSION="${{ needs.prepare-release-tag.outputs.next_version || '' }}"
14          [[ -z "$NEXT_VERSION" ]] && { echo "No next version calculated; skipping."; exit 0; }
15
16          BRANCH="bump-version-$NEXT_VERSION"
17          git config user.name "github-actions[bot]"
18          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
19          git checkout -b "$BRANCH"
20
21          # Replace with repo-specific version bump command(s)
22          # mvn versions:set -DnewVersion="$NEXT_VERSION" -DgenerateBackupPoms=false
23          # sed -i -E "s/(project\([^ ]+ VERSION )[^ )]+/\1$NEXT_VERSION/" CMakeLists.txt
24
25          git add -A
26          git commit -m "Prepare next development iteration $NEXT_VERSION"
27          git push -u origin "$BRANCH"
28          gh pr create --title "Prepare next development iteration $NEXT_VERSION" --body "Automated PR for next iteration." --base main --head "$BRANCH"

Step 16: Full skeleton (compact but wired)

This is the high-level skeleton to start from. Keep this in .github/workflows/ci.yml and split script details into packaging/scripts and config files.

  1name: CI/CD
  2
  3on:
  4  push:
  5    branches: [main, master]
  6    tags: ['v*', 'v*.*.*', 'v*.*.*-rc*', 'v*.*.*-beta*', 'test-*']
  7  pull_request:
  8    types: [opened, synchronize, reopened, ready_for_review, closed]
  9    branches: [main, master]
 10  release:
 11    types: [published]
 12  workflow_dispatch:
 13    inputs:
 14      mode:
 15        type: choice
 16        default: lint-fix
 17        options: [lint-fix, build, release-major, release-minor, release-patch, release-test, release-rc, release-alpha, monthly-maintenance]
 18      release_version_override:
 19        type: string
 20        default: ''
 21      allow_prs:
 22        type: boolean
 23        default: true
 24  schedule:
 25    - cron: '17 3 1 * *'
 26    - cron: '41 2 * * *'
 27
 28concurrency:
 29  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }}
 30  cancel-in-progress: true
 31
 32permissions:
 33  contents: write
 34  pull-requests: write
 35  checks: write
 36  packages: write
 37  security-events: write
 38
 39jobs:
 40  route:
 41    # ... from section above
 42  prepare-release-tag:
 43    needs: [route]
 44    # ... from section above
 45
 46  discover:
 47    needs: route
 48    # ... from section above
 49
 50  gitleaks:
 51    needs: [route, discover]
 52    # ...
 53
 54  java-build-test:
 55    needs: [route, discover]
 56    # ...
 57
 58  hugo-build:
 59    needs: [route, discover]
 60    # ...
 61
 62  hugo-deploy:
 63    needs: [route, discover, hugo-build]
 64    # ...
 65
 66  golangci:
 67    needs: [route, discover]
 68    # ...
 69
 70  go-test:
 71    needs: [route, discover, golangci]
 72    # ...
 73
 74  go-vet:
 75    needs: [route, discover]
 76    # ...
 77
 78  go-fmt-pr:
 79    needs: [route, discover]
 80    # ...
 81
 82  node-lint-test:
 83    needs: [route, discover]
 84    # ...
 85
 86  dart-analyze-test:
 87    needs: [route, discover]
 88    # ...
 89
 90  flutter-analyze-test:
 91    needs: [route, discover]
 92    # ...
 93
 94  flutter-build-artifacts:
 95    needs: [route, discover, flutter-analyze-test]
 96    # ...
 97
 98  cpp-qt-build-test:
 99    needs: [route, discover]
100    # ...
101
102  c-make-build-test:
103    needs: [route, discover]
104    # ...
105
106  docker-build:
107    needs: [route, discover]
108    # ...
109
110  autofix:
111    needs: [route, discover]
112    # ...
113
114  cleanup-autofix-prs:
115    needs: [route]
116    # ...
117
118  goreleaser:
119    needs: [route, discover, go-test, prepare-release-tag]
120    # ...
121
122  source-deb:
123    needs: [route, discover]
124    # ...
125
126  source-rpm:
127    needs: [route, discover]
128    # ...
129
130  docker-release:
131    needs: [route, discover, docker-build]
132    # ...
133
134  publish-draft:
135    needs: [goreleaser, source-deb, source-rpm, docker-release]
136    # ...
137
138  promote-release:
139    needs: [publish-draft]
140    # ...
141
142  prepare-next-version-pr:
143    needs: [publish-draft, prepare-release-tag]
144    # ...

What to decide at install time vs runtime

Install/template time (prefer this):

  • expected project stacks,
  • release channels,
  • package targets,
  • which jobs are required.

Runtime (safety):

  • file presence detection,
  • public/private profile,
  • event-mode routing,
  • monthly/nightly schedule behavior.

This gives sane defaults while still protecting mixed repos.

Public vs private behavior recommendations

AreaPublicPrivate
OS matrixLinux default (add macOS/Windows only when required)Linux default
Parallelismwide job fan-outnarrower job fan-out, parallel inside step
Securitybroader PR scansmonthly/full-mode deep scans
Artifact retentionlongershorter
Validation strictnessmaximumpractical baseline + release hardening

Visibility should be auto-detected (github.event.repository.private) and not manually toggled.

Storage guardrail: artifact expiry policy (important)

To prevent GitHub Actions storage overages, set retention-days on every actions/upload-artifact step.

Required policy for this template:

  • set retention-days: 1 on every actions/upload-artifact step.
  • publish/promote jobs should consume artifacts immediately in the same workflow run.

Copy/paste baseline:

1- uses: actions/upload-artifact@v4
2  with:
3    name: ci-temp-output
4    path: dist/**
5    retention-days: 1

Optional monthly cleanup (especially useful for private repos with low storage quota):

 1  cleanup-old-artifacts:
 2    name: Cleanup old CI artifacts
 3    if: ${{ needs.route.outputs.is_monthly == 'true' }}
 4    runs-on: ubuntu-latest
 5    steps:
 6      - name: Delete artifacts older than 1 day
 7        env:
 8          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 9        run: |
10          set -euo pipefail
11          cutoff=$(date -u -d '1 day ago' +%s)
12          gh api repos/${{ github.repository }}/actions/artifacts --paginate \
13            --jq '.artifacts[] | [.id, .created_at] | @tsv' | \
14          while IFS=$'	' read -r id created; do
15            created_epoch=$(date -u -d "$created" +%s)
16            if (( created_epoch < cutoff )); then
17              gh api -X DELETE repos/${{ github.repository }}/actions/artifacts/$id || true
18            fi
19          done

Final checklist before rollout

  1. Add config files (.golangci.yml, .goreleaser.yml, analysis_options.yaml, .gitleaks.toml, .clang-format).
  2. Add packaging scripts under packaging/scripts/.
  3. Add packaging/debian and packaging/rpm metadata.
  4. Dry-run with workflow_dispatch mode=build or mode=lint-fix.
  5. Validate lint-fix creates/labels branches correctly.
  6. Validate pull_request.closed cleanup against test PRs.
  7. Validate monthly schedule and release lanes.
  8. Validate that every git-mutating job starts with actions/checkout@v4.

README distribution/install checklist (do not skip)

When you add release lanes, update README.md so users know how to install from each release target. Match the README to what the repo actually ships; if there is no binary, do not add fake binary install instructions just because the template has them. At minimum, list:

  • GitHub Releases (binary/tarball download path),
  • Homebrew tap install command,
  • Docker image pull/run command,
  • Go install command for Go CLIs,
  • native package methods (deb, rpm, apk, archlinux) where available.

Copy/paste template:

 1## Install
 2
 3### GitHub Releases
 4Download binaries from: https://github.com/OWNER/REPO/releases
 5
 6### Homebrew
 7brew tap OWNER/homebrew-tap
 8brew install app
 9
10### Docker
11docker pull ghcr.io/OWNER/REPO:latest
12docker run --rm ghcr.io/OWNER/REPO:latest --help
13
14### Go install
15go install github.com/OWNER/REPO/cmd/app@latest
16
17### Native packages
18- Debian/Ubuntu (`.deb`): see Releases assets
19- RPM (`.rpm`): see Releases assets
20- Alpine (`.apk`): see Releases assets
21- Arch (`.pkg.tar.zst` or repo): see Releases assets

This keeps release automation and user-facing install documentation aligned.

Closing

If your goal is “one CI file that does everything”, make it explicit, sectioned, and policy-driven.

The winning pattern is:

  • route events,
  • detect capabilities,
  • branch by profile,
  • run language lanes in parallel,
  • split release lanes by output type,
  • and automate cleanup lifecycle.

That gives you the giant file you wanted, with practical behavior for real repos rather than demo YAML.