From e75992dbae7de2f49738580d760686f2d06ee580 Mon Sep 17 00:00:00 2001 From: Teffen Ellis Date: Mon, 20 Apr 2026 23:11:21 +0000 Subject: [PATCH] docs: document local.env.yml prerequisite for Python tooling mypy and other Python CI targets require a local.env.yml with a secret_key before they can run. This was only set up automatically in CI (via .github/actions/setup) but was not mentioned in the contributor docs. Add a dedicated section explaining why it is needed and how to generate it with 'make gen-dev-config'. --- website/docs/developer-docs/contributing.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/website/docs/developer-docs/contributing.md b/website/docs/developer-docs/contributing.md index 83fbe448ad..c3401b4831 100644 --- a/website/docs/developer-docs/contributing.md +++ b/website/docs/developer-docs/contributing.md @@ -122,6 +122,18 @@ authentik can be run locally, although depending on which part you want to work This is documented in the [developer docs](./setup/frontend-dev-environment.md). +#### Running Python tooling locally (mypy, tests, linting) + +Before running any Python CI targets such as `make lint` or `make ci-lint-mypy`, you must generate a local configuration file: + +```shell +make gen-dev-config +``` + +This creates `local.env.yml` in the repository root with a random `secret_key`. It is required because `mypy_django_plugin` initializes Django at startup to introspect models, and Django requires a non-empty `SECRET_KEY`. Without this file (and without an `AUTHENTIK_SECRET_KEY` environment variable), mypy will fail with a confusing internal error. + +You only need to run this once per clone. The file is already listed in `.gitignore`. + ### Help with the docs Contributions to the technical documentation are greatly appreciated. Open a PR if you have improvements to make or new content to add. If you have questions or suggestions about the documentation, open an Issue. No contribution is too small.