Skip to content

Contributing

This project is fully AI generated

Human review is the most valuable contribution it can receive. Reviews of the architecture decisions count just as much as code.

CONTRIBUTING.md in the repository root is the full document — development environment, the real Makefile targets, the three test tiers, commit conventions, and the make verify contract. This page is the short version.

Quick start

git clone <repository-url>
cd authentik-operator
make build     # generate, format, vet, build bin/manager
make test      # unit + envtest
make help      # every target, with descriptions

Tooling — controller-gen, kustomize, setup-envtest, golangci-lint, helm-docs — is bootstrapped into bin/ on first use and pinned in the Makefile. Do not upgrade any of them by hand; bump the *_VERSION variable so a clean checkout and CI stay identical.

Test tiers

Run the cheapest tier that can catch your mistake.

make test-unit

go test ./internal/... -race -short. No envtest, no Docker, no cluster. Seconds. This is the inner loop.

Because it passes -short, anything needing more than pure Go should guard itself with testing.Short() and skip.

make test

The full suite except test/e2e, against a real kube-apiserver and etcd. CRDs apply, admission runs, watches fire — but there is no kubelet, so nothing you create becomes a running Pod.

Reconciler behaviour belongs here: conditions, finalizers, ownership, and the cross-namespace Secret resolution rules from ADR 0001. Coverage lands in cover.out.

make authentik-up     # start a local authentik (Docker)
make test-e2e         # go test ./test/e2e/... -v -timeout 30m
make authentik-down   # stop it and delete its volumes

make test-e2e does not start authentik for you, so you can iterate without paying the startup cost each time. It does not tear anything down either.

E2E is for what only a real authentik can prove: API compatibility across the supported versions, adoption behaviour from ADR 0002, and the shape of the credentials written back into Secrets.

make verify must pass

This repository commits its generated artifacts — CRD YAML, RBAC, DeepCopy methods — and the version matrix must agree with supported-versions.yaml.

make verify   # manifests + generate + verify-versions, then fail if the tree changed

If CI says artifacts are out of date:

make manifests generate
make sync-versions
git add -A && git commit

Never hand-edit generated files

Anything under config/crd/bases/, any zz_generated.* file, or the version table inside the <!-- BEGIN SUPPORTED-VERSIONS --> markers. The next generator run discards your change silently.

Edit the source instead: the Go types, or supported-versions.yaml.

Documentation

This site is Zensical. Pages live in docs/, and the navigation is defined in zensical.toml — every file listed in nav must exist or the build fails.

zensical serve                     # live-reloading preview
zensical build --clean --strict    # what CI runs; warnings are errors

Strict mode fails on links that leave docs/

A relative link such as ../../SECURITY.md resolves on GitHub and breaks the site build, because the target is not a page in the site. Link to root-level files by absolute URL, or name them in a code span without linking.

Some pages are generated from other files. See Reference for which, and regenerate with:

hack/gen-docs.py            # rewrite derived pages
hack/gen-docs.py --check    # what CI runs; writes nothing

Commits

Conventional Commits:

feat(oauth2provider): write generated client credentials to a Secret
fix(connection): resolve cluster connection Secrets only from spec.tokenSecretRef.namespace
docs(security): document the ClusterAuthentikConnection blast radius

Types in use: feat, fix, docs, test, refactor, build, ci, chore. A breaking API change uses ! before the colon and a BREAKING CHANGE: footer. Summary under about 72 characters, imperative mood, no trailing full stop.

Before opening a pull request

make lint
make test
make verify
  • Explain why, not what — the diff shows what.
  • Keep it focused. A refactor and a behaviour change in one PR are hard to review and harder to revert.
  • Include tests at the cheapest tier that can prove the change.
  • Update the docs in the same PR: a new kind needs a guide page and a row in the status tables; anything touching credentials or RBAC needs SECURITY.md and Security.
  • A new condition reason needs a row in Conditions — that page is hand-written and cannot be generated.
  • A design decision with real trade-offs gets an ADR in docs/decisions/: next number, same structure as the existing two, and a nav entry in zensical.toml.
  • Commit generated artifacts.

Rebase on main rather than merging it in; keep history linear.

Reporting issues

Bugs and feature requests go in the issue tracker.

Security vulnerabilities do not

Report those privately through GitHub private security advisories. See Security and SECURITY.md in the repository root.

Licence

By contributing you agree your contributions are licensed under the Apache License 2.0, the same as the rest of the project.