Private Repository Authentication

In order for Antora to access private repositories, you must supply it with authentication credentials for any private repository URL you use in your playbook. These credentials can be externalized so they don’t have to be hard-coded into the playbook. This page covers various ways you can pass the credentials to Antora, including the built-in git credential store, a custom credential store, and even your own credential manager.

Let’s start by looking at the authentication credential types Antora accepts by default, then move on to how to set them up and put them to use.

Credential types

Antora can authenticate with private repositories using HTTP Basic authentication. HTTP Basic authentication requires sending credentials to the server (over HTTPS) to verify your identity. Authentication credentials consist of either a username/password pair or an access (OAuth 2.0) token.

The username/password pair is usually what you use to log in to the service (GitHub, GitLab, etc.) where the repository is hosted. If the username or password contains characters which have special meaning in a URL, such as /, #, and :, these characters must be URL encoded (i.e., percent encoded) so they aren’t misinterpreted by the URL parser. Keep in mind that while some git hosts support this means of authentication, others do not. You may have better luck using an access token.

When two-factor authentication (2FA) is enabled on your account, you can’t use the username/password pair to authenticate with a private repository. You’ll receive the error 401 HTTP Basic: Access Denied when you try.

Regardless of the reason, if the git host does not allow you to authenticate using a username/password pair, you’ll need to use an access token instead.

There are two types of access tokens: personal access tokens and deploy tokens.

A personal access token is bound to the user and grants access to any private repository that your account can access (subject to the scope settings of the token itself).
A deploy token (not a deploy key) is bound to the project (i.e., repository) and grants access to a single repository (subject to the scope settings on the token itself).

Deploy keys cannot be used with Antora since they require the use of SSH authentication, which the git client in Antora does not support.

You typically use a single personal access token on your own machine and one or more deploy tokens on a CI server.

GitHub

To create an access token for GitHub, see Creating a personal access token (PAT) for the command line. GitHub has two types of access tokens, fine-grained and classic. Both are supported by Antora, though the fine-grained token must be granted the Contents permission to the repositories you want to use.

GitHub also supports Installation Access Tokens (IAT), which are bound to an application instead of user. These access tokens are more suitable for use in an organization.

GitHub does not support deploy tokens at this time.

To learn more about how to create access tokens for use with GitHub, refer to the articles Antora with GitHub PAT and Antora with GitHub IAT.

GitLab

To create an access token for GitLab, see Personal Access Tokens and Deploy Tokens.

Bitbucket

For Bitbucket, you’ll need to create an app password with read access to repositories. An app password is a user-based access token.

Now let’s see how to supply these credentials to Antora’s built-in credential manager via the default git credential store.

Supply credentials using the default git credential store

By default, Antora’s built-in credential manager automatically checks for credentials in the git credential store (a database file). The default path for the git credential store is $HOME/.git-credentials, or $XDG_CONFIG_HOME/git/credentials if the first location doesn’t exist. Note that this path is a file, not a directory.

Since Antora consults the credential manager automatically when credentials are requested by the git host (aka on demand), you don’t have to specify credentials directly in your playbook. In fact, the content sources in your playbook that are private will look just like content sources that are public. Here’s how a private content source in your playbook might look:

content:
  sources:
  - url: https://hostname/your-org/private-repository

When Antora is notified by the git host that a URL requires authentication, it will look for a matching entry in the credentials store. Antora looks for a match using the URL as the key. If a protocol (e.g., https) and hostname (and, optionally, the repository path) are found in the credentials store, those credentials are returned to Antora’s credential manager and passed on to the git server.

The credential store contains zero or more line-based entries. If you need to specify multiple credentials for a single hostname (such as multiple deploy tokens), put each entry on its own line. The structure of each entry is as follows:

https://<credentials>@<hostname>

<credentials> is either a username/password pair (username:password) or an access token (token:). <hostname> is the address of the git server (e.g., github.com).

If the username or password contains characters which have special meaning in a URL, such as /, #, or :, these characters must be URL encoded. (The @ does not have special meaning in a username or password). It’s usually safe to always URL encode the username and password components in the URL. This requirement only applies for URLs that are defined in the git credential store.

