At Decodable we migrated our docs platform onto Antora. I wrote previously about my escapades in getting cross-repository authentication working using Private Access Tokens (PAT). These are fine for just a single user, but they’re tied to that user, which isn’t a good practice for deployment in this case.

In this article I’ll show how to use GitHub Apps and Installation Access Tokens (IAT) instead, and go into some detail on how we’ve deployed Antora. Our GitHub repositories are private which makes it extra-gnarly.

Overview 🔗

The docs platform is built on Antora, which generates a static site. This is hosted on Cloudflare Pages.

  • The docs content is on our private code_repo GitHub repo.

  • The Antora platform configuration and build scripts is held on the private docs-platform GitHub repo.

  • The user interface of the documentation site is taken mostly from the vanilla antora-ui-default, with some small tweaks in this repo.

GitHub Actions is used to trigger, build, and deploy the docs site.

Diagram of what content is where

Why Two Repositories? 🔗

One of the brilliant things that Antora supports is the ability to pull in the docs content from a git repository. This can be the same as the one that is hosting the Antora configuration—or as in our case, the repository that holds the code for which the documentation is written.

This means that when a new feature is released the code and the docs can be kept in lock-step, both deploy and rollback if necessary.

You can also pull in code from multiple repositories—Antora is super-flexible like this, and supports various styles of code organisation and control.

Build and Deploy 🔗

The docs content lives in code_repo under /docs. The actual build and deploy happens on the docs-platform repository, and as a result the process is more complicated than it would be in a single repository.

Diagram of the build and deploy process

  • For docs changes, when a change is pushed to main on code_repo that includes a file under /docs/, the docs-trigger-deploy.yaml workflow runs. This in turn triggers the cloudflare.yaml workflow on the docs-platform repository.

  • For a platform change the cloudflare.yaml workflow on the docs-platform repository will run directly.

PR Preview builds 🔗

Not everyone writes perfect docs PRs. I has ben knowwn to right mistaks with speling and grammer, and that’s before you get onto the correctness of documentation which in software is particularly important to be precise and accurate.

By being able to create a preview of PRs as they are raised it’s easy to seek review from colleagues. However readable Asciidoc might be as a markup language, it’s not going to be more readable than the parsed and rendered web page with its links and images in all their glory. The same goes for PRs against the Antora platform configuration itself—whether customising the skin, tweaking a config—all these things benefit from being able to see them in action before hitting the deploy button.

Thus, when a PR is raised against main on the docs-platform or code_repo repos (and includes a file under /docs/ in the case of the code_repo repo) a preview docs site is built and deployed to a unique URL.

Diagram of the Preview build and deploy process

The build process does some additional things that the production one doesn’t:

  1. The trigger action passes details about the source PR as inputs to the docs-platform workflow

  2. The preview-cloudflare.yaml workflow on the docs-platform modifies the Antora playbook to use the source branch of the PR on the code-repo repository (instead of main)

    - name: If not a platform PR, set the branch of the source repo for antora content
if: github.event_name != 'pull_request'
id: override_antora_playbook_yml
run: |
    sed -i '7s/main/${{ inputs.pr_branch }}/' antora-playbook.yml

  3. It overlays a message on the preview site indicating the PR with which that it is associated.

    Screenshot of a preview docs deployment with a PR message overlaid

  4. Once deployed, it updates the originating PR with the URL of the preview site.

    Screenshot of a PR showing the preview URL

Security and Configuration in GitHub Workflows 🔗

There are two areas of security that need to be correctly configured:

  • Cloudflare

  • GitHub Intra-Repository interactions

Overview of interactions requiring additional authorisation steps

Cloudflare 🔗

This one is fairly simple. Store these in the docs-platform repository settings:

  • Repository secret: CLOUDFLARE_API_TOKEN

  • Repository variable: CLOUDFLARE_ACCOUNT_ID

The GitHub Action then uses these when deploying the site to Cloudflare.

