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