Private Repository Authentication

Antora can connect to and authenticate with private (or public) repositories using either SSH or HTTP/HTTPS.

SSH authentication

One option for connecting to a private repository is to use public-private key authentication over SSH. Antora will attempt to initiate an SSH connection to clone or fetch the repository if the URL matches the pattern user@host:repo.git.

content:
  sources:
  - url: git@gitlab.com:antora/demo/demo-component-a.git

Antora relies on the SSH agent to authenticate using the private SSH repository on your behalf. This works similarly to the git command, except Antora only supports the SSH agent (not the git credentials store). That means you must have an SSH agent running on your machine and it must be configured with a public-private key pair (i.e., identity) that is recognized by the host of the git repository (e.g., GitHub). If the SSH agent isn’t running, or your key isn’t recognized by the host, Antora will fail when it attempts to clone the private repository.

Configure Your SSH Agent

To check if you have an SSH agent running, execute the following command:

$ ssh-add -l -E md5

You should see a list of keys in the form of MD5 fingerprints. If you get an error message instead, you need to start the SSH agent. That entails running:

$ eval $(ssh-agent -s)
  ssh-add ~/.ssh/id_rsa

To learn how to generate an SSH key, start the SSH agent, add your identity, and add your SSH key to your GitHub account, see Generating a new SSH key and adding it to the ssh-agent. For GitLab users, refer to GitLab and SSH keys. Once you start the SSH agent, you’ll use a command similar to this one to add your key to it:

$ ssh-add ~/.ssh/id_rsa

Once you verify your SSH agent is running and can see a list of identities, you’ll need to verify that one is registered with the git host. Check that one of the fingerprint values in the list (the part that follows the prefix MD5:) matches a value listed in the settings for your account (e.g., https://github.com/settings/keys). If none of the fingerprints match, you need to add the SSH public key to your account.

If the SSH agent is running and one of the identities is known to the git host, Antora should be able to connect to a private repository (or even a public repository) on your behalf using SSH.

HTTP/HTTPS authentication

Another option for connecting to a private repository is to use HTTP/HTTPS authentication. HTTP/HTTPS authentication can be performed using either a username+password or an OAuth (personal access) token. Antora will attempt to authenticate over HTTP or HTTPS if the URL begins with http:// or https:// and the URL contains credentials that precede the hostname (e.g., username:password@ or token@).

content:
  sources:
  - url: https://YOUR_GITHUB_TOKEN:x-oauth-basic@github.com:org/project-docs.git
  - url: https://oauth2:YOUR_GITLAB_TOKEN@gitlab.com:org/project-docs.git
  - url: https://x-oauth-token:YOUR_BITBUCKET_TOKEN@bitbucket.org:org/project-docs.git
Tokens are located in different locations in the URL depending on the git host, so mind where you place them. See OAuth2 formats for more details.

Antora will extract the credentials that precede the hostname and use them to perform authentication on your behalf.

The downside of using HTTP/HTTPS authentication is that it requires that you put your credentials directly in the playbook file. That may be fine for a local playbook file, but becomes problematic in a CI environment where the credentials can be leaked. To work around this problem, put a placeholder for the credentials in the playbook file and use a script in CI to substitute it with the real value before running Antora.

content:
  sources:
  - url: https://%GITHUB_TOKEN%:x-oauth-basic@github.com:org-name/project-docs.git

Antora does not yet support resolving environment variables located in the playbook file, though it may do so in the future.