GitHub Intra-Repository Interactions 🔗

This is more complicated since the two repositories are private. The following interactions need authorisation beyond what happens by default within a GitHub Workflow:

  1. Actions running in code_repo repo

    • Triggering a workflow in docs-platform from code_repo workflow

  2. Actions running in docs-platform repo

    • When Antora builds the docs site it needs to clone the code_repo repository

    • Updating the PR issue on code_repo that triggered the preview build

How It Works 🔗

Detail of how security works for interactions requiring additional authorisation steps

The auth for these is handled using a custom GitHub App (Antora Docs Build Bot) installation on each repository.

The auth can also be done using Personal Access Tokens (PAT) but this would then be tied to a particular user’s account and is therefore not suitable for an organisation.

When each workflow runs its first step is to use the create-github-app-token action to generate a GitHub App installation access token (IAT). This is valid for the session only, and then provides the authorisation for the intra-repository actions.

The IAT is used in two ways:

  1. From the github-script action via the optional github-token parameter. This is used for two different interactions:

    1. To trigger the docs-platform build and deploy workflows from the code_repo repository.

    2. When the Preview workflow adds a comment to the PR that triggered it. If this PR came from the docs-platform repository (i.e. local to the action) then no additional auth is needed, but to comment on the code_repo repository it is.

  2. When Antora builds the site it clones the code_repo repository. Since this is run from a different repository the default authentication that would apply to an action running in the same repository doesn’t exist. Antora performs the authentication using the pre-specified GIT_CREDENTIALS environment variable. This must follow the following syntax:

    https://x-access-token:$IAT_TOKEN@github.com

Setting up the GitHub App 🔗

This needs to be done by a user with Owner rights on the GitHub organisation. The App has to be created in the GitHub organisation, and from there is installed to the two repositories. The GitHub docs detail the process - below is a short set of notes covering the essential settings:

  1. From your GitHub profile page set the settings context to that of your organisation, and then click on Developer settings (at the very bottom of the page) and then GitHub Apps

  2. Click on New GitHub App.

    1. Give the new app a name (e.g. Antora Docs Build Bot)

    2. Set the Homepage URL to that of docs-platform repo

    3. Disable Webhook

  3. Under Repository permissions set the following

    Actions

    Read/Write

    Contents

    Read

    Issues

    Read/Write

    Metadata

    Read

    Pull Requests

    Read/Write

  4. Click Create GitHub App

  5. Make a note of the App ID. You’ll store this later on as a repository secret.

  6. Scroll down to Private keys and click on Generate a private key. Save the resulting .pem file locally.

  7. Click Install App

    1. Install it to the account under which the the docs-platform and code_repo repos are (i.e. decodeableco).

    2. When prompted which repositories it should be installed to, select Only select repositories and choose docs-platform and code_repo

Configuring Repository Secrets and Variables 🔗

As a repo admin, on the code_repo repository add the following repository secrets:

Key Value

DOCS_APP_ID

GitHub App ID

DOCS_APP_PRIVATE_KEY

The full text of the .pem, including the BEGIN RSA PRIVATE KEY and END RSA PRIVATE KEY header and footer

As a repo admin, on the docs-platform add the following repository secrets

Key Value

DOCS_APP_ID

GitHub App ID

DOCS_APP_PRIVATE_KEY

The full text of the .pem, including the BEGIN RSA PRIVATE KEY and END RSA PRIVATE KEY header and footer

CLOUDFLARE_API_TOKEN

API token from Cloudflare

and the following repository variable

Key Value

CLOUDFLARE_ACCOUNT_ID

Cloudflare Account ID

Addendum: Deploying Antora using AWS Amplify and GitHub Workflows 🔗

For $REASONS we ended up using AWS Amplify. You can find the build scripts here. There are three scripts:

  1. Preview deployment (triggered by a PR creation)

  2. Live deployment (triggered by a merge to main)

  3. Teardown preview (triggered by a PR being closed)