Skip to content

Consuming the framework's shared CI tooling

Downstream apps get lint, security scans, tests, and coverage two ways, which compose: tools/Makefile.shared for the local gate, and the framework's reusable GitHub Actions workflows (ci-go.yml, release-go.yml) for CI.

1. Local gate — tools/Makefile.shared

Copy or symlink tools/Makefile.shared from the framework into your app, then include it from your root Makefile.

Vendor it (pin to the framework version you depend on):

V=$(go list -m -f '{{.Version}}' github.com/golusoris/golusoris)
cp "$(go env GOPATH)/pkg/mod/github.com/golusoris/golusoris@${V}/tools/Makefile.shared" tools/Makefile.shared
# myapp/Makefile
include tools/Makefile.shared

Or include it straight from the module cache, no copy:

# myapp/Makefile
GOLUSORIS ?= $(shell go env GOPATH)/pkg/mod/github.com/golusoris/golusoris@$(shell go list -m -f '{{.Version}}' github.com/golusoris/golusoris)
include $(GOLUSORIS)/tools/Makefile.shared

Targets after inclusion:

Target What it runs
make ci lint + sec + test — the full local gate
make lint golangci-lint run --config $(GOLANGCI_CONFIG) (default .golangci.yml)
make sec vuln + gosec (govulncheck then gosec -quiet)
make test go test -race -count=1 -timeout=120s ./...
make cover go test with -coverprofile=coverage.out, renders coverage.html
make build go build -trimpath ./cmd/...
make tidy go mod tidy
make gen sqlc + ogen + mockery
make dev air hot-reload
make spec-lint vacuum lint the OpenAPI spec with tools/spectral.yaml

Override any tool binary or path by setting its variable before inclusion — every tool is a ?= default:

GOLANGCI        := $(shell which golangci-lint)
GOLANGCI_CONFIG := .golangci.yml   # point at your own or the shared config
include tools/Makefile.shared

Scope a run to a subtree with PKG:

make test PKG=./internal/payments/...

Multi-module repositories

The framework discovers and gates all 32 Go modules through scripts/ci/go-modules.sh. make ci-all, make build-all, and make verify-all all use that single discovery path, so a newly tracked go.mod cannot silently miss the local or hosted module sweep. Downstream multi-module apps can adopt the same discovery pattern or call the reusable workflow once per module.

2. Reusable CI workflow — ci-go.yml

