Antora GitHub Deploy Template

Use this template to add Antora docs build and GitHub Pages deploy to a repository.

What you get

• Build: Antora runs on push/PR when docs/**, antora-playbook.yml, or the workflow file change.

• Deploy: On main, the built site is deployed to GitHub Pages (branch gh-pages or Pages environment).

• Extension refresh: Workflow can be triggered by repository_dispatch (e.g. when a shared UI bundle updates).

Quick setup

1. Copy .github/workflows/docs.yml into your repo’s .github/workflows/.

2. Copy antora-playbook.yml to your repo root.

3. In the playbook, set site.title, site.url, and start_page to match your project.

4. Ensure you have a docs/ folder with an antora.yml and at least one module (e.g. docs/modules/ROOT/pages/index.adoc).

5. In the repo: Settings → Pages: set source to GitHub Actions (or Deploy from a branch with branch gh-pages if you use that variant).

Requirements

• Node 20 and pnpm (workflow installs pnpm).

• Repo Settings → Pages: either Deploy from a branch (branch gh-pages, root) or GitHub Actions (this template uses upload-pages-artifact + deploy-pages; for Actions-based deployment the source must be GitHub Actions).

Private content sources (multi-repo, same org)

If your playbook pulls from other private repos in the org, GITHUB_TOKEN is not enough to clone them. Add a PAT (e.g. ANTORA_READ_TOKEN) and uncomment the "Configure git for private content sources" step in the workflow. Full explanation: docs/modules/publishing/pages/antora-deployment.adoc — see "Private repos: GITHUB_TOKEN vs PAT".

Custom domain

• In Settings → Pages, set Custom domain to your domain.

• To add a CNAME file to the site root, use a supplemental UI and list the file in supplemental-ui/ui.yml under static_files.

More

Full deployment guide (including private repos and PAT): antora-deployment.adoc in the devcentr repo.