Reference Operations / External Content Sync

CTX Authentik Repo Update

Instructions for refreshing the local and GitLab-hosted Authentik documentation context repository. Authentik as the self-hosted identity provider for company single sign-on, SAML, OIDC, LDAP, access control, and related identity infrastructure.

Text size
Status: publishedCreated: 06/29/2026Last updated: 06/29/2026

Document Scope

Just Headlines uses Authentik as the self-hosted identity provider for company single sign-on, SAML, OIDC, LDAP, access control, and related identity infrastructure.

This document defines the repeatable process for updating the Just Headlines Authentik documentation context repository. The purpose of this task is to keep a focused copy of selected official Authentik documentation and source material available inside the Just Headlines development environment so human developers, Codex sessions, AI agents, AI-assisted development tools, automation workers, and future MCP/RAG tooling can read the relevant Authentik documentation locally without repeatedly relying on external website lookups or pasted documentation links.

This document is written for both human operators and AI agents. It explains what the local context repository is, why it exists, which official Authentik sources are copied into the context repository, and what PowerShell block should be run whenever the Authentik documentation context needs to be refreshed.

1. Purpose

The Authentik documentation context repository exists so that Just Headlines has a local and GitLab-hosted copy of selected official Authentik reference material needed for self-hosted company single sign-on, SAML, OIDC, LDAP, identity-provider configuration, Docker-based deployment, Kubernetes/Helm deployment, PostgreSQL-backed operation, frontend reference, backend reference, API reference, blueprints, and future AI-agent/MCP/RAG work.

Unlike a context repository that mirrors one selected folder from one upstream Git repository, the Authentik context repository is assembled from more than one official source. A normal git pull inside C:\dev\ctx-authentik only updates the local copy from the Just Headlines GitLab context repository. It does not refresh the context repository from Authentik's official sources.

The Authentik update process does the following:

  1. Pulls the latest selected files from the official Authentik source repository.
  2. Copies the official Authentik documentation source from website/docs.
  3. Copies the official Authentik developer documentation source from website/docs/developer-docs.
  4. Copies selected backend, frontend, deployment, Docker, blueprint, API, and developer reference material from the Authentik source repository.
  5. Downloads selected public Authentik documentation pages.
  6. Attempts to download optional AI-readable documentation files if Authentik later publishes them.
  7. Pulls the latest selected files from the official Authentik Helm repository.
  8. Records the upstream commit values used for the refresh.
  9. Commits and pushes the refreshed context repository only if content changed.

The optional Authentik llms.txt and llms-full.txt downloads may return 404. That is not treated as a failure. The refresh report records the warning and continues.

The main Authentik developer documentation URL is:

https://docs.goauthentik.io/developer-docs/

2. Operational Use

Run this task whenever the Authentik documentation context should be refreshed from official Authentik sources.

This may be done manually during active SSO, SAML, OIDC, LDAP, identity-provider, Docker, Kubernetes, Helm, PostgreSQL, frontend, backend, API, blueprint, automation, or AI-agent development, especially before asking Codex or another AI coding agent to rely on Authentik implementation details.

After this task runs successfully, the local folder at C:\dev\ctx-authentik should contain the latest selected Authentik reference content, and the GitLab repository should contain a committed copy of that same refreshed context if any source content changed.

If the official Authentik content has not changed, the script should not create an unnecessary commit.

3. Source and Destination

Official Authentik documentation URL:

https://docs.goauthentik.io/

Official Authentik developer documentation URL:

https://docs.goauthentik.io/developer-docs/

Official Authentik installation documentation URL:

https://docs.goauthentik.io/install-config/

Official Authentik Docker Compose installation documentation URL:

https://docs.goauthentik.io/install-config/install/docker-compose/

Official Authentik Kubernetes installation documentation URL:

https://docs.goauthentik.io/install-config/install/kubernetes/

Official Authentik configuration documentation URL:

https://docs.goauthentik.io/install-config/configuration/

Official Authentik architecture documentation URL:

https://docs.goauthentik.io/core/architecture/

Official Authentik API documentation URL:

https://api.goauthentik.io/

Official Authentik source repository:

https://github.com/goauthentik/authentik.git

Official Authentik documentation repository path:

https://github.com/goauthentik/authentik/tree/main/website/docs

Official Authentik developer documentation repository path:

https://github.com/goauthentik/authentik/tree/main/website/docs/developer-docs

Official Authentik Helm repository:

https://github.com/goauthentik/helm.git

Official Authentik AI-agent note:

https://goauthentik.io/blog/2026-03-16-a-note-to-ai-agents-about-authentik/

Local Just Headlines context repository:

C:\dev\ctx-authentik

Temporary source checkout folder:

C:\dev\_authentik-source

GitLab context repository remote:

git@gitlab-sudostac:sudostac/ctx-authentik.git

Refresh report path:

C:\dev\ctx-authentik-refresh-report.txt

4. What This Script Does

This script performs the following task sequence:

  1. Changes the working directory to C:\dev.
  2. Removes the temporary Authentik source checkout folder if it already exists.
  3. Creates the expected local context repository folder if it does not already exist.
  4. Clones the official Authentik source repository.
  5. Copies the official Authentik documentation source from website/docs.
  6. Copies the official Authentik developer documentation source from website/docs/developer-docs.
  7. Copies selected Authentik source files, backend files, frontend files, deployment files, API schema files, blueprints, and developer support files when they exist.
  8. Downloads selected official Authentik website pages into docs-site.
  9. Attempts to download optional Authentik AI-readable documentation files.
  10. Records a warning and continues if the optional AI-readable files do not exist.
  11. Clones the official Authentik Helm repository.
  12. Copies the Helm material into the local context repository.
  13. Writes source URL metadata.
  14. Writes source commit metadata.
  15. Ensures the local context folder is a Git repository.
  16. Ensures the GitLab SSH remote is set correctly.
  17. Stages the refreshed Authentik context content.
  18. Creates a verbose Git commit only if the context content changed.
  19. Pushes the update to GitLab only if a commit was created.
  20. Prints a file count summary.
  21. Prints the final Git status.
  22. Removes the temporary source checkout folder.
  23. Writes a refresh report to C:\dev\ctx-authentik-refresh-report.txt.

5. PowerShell Refresh Script

Run this block from a normal PowerShell window.

cd C:\dev

$ErrorActionPreference = "Stop"

$LocalRepo = "C:\dev\ctx-authentik"
$TempRoot = "C:\dev\_authentik-source"
$ReportPath = "C:\dev\ctx-authentik-refresh-report.txt"

$AuthentikSource = Join-Path $TempRoot "authentik"
$HelmSource = Join-Path $TempRoot "helm"

$GitLabRemote = "git@gitlab-sudostac:sudostac/ctx-authentik.git"

$AuthentikRepo = "https://github.com/goauthentik/authentik.git"
$AuthentikHelmRepo = "https://github.com/goauthentik/helm.git"

$DocsUrls = @(
    @{ Name = "docs-home"; Url = "https://docs.goauthentik.io/"; File = "docs-home.html" },
    @{ Name = "developer-docs"; Url = "https://docs.goauthentik.io/developer-docs/"; File = "developer-docs.html" },
    @{ Name = "install-config"; Url = "https://docs.goauthentik.io/install-config/"; File = "install-config.html" },
    @{ Name = "docker-compose-install"; Url = "https://docs.goauthentik.io/install-config/install/docker-compose/"; File = "docker-compose-install.html" },
    @{ Name = "kubernetes-install"; Url = "https://docs.goauthentik.io/install-config/install/kubernetes/"; File = "kubernetes-install.html" },
    @{ Name = "configuration"; Url = "https://docs.goauthentik.io/install-config/configuration/"; File = "configuration.html" },
    @{ Name = "architecture"; Url = "https://docs.goauthentik.io/core/architecture/"; File = "architecture.html" },
    @{ Name = "api-docs"; Url = "https://api.goauthentik.io/"; File = "api-docs.html" },
    @{ Name = "ai-agent-note"; Url = "https://goauthentik.io/blog/2026-03-16-a-note-to-ai-agents-about-authentik/"; File = "ai-agent-note.html" }
)