The framework publishes reusable GitHub Actions workflows under .github/workflows/. Call ci-go.yml via workflow_call from your app. It runs, as separate jobs: Conventional-Commits PR-title check, lint (golangci-lint), security (gosec, SARIF upload), vulnerabilities (govulncheck), test (-race with a coverage-threshold gate — Linux by default via the runs-on input; the job's steps also branch for a macOS leg, skipping Docker-requiring packages, for a caller that wraps this workflow in its own runs-on matrix), build, OpenAPI lint (vacuum), and apidiff.

# myapp/.github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  ci:
    uses: golusoris/golusoris/.github/workflows/ci-go.yml@main
    with:
      runs-on: ubuntu-26.04               # default; or your self-hosted runner-set label
      working-directory: .                  # dir holding go.mod; "." for a root module
      go-version-file: go.mod
      coverage-threshold: 70          # 85 for security-critical packages
      module-path: github.com/myorg/myapp
    secrets: inherit

Pin @main to a specific commit before relying on this in production — see "Pinning the reusable-workflow reference" below.

Coverage is not a separate workflow — it's the coverage-threshold input on the test job (set 0 to skip the gate).

Calling ci-go.yml for more than one module

If your app is also a multi-module repo, invoke ci-go.yml once per module (each uses: gets its own working-directory). The workflow is matrix-safe for this since #498: the coverage artifact is named coverage-<working-directory-slug> (or plain coverage at the repo root) instead of a fixed coverage, and the gosec SARIF upload is tagged with a gosec[/<working-directory>] code-scanning category — both derived from working-directory, so two calls in the same run no longer collide on the artifact name or overwrite each other's SARIF upload.

Pinning the reusable-workflow reference

The example above uses @main for readability. The app template this framework ships under template/ pins the same calls to a full commit SHA with a version comment instead — template/.github/workflows/ci.yml and release.yml both reference golusoris/golusoris/.github/workflows/<workflow>.yml@4b22fc0dc3c1f9c779b77e78a292539655d2dc69 # v0.12.0. Do the same in a real app: pin to a released tag's commit SHA (and bump it deliberately) rather than floating on @main, so an unreviewed change to this repository's default branch cannot silently change your CI.

Common inputs (all optional except where noted; see the workflow_call block at the top of .github/workflows/ci-go.yml for the full list and defaults):

Input Default Purpose
runs-on ubuntu-26.04 runner label every job runs on: GitHub-hosted by default, or your own self-hosted runner-set label
working-directory . directory holding your module's go.mod, relative to the repo root; set for apps whose module is not at the repo root
go-version-file go.mod where the Go version is resolved from — relative to the repo root, not working-directory (see the input's own description in ci-go.yml); a non-root module must pass e.g. <working-directory>/go.mod
coverage-threshold 70 minimum total coverage %; 0 skips the check
golangci-version v2.13.2 golangci-lint version to install
golangci-config (empty) path to a shared ruleset, relative to working-directory; empty = auto-discover the app's .golangci.yml in that same directory
module-path (empty) module path for the apidiff check, e.g. github.com/myorg/myapp
apidiff-base-ref (empty) exact comparison base for apidiff; empty selects the previous root vN tag
needs-docker true verify Docker before tests; set false if no testcontainers
container (empty) image to run the Go jobs in (cgo/system-lib builds)
system-packages (empty) Debian packages (name or name=version) every Go job needs
install-system-packages true install system-packages with bounded apt-get calls before verifying them; set false on a self-hosted image that already contains them
openapi-spec (empty) path to an OpenAPI spec for the vacuum lint; empty = skip
skip-apidiff false set true for a first release with no prior tag

3. Reusable release workflow — release-go.yml

release-go.yml runs only when a caller invokes it through workflow_call. The caller below selects v*.*.* tags. The reusable workflow publishes the multi-arch OCI image configured by the caller's GoReleaser file, signs its digest with keyless cosign, and publishes build-provenance and SPDX SBOM attestations. It makes no SLSA level claim.

# myapp/.github/workflows/release.yml
name: Release

on:
  push:
    tags: ["v*.*.*"]

permissions:
  contents: write     # attach release assets
  packages: write     # push image to GHCR
  id-token: write     # keyless cosign + provenance attestation
  attestations: write
  artifact-metadata: write

jobs:
  release:
    uses: golusoris/golusoris/.github/workflows/release-go.yml@fedcba9876543210fedcba9876543210fedcba98
    with:
      runs-on: ubuntu-26.04               # default; or your self-hosted runner-set label
      image-name: ghcr.io/myorg/myapp     # required
      goreleaser-config: tools/.goreleaser.yml

Replace the example fedcba... value with a reviewed full commit SHA from golusoris/golusoris. Keep that SHA for provenance verification; a branch or tag does not provide an immutable reusable-workflow identity.

The caller must grant all five permissions: a called workflow can reduce a caller's token permissions but cannot add missing ones. The reusable workflow rejects non-tag and non-SemVer refs, then reads the image digest from the current dist/artifacts.json GoReleaser receipt and confirms that the registry tag resolves to that same digest before signing or attesting it. The SPDX SBOM is an OCI attestation on that digest. GoReleaser leaves the GitHub Release as a draft; only the final workflow step publishes it after all three supply-chain claims succeed, so immutable releases cannot become public first.

The caller's GoReleaser config must publish the exact image name passed to the workflow and include its default {{ .Tag }} tag. It must also make failed draft releases resumable:

dockers_v2:
  - images:
      - ghcr.io/myorg/myapp
    tags:
      - "{{ .Tag }}"

release:
  use_existing_draft: true
  replace_existing_artifacts: true

The image-name input must match the images value. The workflow accepts only SemVer tags that are also valid OCI tags: build metadata containing + and tags longer than 128 characters are rejected before the build. It forces draft mode; on a retry, the release settings reuse the draft and replace any assets uploaded by the failed attempt. A successful final publish then makes the release immutable when that repository setting is enabled.

Gate a deploy with the matching signature, provenance, and SPDX SBOM claims:

permissions:
  contents: read
  packages: read

jobs:
  verify:
    uses: golusoris/golusoris/.github/workflows/verify-provenance.yml@fedcba9876543210fedcba9876543210fedcba98
    with:
      image: ghcr.io/myorg/myapp
      digest: sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
      repository: myorg/myapp
      source-ref: refs/tags/v1.2.3
      source-digest: 0123456789abcdef0123456789abcdef01234567
      signer-workflow: golusoris/golusoris/.github/workflows/release-go.yml
      signer-digest: fedcba9876543210fedcba9876543210fedcba98

verify-provenance.yml fails if every verification mode is disabled. By default it verifies the keyless signature plus the SLSA provenance and SPDX SBOM predicates. The signer path and digest must match the commit-pinned release-go.yml call. Verification constrains the Fulcio certificate SAN and both attestations to that reusable signer, then independently constrains the source ref, source commit, and image digest.

The verifier uses the caller's GitHub token only for ghcr.io. Set registry to an empty string when verifying a public image on another registry; the workflow never forwards the GitHub token to a caller-selected host.

4. Required tools + versions

make ci expects these on PATH locally. tools/tool-versions.env is the repository authority; make tools-bootstrap installs that complete pinned set. The reusable workflow installs its required subset from explicit inputs.

Tool Repository pin Install locally
golangci-lint v2.13.2 go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2
gosec v2.29.0 scripts/ci/install-gosec.sh
govulncheck v1.8.0 go install golang.org/x/vuln/cmd/govulncheck@v1.8.0
mockery v3.8.0 go install github.com/vektra/mockery/v3@v3.8.0
air v1.67.4 go install github.com/air-verse/air@v1.67.4

5. golangci-lint config

.golangci.yml (repo root — golangci-lint's own auto-discovery path, and where praetor's flavor audit expects it) is a golangci-lint v2 config and the shared baseline for the framework and downstream apps. Point GOLANGCI_CONFIG (local) and the golangci-config input (CI) at your copy, or extend it in your app:

# myapp/.golangci.yml  (golangci-lint v2)
version: "2"
# copy the shared .golangci.yml and layer app-specific overrides here,
# or vendor it under a different name and set golangci-config accordingly
# in ci-go.yml.

If golangci-config is left empty in ci-go.yml, golangci-lint auto-discovers the app's own .golangci.yml at its repo root — the recommended default, and the same file praetor's flavor audit looks for; set golangci-config only to opt into a path other than your own root .golangci.yml.

6. Git hooks

make ci is the intended local gate for apps. The framework itself uses lefthook with finer-grained hooks (below); the minimal app-side configuration is:

# lefthook.yml
pre-commit:
  commands:
    ci:
      run: make ci

The framework's own lefthook.yml + scripts/hooks/ is a finer-grained template (staged-package lint, commit-msg Conventional Commits + DCO, pre-push build + go test -short) that apps can copy verbatim.