Skip to main content

Upgrade planning and CI policy

Upgrade planning is read-only. It compares authenik8.json, the declared and installed authenik8-core, and the running CLI's template contract.

npx create-authenik8-app@latest upgrade
npx create-authenik8-app@latest upgrade --json
npx create-authenik8-app@latest upgrade --check --json

--check exits with status 1 when an upgrade is pending or the plan is blocked by drift or a downgrade. Security-significant engine boundaries return explicit review steps before any dependency command. Engine install commands use the package manager's exact-save option; ranges are rejected because a later install could cross an unaudited auth boundary.

Follow the ordered plan: review migrations, install the exact engine target, run the listed deep Doctor command, exercise the application's auth flows, and only then acknowledge the verified versions:

npx create-authenik8-app@<planned-version> doctor --deep --ci
npx create-authenik8-app@<planned-version> upgrade --acknowledge

Between installation and acknowledgement, Doctor reports the older manifest version as a deliberate warning and upgrade policy remains pending. --acknowledge refuses a missing install, a version range, version drift, a downgrade, or a failed focused deep Doctor verification. It reruns that deep boundary immediately before the write, then atomically changes only the generator and engine release fields in authenik8.json; it never rewrites application auth code.

GitHub Actions gate​

Commit the selected package manager's lockfile, then preview and apply the managed workflow:

npx create-authenik8-app@latest add ci-github --dry-run
npx create-authenik8-app@latest add ci-github

The generated .github/workflows/authenik8.yml:

  • Uses a frozen npm, pnpm, or Bun lockfile install
  • Pins the CLI and any package-manager bootstrap version
  • Pins GitHub actions to full commit SHAs
  • Grants read-only repository contents permission
  • Disables checkout credential persistence
  • Runs pinned npx --yes create-authenik8-app@<version> doctor --ci --offline --strict
  • Enforces upgrade --check

In a clean checkout, Doctor validates .env.example with ephemeral authentication values held only in memory, so the workflow requires no committed .env or repository auth secrets. Explicitly mapped secret pairs are still validated and incomplete mappings fail closed.

The recipe refuses to overwrite an unmanaged workflow or a managed workflow with local edits.