To URL encode a component, open the JavaScript console in your browser, and run encodeURIComponent('<component>'), where <component> is the username or password value. Use the printed result in place of your username or password, if different. For example, the URL encoded version of my#password is my%23password.

You can populate the credential store interactively using the system git command or by editing the credential store directly. Let’s start with the interactive approach.

Populate the credential store interactively

You can use the git command to populate the credential store interactively. This approach is especially useful since it allows you to verify that your credentials are accepted by the git server.

First, select the URL of a private repository you want to use with Antora. Next, in your terminal, run the following command for each private repository you need to access from Antora:

$ echo -n 'Repository URL: ' && read REPLY && \
  git -c credential.helper=store ls-remote -h $REPLY > /dev/null

This command performs the following steps:

Prompts you for the URL of a private repository.
Communicates with the private repository, triggering a prompt for your credentials.

If you aren’t prompted for your credentials, it means your credentials are already stored.
Stores the credentials in the $HOME/.git-credentials file (and assigns it the appropriate permissions).

If this script succeeds, you can use the applicable private repositories in Antora without any further configuration.

If the interactive approach didn’t work for you, you can populate the credential store directly. Let’s give that a shot.

Populate the credential store directly

To add credentials to the git credential store directly, create the file (not directory) $HOME/.git-credentials and open it in your editor. Put each unique set of credentials (i.e., username/password pair or access token plus hostname and optional repository path) on its own line. If you’re using a single git host and a personal access token, you only need one entry. If you’re using multiple git hosts or multiple deploy tokens, you’ll need more than one entry.

Here’s an example entry that uses a username/password pair:

https://octocat:ilovegit@github.com

Here’s an example that uses a token (pay attention to the trailing : after the token):

https://abcdefg0123456:@github.com

To use different credentials for a given repository on the same git host, you can append a repository path (i.e., <repo>) to the entry to make the matching more strict. (The .git file extension in the repository path is optional).

https://<credentials>@<hostname>/<repo>

Here’s an example of an entry for a specific repository path:

https://octocat:ilovegit@github.com/octocat/Hello-World

Here are examples for several popular git hosts (for which you’d substitute the placeholders in bold with the real values):

https://TOKEN:@github.com/org/project-docs
https://oauth2:TOKEN@gitlab.com/org/project-docs.git
https://gitlab+deploy-token-TOKEN_ID:TOKEN@gitlab.com/org/project-docs.git
https://x-oauth-token:TOKEN@bitbucket.org/org/project-docs.git
https://USERNAME:APP_PASSWORD@bitbucket.org/org/project-docs.git

Specifying the repository path in the URL is optional. If you don’t include it, that credential pair will be used for all URLs that share the same git host.

You may need to append the .git file extension depending on which URL format you use for your content sources and whether you’ve configured the ensure_git_suffix key in your playbook.

Notice that the tokens are located in different locations in the URL depending on the git host. See OAuth2 formats for more details. If you’re using a Bitbucket app password, notice you must include your own username (using the format USERNAME:APP_PASSWORD).

To ensure the credentials file is protected, immediately set its file permissions so it cannot be read by others.

$ chmod 600 $HOME/.git-credentials

Specify a custom git credential store path

Instead of using the credential store at the default path(s), you can instruct Antora to look for the file in a different location using either the --git-credentials-path CLI option or GIT_CREDENTIALS_PATH environment variable, both of which set the git.credentials.path playbook key at runtime.

Here’s an example that uses the CLI option to specify a path relative to the playbook file:

$ antora --git-credentials-path=./.git-credentials antora-playbook.yml

To learn more about how to use the git.credentials.path playbook key, including how to set it directly in the playbook, consult the reference for the git.credentials.path key.

Pass credentials via an environment variable

Instead of reading the credentials from a file, you can have Antora read the credentials directly from the environment variable named GIT_CREDENTIALS, which sets the git.credentials.contents playbook key at runtime.

Here’s an example that demonstrates the concept:

$ export GIT_CREDENTIALS='https://octocat:ilovegit@github.com'
$ antora antora-playbook.yml

You can even reduce this to a single line (which only defines the environment variable for the scope of the command):

$ GIT_CREDENTIALS='https://octocat:ilovegit@github.com' antora antora-playbook.yml

When using the Windows command prompt, you need to define the environment variable using the set command:

C:\> set "GIT_CREDENTIALS=https://octocat:ilovegit@github.com" && antora antora-playbook.yml

This strategy is most useful in a CI environment where environment variables can be secured. It’s also a quick and informal way of passing credentials to Antora when generating the site on your own machine.

When using the environment variable, multiple entries may be separated either by a comma or a newline character. For example:

$ GIT_CREDENTIALS='https://my-github-token:@github.com,https://oauth2:my-gitlab-token@gitlab.com' antora antora-playbook.yml

Exporting the environment variable saves you from having to type it each time you run Antora.

To learn more about how to use the git.credentials.contents playbook key, including how to set it directly in the playbook, consult the reference for the git.credentials.contents key.

Encode credentials in a URL (not recommended)

Another option for passing credentials to the credential manager is to encode them directly in the URL listed in the playbook. Since this option doesn’t trigger the challenge-response workflow, Antora automatically assumes the repository is private.

This strategy is not recommended unless you’re using a placeholder to inject the real credentials, as described at the end of this section.

Antora will extract the credentials that precede the hostname (i.e., username:password@ or token@) and use them to perform authentication on your behalf if requested by the server.

Here are examples for several popular git hosts (for which you’d substitute the placeholders in bold with the real values):

Example 1. antora-playbook.yml (fragment)

content:
  sources:
  - url: https://TOKEN:@github.com/org/project-docs
  - url: https://oauth2:TOKEN@gitlab.com/org/project-docs.git
  - url: https://gitlab+deploy-token-TOKEN_ID:TOKEN@gitlab.com/org/project-docs.git
  - url: https://x-oauth-token:TOKEN@bitbucket.org/org/project-docs.git
  - url: https://USERNAME:APP_PASSWORD@bitbucket.org/org/project-docs.git

The drawback of this approach is that it requires putting the credentials directly into the playbook file. Unfortunately, Antora does not yet support resolving environment variables located in the playbook file. However, you can emulate this behavior by using a script to substitute references to an environment variable in the playbook file with its value.

Let’s assume you have the following source defined in your playbook file:

Example 2. antora-playbook.yml (fragment)

content:
  sources:
  - url: https://$GITHUB_TOKEN:@github.com/org-name/project-docs

If you’re using multiple private repositories that require the same credentials, you can instead define the credentials once under the git key as follows:

Example 3. antora-playbook.yml (fragment)

git:
  credentials:
    contents: https://$GITHUB_TOKEN:@github.com

You can then use the following script to expand the references to the environment variable, which you may run in CI prior to invoking Antora:

$ sed -i s/\$GITHUB_TOKEN/$GITHUB_TOKEN/ antora-playbook.yml
$ antora antora-playbook.yml

Despite this workaround, we still recommend using the credential store integration described earlier.

Configure a custom credential manager

The git client used by Antora, isomorphic-git, provides a pluggable credential manager for looking up authentication credentials. Antora provides a default implementation of this plugin. As you’ve seen in previous sections, this implementation assumes Antora can access the credentials directly, in plain text, either via a file or environment variable. If this arrangement does not meet your security requirements, you can replace the built-in credential manager with your own.

To write a custom credential manager, export a JavaScript object that implements the following methods:

Example 4. API for custom git credential manager

configure ({ config, startDir })
async fill ({ url })
async approved ({ url })
async rejected ({ url, auth })
status ({ url })

The method that looks up the credentials is fill. It must return either a { username, password } or { token } data object. The approved and rejected methods are called when the credentials are approved or rejected by the server, respectively.

The optional configure and status methods are specific to Antora, extending the capabilities of what a credential manager in isomorphic-git typically provides. If defined, the configure method is called each time Antora starts, providing an opportunity to perform initialization steps such as defining properties. The status method, if available, is used by Antora to look up whether authentication was requested for a given URL.

To activate your custom credential manager, first write your implementation in a dedicated JavaScript file and configure it as the default export:

Example 5. custom-git-credential-manager.js

module.exports = {
  async fill ({ url }) { ... },
  async approved ({ url }) { ... },
  async rejected ({ url, auth }) { ... },
}

Then register the credential manager with the playbook as follows:

git:
  plugins:
    credential_manager: ./custom-git-credential-manager.js

Alternately, you can configure the plugin to self register:

Example 6. custom-git-credential-manager.js

'use strict'

const git = require('isomorphic-git')

if (!git.cores) git.cores = new Map()
git.cores.set('antora', new Map().set('credentialManager', {
  async fill ({ url }) { ... },
  async approved ({ url }) { ... },
  async rejected ({ url, auth }) { ... },
}))

Notice that in this case, the plugin name is credentialManager rather than credential_manager. That’s because the playbook builder automatically camelCases the key name for us, which is the key name that git client expects.

When using a self-registering credential manager, you pass it to Antora using the -r option instead of registering it with the playbook:

$ antora -r ./custom-git-credential-manager.js antora-playbook.yml

If you’ve installed Antora globally using npm, you may run into problems getting your self-registering credential manager to work. Either you’ll encounter the error Cannot find module 'isomorphic-git' or your custom credential manager won’t be called. To fix this problem, set the NODE_PATH environment variable to tell Node.js where to look for Antora’s dependencies:

$ NODE_PATH=$(npm -g list --parseable=true @antora/site-generator)/node_modules \
  antora -r ./custom-git-credential-manager.js antora-playbook.yml

The alternate solution is to install Antora locally (i.e., add the Antora packages to the dependencies in package.json file and run npm i).

Since self-registering a plugin is more complex, we’ll proceed with the example of registering the plugin in the playbook.

Get credentials from git

Git offers a command named git credential that serves as a simple interface for storing and retrieving credentials from system-specific helpers in the same manner as git itself. It can also prompt the user for a username and password. We can use this command in a custom credential manager to allow Antora to delegate to git to look up credentials (and thus integrate with the user’s own git settings).

Let’s start by creating a helper function that interfaces with the system git via git credentials fill to retrieve the credentials for a URL:

Example 7. system-git-credential-manager.js

'use strict'

const { spawn } = require('child_process')

function callGitCredentialFill (url) {
  const { protocol, host } = new URL(url)
  return new Promise((resolve, reject) => {
    const output = []
    const process = spawn('git', ['credential', 'fill'])
    process.on('close', (code) => {
      if (code) return reject(code)
      const { username, password } = output.join('\n').split('\n').reduce((acc, line) => {
        if (line.startsWith('username') || line.startsWith('password')) {
          const [key, val] = line.split('=')
          acc[key] = val
        }
        return acc
      }, {})
      resolve(password ? { username, password } : username ? { token: username } : undefined)
    })
    process.stdout.on('data', (data) => output.push(data.toString().trim()))
    process.stdin.write(`protocol=${protocol.slice(0, -1)}\nhost=${host}\n\n`)
  })
}

Next, let’s create a credential manager that uses this function to fill the credentials for a URL:

// ...

module.exports = {
  configure () {
    this.urls = {}
  },
  async fill ({ url }) {
    this.urls[url] = 'requested'
    return callGitCredentialFill(url)
  },
  async approved ({ url }) {
    this.urls[url] = 'approved'
  },
  async rejected ({ url, auth }) {
    this.urls[url] = 'rejected'
    const data = { statusCode: 401, statusMessage: 'HTTP Basic: Access Denied' }
    const err = new Error(`HTTP Error: ${data.statusCode} ${data.statusMessage}`)
    err.name = err.code = 'HttpError'
    err.data = data
    if (auth) err.rejected = true
    throw err
  },
  status ({ url }) {
    return this.urls[url]
  },
}

Finally, we need to register the credential manager with the playbook:

git:
  plugins:
    credential_manager: ./system-git-credential-manager.js

Antora will now delegate to the system git to fill the credentials for a URL:

$ antora antora-playbook.yml

It’s left up to an exercise for the reader to store or erase the credentials based on whether they were approved or rejected by the server (hint: use the approved and rejected methods to invoke git credential again).

SSH authentication

Since 2.0, Antora no longer supports public/private key authentication over SSH using an SSH agent. Instead, Antora transparently converts git SSH URLs in the playbook to HTTPS URLs and uses the credential manager for authentication. That means you can use SSH URLs and HTTPS URLs interchangeably in your playbook file, but ultimately the git client will communicate over HTTPS. If, for some reason, this automatic translation doesn’t work, you’ll need to update your playbook file to use the correct HTTPS URL.