$OptionalTextUrls = @(
    @{ Name = "docs-llms"; Url = "https://docs.goauthentik.io/llms.txt"; File = "llms.txt" },
    @{ Name = "docs-llms-full"; Url = "https://docs.goauthentik.io/llms-full.txt"; File = "llms-full.txt" }
)

$ReportLines = New-Object System.Collections.Generic.List[string]

function Add-Line {
    param ([string]$Text)
    $script:ReportLines.Add($Text)
    Write-Host $Text
}

function Count-Files {
    param ([string]$Path)
    if (Test-Path -LiteralPath $Path) {
        return (Get-ChildItem -LiteralPath $Path -Recurse -File -Force -ErrorAction SilentlyContinue | Measure-Object).Count
    }
    return "MISSING"
}

function Copy-PathRequired {
    param ([string]$Source, [string]$Destination)
    if (-not (Test-Path -LiteralPath $Source)) {
        throw "Required source path missing: $Source"
    }
    Remove-Item -Recurse -Force $Destination -ErrorAction SilentlyContinue
    $Parent = Split-Path -Parent $Destination
    New-Item -ItemType Directory -Force $Parent | Out-Null
    Copy-Item -Recurse -Force -LiteralPath $Source -Destination $Destination
}

function Copy-PathOptional {
    param ([string]$Source, [string]$Destination, [string]$Label)
    Remove-Item -Recurse -Force $Destination -ErrorAction SilentlyContinue
    if (Test-Path -LiteralPath $Source) {
        $Parent = Split-Path -Parent $Destination
        New-Item -ItemType Directory -Force $Parent | Out-Null
        Copy-Item -Recurse -Force -LiteralPath $Source -Destination $Destination
        Add-Line "Copied optional source: $Label"
    } else {
        $Parent = Split-Path -Parent $Destination
        New-Item -ItemType Directory -Force $Parent | Out-Null
        Add-Line "WARN - Optional source not found: $Label"
    }
}

function Copy-DirectoryContentsRequired {
    param ([string]$Source, [string]$Destination)
    if (-not (Test-Path -LiteralPath $Source)) {
        throw "Required source directory missing: $Source"
    }
    Remove-Item -Recurse -Force $Destination -ErrorAction SilentlyContinue
    New-Item -ItemType Directory -Force $Destination | Out-Null
    Get-ChildItem -LiteralPath $Source -Force | Where-Object { $_.Name -ne ".git" } | ForEach-Object {
        Copy-Item -Recurse -Force -LiteralPath $_.FullName -Destination $Destination
    }
}

function Download-Required {
    param ([string]$Url, [string]$Destination)
    $Parent = Split-Path -Parent $Destination
    New-Item -ItemType Directory -Force $Parent | Out-Null
    Invoke-WebRequest -Uri $Url -OutFile $Destination
}

function Download-Optional {
    param ([string]$Url, [string]$Destination, [string]$Label)
    $Parent = Split-Path -Parent $Destination
    New-Item -ItemType Directory -Force $Parent | Out-Null
    try {
        Invoke-WebRequest -Uri $Url -OutFile $Destination
        Add-Line "Downloaded optional source: $Label"
    } catch {
        Add-Line "WARN - Optional download failed: $Label"
        Add-Line "WARN - $Url"
        Add-Line "WARN - $($_.Exception.Message)"
    }
}

Add-Line "***** BEGIN CTX AUTHENTIK REFRESH *****"
Add-Line "Started: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')"
Add-Line ""

Remove-Item -Recurse -Force $TempRoot -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Force $TempRoot | Out-Null
New-Item -ItemType Directory -Force $LocalRepo | Out-Null

