Tooling

The Makefile is the single entry point for almost everything. CI delegates to the same targets.

Makefile cheat sheet

A focused subset of make help output, grouped by what you'll use most:

Build

Target	Purpose
make binary	go generate + dashboard + go build into dist/<goos>/<goarch>/traefik.
make binary-linux-amd64 / binary-linux-arm64 / binary-windows-amd64	Cross-compile presets.
make crossbinary-default	Cross-compile for Linux, macOS, Windows in one shot.
make build-image	docker buildx a multi-arch image, defaults to traefik:latest.
make build-image-dirty	Same, but skips rebuilding the dashboard if you already have one.

Generate

Target	Purpose
make generate	Run go generate from the repo root. Refreshes documentation reference.
make generate-webui	Build the dashboard into webui/static.
make clean-webui	Wipe the dashboard build output.
make generate-crd	Regenerate Kubernetes CRD clientset and deepcopy files. Calls script/code-gen.sh.
make generate-genconf	Regenerate the genconf package output.

Test

Target	Purpose
make test	Unit + integration + UI unit.
make test-unit	Go unit tests under ./pkg/... and ./cmd/....
make test-integration	End-to-end suite under ./integration (Docker required, 20m timeout).
make test-ui-unit	Run vitest for the dashboard inside Docker.
make test-gateway-api-conformance	Gateway API conformance suite.
make test-knative-conformance	Knative serving conformance suite.
make pull-images	One-time prefetch of integration-test Docker images.

Validate

Target	Purpose
make lint	golangci-lint run against .golangci.yml.
make validate-files	Misspell, shellcheck, vendor consistency.
make validate	lint + validate-files.
make fmt	gofmt -s -l -w over the tracked Go sources.

Docs

Target	Purpose
make docs	Build the documentation site (delegates to docs/Makefile).
make docs-serve	Serve the docs site locally.
make docs-pull-images	Pull the docs container images.

CI workflows

.github/workflows/ contains a small set of focused workflows. Each maps to one or more Makefile targets:

Workflow	What it runs
validate.yaml	make validate (lint + misspell + vendor + shell).
test-unit.yaml	make test-unit on a Go matrix.
test-integration.yaml	make test-integration sharded across multiple jobs.
test-gateway-api-conformance.yaml	make test-gateway-api-conformance.
test-knative-conformance.yaml	make test-knative-conformance.
template-webui.yaml	Reusable workflow for the dashboard.
documentation.yaml, check_doc.yaml	Documentation build and link checks.
build.yaml	Cross-compile and Docker build smoke test.
release.yaml	goreleaser tag-driven release pipeline.
experimental.yaml	Experimental builds (publishes nightly images).
sync-docker-images.yaml	Mirrors official images.
codeql.yml	GitHub CodeQL static analysis.

Linting

golangci-lint is configured in .golangci.yml. The linter set is curated — adding a new linter typically requires a separate cleanup pass. The most-touched checks day-to-day are:

• errcheck — every error must be checked or explicitly discarded.
• gosimple and staticcheck — idiomatic Go.
• gocritic — additional opinionated checks; some rules are disabled in .golangci.yml.
• revive — replaces the deprecated golint.

If you cannot satisfy a linter for a legitimate reason, use a //nolint:<rule> comment with a one-line justification.

Code generators

A few generators run via go generate:

• The root generate.go triggers documentation reference generation.
• pkg/cli/cli_test.go and similar fixtures are generated by Go tests' -update flag.
• CRD-related deepcopy files (*.zz_generated.deepcopy.go) are produced by controller-gen invoked from script/code-gen.sh.
• The dashboard is "generated" in the sense that webui/static/ is built before the Go build.

When in doubt, run make generate generate-crd generate-webui to refresh everything.

Environment variables that matter

The Makefile honors:

• GOOS, GOARCH — for cross-compilation.
• GOGC — passed straight to the Go compiler/runtime.
• VERSION, CODENAME — stamped into the binary via -ldflags -X.
• DOCKER_BUILD_PLATFORMS — for docker buildx calls.
• TESTFLAGS — appended to go test invocations.

Set these inline (make binary GOARCH=arm64) rather than exporting them globally — the Makefile snapshots them per target.

External tools

Tool	Why	Install
golangci-lint	Linting	https://golangci-lint.run
misspell	Spelling check	go install github.com/client9/misspell/cmd/misspell@latest
shellcheck	Shell script linting	OS package manager
controller-gen	CRD deepcopy generation	Pulled by script/code-gen.sh
goreleaser	Release builds	Used only by maintainers via .goreleaser.yml.tmpl
docker + buildx	UI build, multi-arch images, integration tests	Standard Docker installation
yarn	Dashboard package management	Through Corepack or Node tooling

Nix

flake.nix and flake.lock provide a reproducible development shell. If you have Nix with flakes enabled:

nix develop

This pins Go, Node, and the linting tools to the versions used by maintainers.