Antora Workflow Templates

Starter workflow templates for building Antora documentation sites with GitHub Actions.

Contents

• Overview
• Prerequisites
• Quick Start
• Credential Setup for Private Repositories
  • Step 1: Create a Personal Access Token (PAT)
  • Step 2: Add Token as Repository Secret
  • Step 3: Reference in Workflow
• Multi-Host Credentials (GitHub + GitLab)
• Workflow Comparison
• Related Resources
• License
• Disclaimer

Overview

This repository provides two equivalent workflows for building and deploying Antora documentation to GitHub Pages:

File	Approach	Best For
diy-workflow.yml	DIY (all steps visible)	Understanding what’s happening, full control
action-workflow.yml	Reusable action	Shorter config, standard interface

Both produce identical results. Choose based on your preference for transparency vs. brevity.

Prerequisites

Your repository needs a package.json with Antora as a local dependency:

{
  "devDependencies": {
    "antora": "^3.1"
  }
}

The antora package bundles both the CLI and site generator. Alternatively, you can install them separately:

{
  "devDependencies": {
    "@antora/cli": "^3.1",
    "@antora/site-generator": "^3.1"
  }
}

Run npm install or pnpm install to generate a lockfile.

Warning

Do not use global installation (npm install -g @antora/cli). Global installs lead to unreproducible builds because "latest" resolves to whatever version exists at build time, and there’s no lockfile to ensure consistency. The Antora documentation recommends local installation: "Installing Antora locally makes it easier to manage the version of Antora and ensures that the version of Antora matches the version for which the playbook was made."

Quick Start

1. Ensure you have a package.json with Antora dependencies (see above)

2. Copy one of the workflow files to your repo’s .github/workflows/ directory

3. Rename it (e.g., docs.yml or build-and-deploy.yml)

4. Update the playbook path if yours isn’t antora-playbook.yml

5. If you have private content repos, set up credentials (see below)

6. Commit and push to trigger the workflow

Credential Setup for Private Repositories

If your Antora playbook references private Git repositories, you need to provide credentials.

Step 1: Create a Personal Access Token (PAT)

1. Go to GitHub Token Settings

2. Click "Generate new token" (classic)

3. Give it a descriptive name like "Antora Docs Build"

4. Select the repo scope (required for private repos)

5. Click "Generate token" and copy the token

Step 2: Add Token as Repository Secret

1. Go to your documentation repo on GitHub

2. Settings → Secrets and variables → Actions

3. Click "New repository secret"

4. Name it (e.g., DOCS_PAT or MY_GITHUB_PAT)

5. Paste your token as the value

6. Click "Add secret"

Step 3: Reference in Workflow

In diy-workflow.yml, update the GIT_CREDENTIALS environment variable:

env:
  GIT_CREDENTIALS: "https://x-access-token:${{ secrets.DOCS_PAT }}@github.com"

In action-workflow.yml, update the git_credentials input:

with:
  git_credentials: "https://x-access-token:${{ secrets.DOCS_PAT }}@github.com"

Multi-Host Credentials (GitHub + GitLab)

If your playbook pulls content from both GitHub and GitLab:

# DIY workflow
env:
  GIT_CREDENTIALS: |
    https://x-access-token:${{ secrets.GITHUB_PAT }}@github.com
    https://oauth2:${{ secrets.GITLAB_PAT }}@gitlab.com

# Action workflow
with:
  git_credentials: |
    https://x-access-token:${{ secrets.GITHUB_PAT }}@github.com
    https://oauth2:${{ secrets.GITLAB_PAT }}@gitlab.com

Workflow Comparison

The table below shows how the DIY workflow steps map to action inputs:

What It Does	DIY Workflow	Action Input
Choose Node.js version	actions/setup-node with node-version	node_version: '20'
Choose Antora version	npm install @antora/cli@X.X.X	antora_version: '3.1.7'
Install extensions	npm install -g @antora/lunr-extension	extensions: '@antora/lunr-extension'
Provide credentials	GIT_CREDENTIALS env var	git_credentials or github_token
Specify playbook	Argument to antora command	playbook: 'antora-playbook.yml'
Fetch latest content	--fetch flag	fetch: 'true'
Set log verbosity	--log-level flag	log_level: 'info'
Build in subdirectory	working-directory: on run step	working_directory: 'docs'

Related Resources

• antora-supplemental/antora-build-action — The reusable action used by action-workflow.yml

• Antora: Publish to GitHub Pages — Official documentation

• Antora: Private Repository Authentication — Credential formats

License

MIT License. See LICENSE file.

Disclaimer

This is a community-maintained project, not officially affiliated with Antora. The official Antora project is at https://gitlab.com/antora/antora.