Add-Line "Cloning Authentik source repository..."
git clone --depth 1 $AuthentikRepo $AuthentikSource
if ($LASTEXITCODE -ne 0) { throw "Git clone failed for Authentik source repository." }

cd $AuthentikSource
$AuthentikCommit = git rev-parse --short HEAD
if ($LASTEXITCODE -ne 0) { throw "Could not read Authentik source commit." }
cd C:\dev

Add-Line "Copying Authentik documentation and source material..."

Copy-PathRequired "$AuthentikSource\website\docs" "$LocalRepo\docs-repo\website-docs"
Copy-PathRequired "$AuthentikSource\website\docs\developer-docs" "$LocalRepo\docs-repo\developer-docs"
Copy-PathOptional "$AuthentikSource\README.md" "$LocalRepo\source\README.md" "README.md"
Copy-PathOptional "$AuthentikSource\AGENTS.md" "$LocalRepo\source\AGENTS.md" "AGENTS.md"
Copy-PathOptional "$AuthentikSource\SECURITY.md" "$LocalRepo\source\SECURITY.md" "SECURITY.md"
Copy-PathOptional "$AuthentikSource\CONTRIBUTING.md" "$LocalRepo\source\CONTRIBUTING.md" "CONTRIBUTING.md"
Copy-PathOptional "$AuthentikSource\schema.yml" "$LocalRepo\api\schema.yml" "schema.yml"
Copy-PathOptional "$AuthentikSource\schema.yaml" "$LocalRepo\api\schema.yaml" "schema.yaml"
Copy-PathOptional "$AuthentikSource\openapi.yml" "$LocalRepo\api\openapi.yml" "openapi.yml"
Copy-PathOptional "$AuthentikSource\openapi.yaml" "$LocalRepo\api\openapi.yaml" "openapi.yaml"
Copy-PathOptional "$AuthentikSource\openapi.json" "$LocalRepo\api\openapi.json" "openapi.json"
Copy-PathOptional "$AuthentikSource\blueprints" "$LocalRepo\blueprints\blueprints" "blueprints"
Copy-PathOptional "$AuthentikSource\lifecycle" "$LocalRepo\deployment\lifecycle" "lifecycle"
Copy-PathOptional "$AuthentikSource\scripts" "$LocalRepo\developer\scripts" "scripts"
Copy-PathOptional "$AuthentikSource\authentik" "$LocalRepo\backend\authentik" "authentik backend"
Copy-PathOptional "$AuthentikSource\web" "$LocalRepo\frontend\web" "web frontend"
Copy-PathOptional "$AuthentikSource\website" "$LocalRepo\frontend\website" "website source"
Copy-PathOptional "$AuthentikSource\docker-compose.yml" "$LocalRepo\deployment\docker-compose.yml" "docker-compose.yml"
Copy-PathOptional "$AuthentikSource\docker-compose.yaml" "$LocalRepo\deployment\docker-compose.yaml" "docker-compose.yaml"
Copy-PathOptional "$AuthentikSource\Dockerfile" "$LocalRepo\deployment\Dockerfile" "Dockerfile"
Copy-PathOptional "$AuthentikSource\Makefile" "$LocalRepo\developer\Makefile" "Makefile"
Copy-PathOptional "$AuthentikSource\package.json" "$LocalRepo\developer\package.json" "package.json"
Copy-PathOptional "$AuthentikSource\pyproject.toml" "$LocalRepo\developer\pyproject.toml" "pyproject.toml"
Copy-PathOptional "$AuthentikSource\poetry.lock" "$LocalRepo\developer\poetry.lock" "poetry.lock"

Add-Line "Downloading selected Authentik website pages..."
Remove-Item -Recurse -Force "$LocalRepo\docs-site" -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Force "$LocalRepo\docs-site" | Out-Null
foreach ($Item in $DocsUrls) {
    Download-Required $Item.Url "$LocalRepo\docs-site\$($Item.File)"
}

