build: pin Taskfile Go toolchain and isolate docs config generation
Open
@jbeda is already working on this.
Since Aug 27, 2026.
- Dominant language
- Go
- Stars
- 152
- Forks
- 16
- Avg merge
- 14h 48m
- Merged PRs (30d)
- 536
Description
Problem
The repository targets Go 1.26.6, but go.work does not force a developer running a newer Go binary to use that exact toolchain. In this checkout, ordinary go resolves to Go 1.27.0.
task docs:configref runs a root-only generator in workspace mode. That generator does not need workspace resolution, yet Go writes broad, unrelated checksum additions to go.work.sum while resolving workspace metadata. The same generator run with GOWORK=off is clean.
Plan
- Define one Taskfile Go-toolchain variable pinned to
go1.26.6. - Apply
GOTOOLCHAIN=<pinned>to Taskfile commands that invoke Go, so local Taskfile execution matches CI's provisioned Go 1.26.6 behavior rather than the caller's ambientgobinary. - Change
docs:configrefto run with both the pinned toolchain andGOWORK=off. It is a root-only generator and has no workspace-local dependency requirement. - Keep workspace mode as the default for integrated root build/test/lint flows. Do not broadly disable it.
- Preserve existing
GOWORK=offstandalone checks for engine, OIDC, and provider modules; those prove external-consumer dependency closure and are intentionally different from integrated development. - Run the canonical dependency-maintenance path under Go 1.26.6 and decide whether its resulting
go.work.sumupdate is intentional dependency hygiene. Do not accept incidental docs-generation checksum churn. - Document the distinction:
go.workselects local modules but does not force downgrade from a newer Go binary;GOTOOLCHAIN=go1.26.6is the local exact-toolchain escape hatch, while CI uses setup-go plusGOTOOLCHAIN=local.
Acceptance criteria
task docs:configreffrom a clean tree does not modifygo.work.sum.- A developer whose ambient Go is newer than 1.26.6 executes Taskfile Go commands under Go 1.26.6.
- Integrated commands still resolve local workspace modules.
- Existing standalone module checks remain
GOWORK=off. - CI behavior remains compatible with its provisioned Go 1.26.6 plus
GOTOOLCHAIN=localposture. - Documentation explains the workspace/toolchain split and the intentional checksum-maintenance path.
Evidence
task docs:configrefmodifiesgo.work.sum.GOWORK=off go run ./internal/configgen/cmd/configref ...does not.- Running the generator under Go 1.26.6 still changes
go.work.sum, but with a smaller diff than Go 1.27, confirming both workspace resolution and ambient toolchain version contribute.
Related context: the status-customization design work exposed the churn while running the required task docs gate.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.