Workflow examples (GitHub Actions)

These snippets are adapted from the legacy antora-github-action examples. They use antora-supplemental/antora-build-action@v2 (Antora Site Builder). Copy a file into .github/workflows/ in your own repository and adjust secrets, paths, and deploy steps.

Files also live under docs/content/modules/ROOT/partials/examples/ in this repo for editing with the YAML workflow schema (see root .vscode/settings.json).

Basic public repository

Single public repo; optional PR artifact and peaceiris deploy on main.

# =============================================================================
# Example: Basic Public Repository
# =============================================================================
# The simplest case - building docs from a single public repository.
# No authentication required.
# =============================================================================

name: Build Documentation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Build Antora site
        uses: antora-supplemental/antora-build-action@v2
        with:
          playbook: antora-playbook.yml

      # For pull requests, just upload as artifact for review
      - name: Upload site artifact
        if: github.event_name == 'pull_request'
        uses: actions/upload-artifact@v4
        with:
          name: documentation-preview
          path: build/site
          retention-days: 7

      # For main branch, deploy to GitHub Pages
      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build/site

With Antora extensions

Playbook must list extensions (Lunr, Kroki, etc.); see comments in the partial.

# =============================================================================
# Example: With Extensions (Search, Diagrams, PDF)
# =============================================================================
# Using Antora extensions for enhanced functionality:
# - Lunr search for full-text search
# - Kroki for diagrams (PlantUML, Mermaid, etc.)
# - PDF generation (optional)
#
# Prerequisites:
# Configure extensions in your playbook:
#
# ```yaml
# antora:
#   extensions:
#     - '@antora/lunr-extension'
#
# asciidoc:
#   extensions:
#     - 'asciidoctor-kroki'
#   attributes:
#     kroki-server-url: https://kroki.io
#     # Or self-hosted: kroki-server-url: https://kroki.internal.company.com
# ```
# =============================================================================

name: Build Documentation with Extensions

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build Antora site with extensions
        uses: antora-supplemental/antora-build-action@v2
        with:
          playbook: antora-playbook.yml
          # Optional: if your content repos are private
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build/site

Versioned documentation

Branch-based triggers with path filters. For tag-only builds, add a second workflow with on.push.tags.

# =============================================================================
# Example: Versioned Documentation
# =============================================================================
# Building documentation for multiple versions of a project using Git branches.
# Antora automatically creates version selectors in the generated site.
#
# Corresponding playbook:
# ```yaml
# content:
#   sources:
#     - url: https://github.com/your-org/your-project.git
#       branches: [main, 'v1.*', 'v2.*', 'v3.*']
#       tags: ['v*']  # Optional: include tagged releases
#       start_path: docs
#
# site:
#   title: Your Project Documentation
#   start_page: your-component::index.adoc
# ```
#
# To also run when you push version tags, add a separate workflow with only:
#   on: { push: { tags: ['v*'] } }
# (GitHub Actions does not allow two `push:` keys in one file.)
# =============================================================================

name: Build Versioned Documentation

on:
  push:
    branches: [main, 'v*']
    paths:
      - 'docs/**'
      - 'antora-playbook.yml'
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Build versioned Antora site
        uses: antora-supplemental/antora-build-action@v2
        with:
          playbook: antora-playbook.yml
          fetch: 'true'
          log_level: 'info'
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build/site
          keep_files: true

Private multi-repository (GitHub)

git_credentials for a PAT that can read all content.sources repos; GitHub Pages via upload-pages-artifact + deploy-pages.

# =============================================================================
# Example: Private Multi-Repository Setup
# =============================================================================
# Aggregating documentation from multiple private repositories within
# a single GitHub organization.
#
# Prerequisites:
# 1. Create a PAT with 'repo' scope (classic) or 'Contents: Read' (fine-grained)
#    that has access to all content source repositories
# 2. Add the PAT as a repository secret named 'DOCS_PAT'
# =============================================================================

name: Build Multi-Repo Documentation

on:
  push:
    branches: [main]
  repository_dispatch:
    types: [docs-updated]
  schedule:
    - cron: '0 */4 * * *'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout documentation repo
        uses: actions/checkout@v4

      - name: Build Antora site
        id: antora
        uses: antora-supplemental/antora-build-action@v2
        with:
          playbook: antora-playbook.yml
          git_credentials: |
            https://x-access-token:${{ secrets.DOCS_PAT }}@github.com
          fetch: 'true'
          log_level: 'info'

      - name: Configure Pages
        uses: actions/configure-pages@v4

      - name: Upload to GitHub Pages
        uses: actions/upload-pages-artifact@v3
        with:
          path: ${{ steps.antora.outputs.site-path }}

  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Cross-platform (GitHub + GitLab)

Multiple credential lines for different hosts.

# =============================================================================
# Example: Cross-Platform (GitHub + GitLab)
# =============================================================================
# Aggregating documentation from repositories hosted on both GitHub and GitLab.
# This is common in enterprise environments using GitLab internally.
#
# Prerequisites:
# 1. GitHub PAT with 'repo' scope for private GitHub repos
# 2. GitLab PAT with 'read_repository' scope
# 3. Add both as repository secrets: GITHUB_PAT, GITLAB_PAT
#
# Corresponding playbook:
# ```yaml
# content:
#   sources:
#     - url: https://github.com/public-org/open-source-project.git
#       branches: [main]
#     - url: https://github.com/your-org/internal-api.git
#       branches: [main]
#     - url: https://gitlab.com/your-group/backend-services.git
#       branches: [main]
#     - url: https://gitlab.internal.company.com/platform/core.git
#       branches: [main]
# ```
# =============================================================================

name: Build Cross-Platform Documentation

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 6 * * *'
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build Antora site
        uses: antora-supplemental/antora-build-action@v2
        with:
          playbook: antora-playbook.yml
          git_credentials: |
            https://x-access-token:${{ secrets.GITHUB_PAT }}@github.com
            https://oauth2:${{ secrets.GITLAB_PAT }}@gitlab.com
            https://oauth2:${{ secrets.INTERNAL_GITLAB_PAT }}@gitlab.internal.company.com

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build/site
          cname: docs.company.com

Netlify

Build with the action, then deploy the output directory with Netlify’s action.

# =============================================================================
# Example: Deploy to Netlify
# =============================================================================
# Alternative deployment to Netlify instead of GitHub Pages.
# Netlify offers features like:
# - Deploy previews for PRs
# - Split testing
# - Form handling
# - Edge functions
#
# Prerequisites:
# 1. Create a Netlify site
# 2. Get your NETLIFY_AUTH_TOKEN from Netlify user settings
# 3. Get your NETLIFY_SITE_ID from site settings
# 4. Add both as repository secrets
# =============================================================================

name: Build and Deploy to Netlify

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build Antora site
        uses: antora-supplemental/antora-build-action@v2
        with:
          playbook: antora-playbook.yml
          git_credentials: |
            https://x-access-token:${{ secrets.DOCS_PAT }}@github.com

      - name: Deploy to Netlify
        uses: nwtgck/actions-netlify@v3
        with:
          publish-dir: './build/site'
          production-branch: main
          github-token: ${{ secrets.GITHUB_TOKEN }}
          deploy-message: "Deploy from GitHub Actions - ${{ github.sha }}"
          enable-pull-request-comment: true
          enable-commit-comment: false
          overwrites-pull-request-comment: true
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}