Add-Line "Downloading optional Authentik AI-readable documentation files..."
New-Item -ItemType Directory -Force "$LocalRepo\ai" | Out-Null
foreach ($Item in $OptionalTextUrls) {
    Download-Optional $Item.Url "$LocalRepo\ai\$($Item.File)" $Item.Name
}

@"
Official Authentik AI-agent note:
https://goauthentik.io/blog/2026-03-16-a-note-to-ai-agents-about-authentik/

This page is downloaded into:
docs-site\ai-agent-note.html

Optional AI-readable files are attempted from:
https://docs.goauthentik.io/llms.txt
https://docs.goauthentik.io/llms-full.txt

If those files do not exist or are not served by Authentik, the refresh script records a warning and continues.
"@ | Set-Content -Encoding UTF8 "$LocalRepo\ai\ai-agent-source-notes.md"

Add-Line "Cloning Authentik Helm repository..."
git clone --depth 1 $AuthentikHelmRepo $HelmSource
if ($LASTEXITCODE -ne 0) { throw "Git clone failed for Authentik Helm repository." }

cd $HelmSource
$HelmCommit = git rev-parse --short HEAD
if ($LASTEXITCODE -ne 0) { throw "Could not read Authentik Helm commit." }
cd C:\dev

Add-Line "Copying Authentik Helm material..."
Copy-DirectoryContentsRequired $HelmSource "$LocalRepo\helm"

Add-Line "Writing source metadata..."
Remove-Item -Recurse -Force "$LocalRepo\source-metadata" -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Force "$LocalRepo\source-metadata" | Out-Null

@"
Official Authentik documentation URL:
https://docs.goauthentik.io/

Official Authentik developer documentation URL:
https://docs.goauthentik.io/developer-docs/

Official Authentik installation documentation URL:
https://docs.goauthentik.io/install-config/

Official Authentik Docker Compose installation documentation URL:
https://docs.goauthentik.io/install-config/install/docker-compose/

Official Authentik Kubernetes installation documentation URL:
https://docs.goauthentik.io/install-config/install/kubernetes/

Official Authentik configuration documentation URL:
https://docs.goauthentik.io/install-config/configuration/

Official Authentik architecture documentation URL:
https://docs.goauthentik.io/core/architecture/

Official Authentik API documentation URL:
https://api.goauthentik.io/

Official Authentik source repository:
https://github.com/goauthentik/authentik.git

Official Authentik documentation repository path:
https://github.com/goauthentik/authentik/tree/main/website/docs

Official Authentik developer documentation repository path:
https://github.com/goauthentik/authentik/tree/main/website/docs/developer-docs

Official Authentik Helm repository:
https://github.com/goauthentik/helm.git

Official Authentik AI-agent note:
https://goauthentik.io/blog/2026-03-16-a-note-to-ai-agents-about-authentik/
"@ | Set-Content -Encoding UTF8 "$LocalRepo\source-metadata\source-urls.md"

@"
# Authentik Context Repository Source Metadata

This repository contains selected official Authentik documentation and source material for local development, AI-agent reference, AI-assisted development tools, automation, and future MCP/RAG workflows.

## Source Commits

Authentik source repository:
- Repository: https://github.com/goauthentik/authentik.git
- Branch: default
- Commit: $AuthentikCommit

Authentik Helm repository:
- Repository: https://github.com/goauthentik/helm.git
- Branch: default
- Commit: $HelmCommit

## Downloaded Website Pages

- https://docs.goauthentik.io/
- https://docs.goauthentik.io/developer-docs/
- https://docs.goauthentik.io/install-config/
- https://docs.goauthentik.io/install-config/install/docker-compose/
- https://docs.goauthentik.io/install-config/install/kubernetes/
- https://docs.goauthentik.io/install-config/configuration/
- https://docs.goauthentik.io/core/architecture/
- https://api.goauthentik.io/
- https://goauthentik.io/blog/2026-03-16-a-note-to-ai-agents-about-authentik/

## Database Note

