stacklok / stacklok/mecatl

build: pin Taskfile Go toolchain and isolate docs config generation

Open
#807 0 comments 0 reactions 1 assignee View on GitHub

@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

  1. Define one Taskfile Go-toolchain variable pinned to go1.26.6.
  2. 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 ambient go binary.
  3. Change docs:configref to run with both the pinned toolchain and GOWORK=off. It is a root-only generator and has no workspace-local dependency requirement.
  4. Keep workspace mode as the default for integrated root build/test/lint flows. Do not broadly disable it.
  5. Preserve existing GOWORK=off standalone checks for engine, OIDC, and provider modules; those prove external-consumer dependency closure and are intentionally different from integrated development.
  6. Run the canonical dependency-maintenance path under Go 1.26.6 and decide whether its resulting go.work.sum update is intentional dependency hygiene. Do not accept incidental docs-generation checksum churn.
  7. Document the distinction: go.work selects local modules but does not force downgrade from a newer Go binary; GOTOOLCHAIN=go1.26.6 is the local exact-toolchain escape hatch, while CI uses setup-go plus GOTOOLCHAIN=local.

Acceptance criteria

  • task docs:configref from a clean tree does not modify go.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=local posture.
  • Documentation explains the workspace/toolchain split and the intentional checksum-maintenance path.

Evidence

  • task docs:configref modifies go.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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.