Git Authentication for Antora

This guide explains how to configure Git authentication for Antora deployments to access private repositories.

Overview

Antora needs to clone Git repositories to build documentation. For private repositories, you need to provide authentication credentials. There are two main approaches:

Method Best For Notes

Method	Best For	Notes
HTTPS + Token	Simple setups, CI/CD	Uses Personal Access Token via `GIT_CREDENTIALS`
SSH Key	Production, multiple repos	Uses deploy keys or user SSH keys

HTTPS + Token

Simple setups, CI/CD

Uses Personal Access Token via GIT_CREDENTIALS

SSH Key

Production, multiple repos

Uses deploy keys or user SSH keys

HTTPS Authentication (Tokens)

Create a GitHub Fine-Grained Token

Sign in to GitHub: Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token
Give the token a descriptive name (e.g., antora-readonly-YYYYMMDD)
Select the resource owner (your user or organization)
Under Repositories, select specific repository(ies) - avoid "All repositories"
Under Permissions set:
- Repository → Contents: Read
- Repository → Metadata: Read (optional)
- Do NOT grant write/delete permissions
Set an expiration (30-90 days recommended)
Generate and copy the token immediately

For classic PATs, use minimal repo scope. Fine-grained tokens are safer.

Format the Token for Antora

Antora accepts credentials in git credential format:

Token-only (recommended)

https://TOKEN:@github.com

Username + token

https://USERNAME:[email protected]

Test the Token Locally

# Replace TOKEN, ORG, and REPO
git ls-remote https://TOKEN:@github.com/ORG/REPO.git

If successful, you’ll see a list of refs (branches, tags).

Create the Kubernetes Secret

Do not commit real tokens to Git. These examples avoid leaving tokens in shell history.

PowerShell - from environment variable

# Set token in environment for this session
$env:GIT_CREDENTIALS = 'https://TOKEN:@github.com'

# Create or update the Secret (idempotent)
kubectl create secret generic git-credentials `
  --from-literal=GIT_CREDENTIALS="$env:GIT_CREDENTIALS" `
  -n <namespace> --dry-run=client -o yaml | kubectl apply -f -

# Clear the environment variable
Remove-Item Env:GIT_CREDENTIALS

PowerShell - from temporary file

Set-Content -Path C:\Temp\git-cred.txt -Value "https://TOKEN:@github.com"
kubectl create secret generic git-credentials `
  --from-file=GIT_CREDENTIALS=C:\Temp\git-cred.txt `
  -n <namespace> --dry-run=client -o yaml | kubectl apply -f -
Remove-Item C:\Temp\git-cred.txt

POSIX (Linux/macOS)

export GIT_CREDENTIALS='https://TOKEN:@github.com'
kubectl create secret generic git-credentials \
  --from-literal=GIT_CREDENTIALS="$GIT_CREDENTIALS" \
  -n <namespace> --dry-run=client -o yaml | kubectl apply -f -
unset GIT_CREDENTIALS

CI/CD Integration

Store the token in your CI provider’s secrets and inject at runtime.

GitHub Actions example

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Create git-credentials secret
        env:
          GIT_CREDENTIALS: ${{ secrets.GIT_CREDENTIALS }}
        run: |
          kubectl create secret generic git-credentials \
            --from-literal=GIT_CREDENTIALS="$GIT_CREDENTIALS" \
            -n <namespace> --dry-run=client -o yaml | kubectl apply -f -
      - name: Deploy
        run: make deploy

SSH Authentication (Deploy Keys)

Prerequisites

kubectl configured for your cluster
ssh-keygen available locally
Optional: GITHUB_TOKEN for automated deploy key upload

Quick Setup with Helper Script

If your project includes a helper script:

# Generate keypair and create/update secret
# Optionally set GITHUB_* vars to upload as deploy key
GITHUB_USERNAME=youruser GITHUB_REPO=your-repo GITHUB_TOKEN=ghp_xxx \
  ./scripts/create-ssh-key.sh <namespace>

Manual Setup

Generate SSH keypair:

ssh-keygen -t ed25519 -C "deploy-key@yourdomain" -f ./git_deploy_key -N ""

Create Kubernetes Secret:

kubectl create secret generic git-ssh-key \
  --from-file=id_rsa=./git_deploy_key \
  --from-file=id_rsa.pub=./git_deploy_key.pub \
  -n <namespace>

Upload public key to GitHub:
- Repository deploy key: Repository → Settings → Deploy keys → Add deploy key
- User SSH key: GitHub → Settings → SSH and GPG keys → New SSH key

Verify Secret

kubectl get secret git-ssh-key -n <namespace>

# View public key
kubectl get secret git-ssh-key -n <namespace> \
  -o jsonpath='{.data.id_rsa\.pub}' | base64 --decode

SSH Configuration

Ensure your deployment mounts an SSH config that points to the key:

Example ssh-config ConfigMap

Host github.com
  IdentityFile /root/.ssh/id_rsa
  StrictHostKeyChecking no

Repository URL Format

Use SSH URLs in your playbook when using SSH authentication:

content:
  sources:
    - url: [email protected]:org/repo.git  # SSH format
      branches: main

Security Best Practices

For HTTPS Tokens

Use fine-grained tokens limited to specific repositories
Grant only Contents: Read permission
Set short expiry (30-90 days) and rotate frequently
Prefer GitHub App tokens for better security
Never commit tokens to Git

For SSH Keys

Use repository deploy keys for single-repo access
Use read-only deploy keys (no write access)
Rotate keys periodically
Remove unused keys from GitHub and cluster

General

Use SealedSecrets, ExternalSecrets, or cloud secret managers for GitOps
Restrict Kubernetes RBAC so only the deployment’s service account can read secrets
Revoke credentials immediately if compromised
Audit credential usage regularly

Troubleshooting

HTTPS Authentication Fails

Verify token hasn’t expired
Check token has correct repository permissions
Ensure GIT_CREDENTIALS format is correct
Test token locally with git ls-remote

SSH Authentication Fails

Verify public key is uploaded to GitHub
Check repository URL uses SSH format ([email protected]:…)
Ensure SSH config is correctly mounted in init container
Check key file permissions (should be restrictive)

Permission Denied

For HTTPS: Regenerate token with correct permissions
For SSH: Verify deploy key is added to correct repository
Check Kubernetes Secret exists in correct namespace

Clearing Credentials

PowerShell

Remove-Item Env:GIT_CREDENTIALS

POSIX

unset GIT_CREDENTIALS