The context repository stores official Authentik documentation and source material. If SQLite or MySQL support is not present in the official Authentik source material, this repository should not treat SQLite or MySQL as supported production database choices. PostgreSQL references should be treated as the primary official database path unless later official Authentik documentation says otherwise.

## Refresh Rule

A normal git pull inside this context repository only updates the local copy from the configured GitLab remote. It does not refresh current official Authentik source material. To refresh current official Authentik content, run this repeat-safe PowerShell refresh script.
"@ | Set-Content -Encoding UTF8 "$LocalRepo\source-metadata\refresh-metadata.md"

Add-Line "Preparing Git repository..."
cd $LocalRepo

if (-not (Test-Path ".git")) {
    git init
    if ($LASTEXITCODE -ne 0) { throw "Git init failed." }
    git branch -M main
    if ($LASTEXITCODE -ne 0) { throw "Git branch setup failed." }
}

$ExistingRemote = git remote get-url origin 2>$null
if ([string]::IsNullOrWhiteSpace($ExistingRemote)) {
    git remote add origin $GitLabRemote
    if ($LASTEXITCODE -ne 0) { throw "Git remote add failed." }
} else {
    git remote set-url origin $GitLabRemote
    if ($LASTEXITCODE -ne 0) { throw "Git remote set-url failed." }
    git remote set-url --push origin $GitLabRemote
    if ($LASTEXITCODE -ne 0) { throw "Git remote push-url set failed." }
}

git add -A
if ($LASTEXITCODE -ne 0) { throw "Git add failed." }

$StagedFiles = git diff --cached --name-only

if ([string]::IsNullOrWhiteSpace($StagedFiles)) {
    Add-Line "No Authentik documentation context changes to commit."
} else {
    $CommitBody = @"
Refreshes the local GitLab context copy of selected official Authentik documentation, source, deployment, API, Helm, frontend, backend, blueprint, and AI-agent reference material.

Changed behavior:
- Replaces the stored Authentik documentation context with a fresh official source copy.
- Stores the Authentik website documentation source from website/docs.
- Stores the Authentik developer documentation source from website/docs/developer-docs.
- Stores selected Authentik backend, frontend, deployment, Docker, blueprint, and developer reference material.
- Stores selected Authentik API schema material when available in the source repository.
- Downloads selected Authentik documentation website pages.
- Attempts to download optional Authentik AI-readable documentation files.
- Stores selected Authentik Helm chart material.
- Stores source metadata showing the upstream commits used for this refresh.

Source:
- Documentation URL: https://docs.goauthentik.io/
- Developer documentation URL: https://docs.goauthentik.io/developer-docs/
- Installation documentation URL: https://docs.goauthentik.io/install-config/
- Docker Compose documentation URL: https://docs.goauthentik.io/install-config/install/docker-compose/
- Kubernetes documentation URL: https://docs.goauthentik.io/install-config/install/kubernetes/
- Configuration documentation URL: https://docs.goauthentik.io/install-config/configuration/
- Architecture documentation URL: https://docs.goauthentik.io/core/architecture/
- API documentation URL: https://api.goauthentik.io/
- Authentik source repository: https://github.com/goauthentik/authentik.git at $AuthentikCommit
- Included documentation path: website/docs
- Included developer documentation path: website/docs/developer-docs
- Authentik Helm repository: https://github.com/goauthentik/helm.git at $HelmCommit
- Authentik AI-agent note: https://goauthentik.io/blog/2026-03-16-a-note-to-ai-agents-about-authentik/

Operational context:
- Maintains an updated local and GitLab-hosted documentation context for Authentik.
- Supports SSO, SAML, OIDC, LDAP, identity-provider, Docker, Kubernetes, PostgreSQL, frontend, backend, API, blueprint, and MCP/RAG reference work.
- Supports local review, AI-assisted development tool access, future documentation indexing, and future MCP/RAG workflows.
- Avoids depending only on live website lookup when AI agents need stable local Authentik reference material.

Validation performed:
- Cloned the Authentik source repository.
- Verified required documentation source paths before copying.
- Copied selected source folders and files into the context repository.
- Downloaded selected official Authentik documentation pages.
- Cloned the Authentik Helm repository.
- Staged only the resulting context-repository changes.
"@

    git commit -m "Update Authentik documentation context" -m "$CommitBody"
    if ($LASTEXITCODE -ne 0) { throw "Git commit failed." }

    git push origin main
    if ($LASTEXITCODE -ne 0) { throw "Git push failed." }

    Add-Line "Authentik documentation context committed and pushed to GitLab."
}

Add-Line ""
Add-Line "File count summary:"
Add-Line "docs-site files: $(Count-Files "$LocalRepo\docs-site")"
Add-Line "docs-repo files: $(Count-Files "$LocalRepo\docs-repo")"
Add-Line "api files: $(Count-Files "$LocalRepo\api")"
Add-Line "source files: $(Count-Files "$LocalRepo\source")"
Add-Line "helm files: $(Count-Files "$LocalRepo\helm")"
Add-Line "deployment files: $(Count-Files "$LocalRepo\deployment")"
Add-Line "developer files: $(Count-Files "$LocalRepo\developer")"
Add-Line "frontend files: $(Count-Files "$LocalRepo\frontend")"
Add-Line "backend files: $(Count-Files "$LocalRepo\backend")"
Add-Line "blueprints files: $(Count-Files "$LocalRepo\blueprints")"
Add-Line "ai files: $(Count-Files "$LocalRepo\ai")"
Add-Line "source-metadata files: $(Count-Files "$LocalRepo\source-metadata")"
Add-Line "total ctx-authentik files: $(Count-Files "$LocalRepo")"

Add-Line ""
Add-Line "Git status:"
$GitStatus = git status 2>&1
foreach ($Line in $GitStatus) {
    Add-Line $Line
}

cd C:\dev
Remove-Item -Recurse -Force $TempRoot -ErrorAction SilentlyContinue

Add-Line ""
Add-Line "Temporary source folder removed: $TempRoot"
Add-Line "Finished: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')"
Add-Line "Report file: $ReportPath"
Add-Line "***** END CTX AUTHENTIK REFRESH *****"

$ReportLines | Set-Content -Encoding UTF8 $ReportPath

6. Expected Result

If the official Authentik context material changed, the script should create and push a new commit with this subject:

Update Authentik documentation context

If the official Authentik context material did not change, the script should print:

No Authentik documentation context changes to commit.

If a commit is created, the script pushes it to:

git@gitlab-sudostac:sudostac/ctx-authentik.git

In either case, the final git status should show the current state of the local context repository.

A successful final Git status should look like this:

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

The script also writes a refresh report to:

C:\dev\ctx-authentik-refresh-report.txt

A successful refresh should show nonzero file counts for the main folders that were populated during the initial refresh:

docs-site
docs-repo
api
source
helm
deployment
developer
frontend
backend
blueprints
ai
source-metadata

A prior successful local refresh produced about 10,000 files in C:\dev\ctx-authentik. The exact number can change when official Authentik sources change.

The optional llms.txt and llms-full.txt downloads may fail with 404. That is acceptable unless Authentik later publishes those files and the script still cannot download them.

7. AI Agent Instructions

When using this repository for Authentik-related work, AI agents should treat C:\dev\ctx-authentik as the local Authentik documentation and source-material context.

AI agents should use the local context repository as the first reference source for work involving company single sign-on, SAML, OIDC, LDAP, identity-provider setup, Docker deployment, Kubernetes deployment, Helm deployment, PostgreSQL-backed operation, API usage, frontend reference, backend reference, blueprints, automation, or MCP/RAG workflows.

The Authentik developer website, Authentik API documentation, or public upstream Authentik source repositories may still be used when the local context appears incomplete, stale, missing, or insufficient for a specific implementation question.

Do not assume that a normal git pull inside C:\dev\ctx-authentik refreshes the repository from Authentik's official sources. It only refreshes the local copy from the Just Headlines GitLab context repository. To update from official Authentik sources, run the PowerShell refresh script in this document.

Do not treat SQLite or MySQL as supported Authentik production database options unless official Authentik documentation or source material confirms support. PostgreSQL should be treated as the primary official database path unless later official Authentik documentation says otherwise.

8. Human Operator Notes

This script is safe to run repeatedly. It replaces the stored Authentik context content with a fresh copy of the selected official source material.

The script does not store SSH keys, passphrases, API keys, Authentik secrets, Authentik bootstrap tokens, Authentik secret keys, PostgreSQL credentials, SMTP credentials, GitLab tokens, company secrets, service secrets, environment files, or application configuration secrets.

Git authentication is handled by the existing local SSH configuration on the operator's computer.

If GitLab asks for the SSH key passphrase, enter the passphrase for the local SSH key used with the gitlab-sudostac SSH configuration.

If GitLab does not ask for the SSH key passphrase, that does not automatically mean the push failed. It may mean that no commit was created, the SSH key is already unlocked in the current session, or the system has cached the SSH key.

If GitLab blocks a push because the branch is protected, check the GitLab branch protection settings for the ctx-authentik repository and confirm that normal pushes to main are permitted for the account performing this task.

The temporary source checkout folder is:

C:\dev\_authentik-source

The script removes that folder at the end of the run. It is not part of the permanent context repository.

9. Validation Checklist

After running the script, confirm the following:

  1. C:\dev\ctx-authentik\docs-site exists.
  2. C:\dev\ctx-authentik\docs-site contains downloaded Authentik website pages.
  3. C:\dev\ctx-authentik\docs-repo\website-docs exists.
  4. C:\dev\ctx-authentik\docs-repo\developer-docs exists.
  5. C:\dev\ctx-authentik\api exists.
  6. C:\dev\ctx-authentik\api contains selected Authentik API schema material when available.
  7. C:\dev\ctx-authentik\source exists.
  8. C:\dev\ctx-authentik\helm exists.
  9. C:\dev\ctx-authentik\deployment exists.
  10. C:\dev\ctx-authentik\developer exists.
  11. C:\dev\ctx-authentik\frontend exists.
  12. C:\dev\ctx-authentik\backend exists.
  13. C:\dev\ctx-authentik\blueprints exists.
  14. C:\dev\ctx-authentik\ai exists.
  15. C:\dev\ctx-authentik\source-metadata\source-urls.md exists.
  16. C:\dev\ctx-authentik\source-metadata\refresh-metadata.md exists.
  17. The local context repository contains selected official Authentik documentation, source, API, deployment, Helm, frontend, backend, blueprint, and AI-agent reference material.
  18. git status does not show unexpected staged changes.
  19. If changes were found, a commit was created.
  20. If a commit was created, it was pushed to git@gitlab-sudostac:sudostac/ctx-authentik.git.
  21. The final Git status says the local branch is up to date with origin/main.
  22. The temporary folder C:\dev\_authentik-source was removed.
  23. The refresh report exists at C:\dev\ctx-authentik-refresh-report.txt.

The optional docs.goauthentik.io/llms.txt and docs.goauthentik.io/llms-full.txt files may be absent. If those URLs return 404, that is a warning, not a failure.

10. Related Repositories

This document concerns the Authentik documentation context repository only:

C:\dev\ctx-authentik

It does not define the Just Headlines Authentik implementation itself. Production implementation belongs in the applicable Just Headlines application, admin, site, or server repository.

Related implementation repositories may include:

C:\dev\admin
C:\dev\site
C:\dev\news
C:\dev\server

The Authentik context repository is a reference repository. It stores selected official Authentik documentation and source material for local review, AI-assisted development, automation, and future MCP/RAG workflows. It does not store Authentik secrets, API tokens, bootstrap credentials, secret keys, PostgreSQL credentials, SMTP credentials, environment files, or production configuration secrets.