Git Credentials Path and Contents
In order for Antora to access private repositories, you must supply it with authentication credentials in order to access those private repositories.
When you’re using an alternate git credential store location or haven’t populated the store with credentials, you can use the
credentials.contents keys to pass your credentials to Antora.
When a git host requests authentication for a private content source repository, Antora’s built-in credential manager automatically checks for credentials in the default git credential store. The default path for the git credential store is $HOME/.git-credentials (or $XDG_CONFIG_HOME/git/credentials, if the previous location doesn’t exist).
credentials key is set under the git key.
git: (1) credentials: (2)
|1||Enter the parent key
credentials key accepts a key-value pair the specifies an alternate filesystem path (
path) to a git credentials file or the contents of the git credentials file (
contents key and the
path key are mutually exclusive.
That is, you can only set one or the other in your playbook.
Instead of using the credential store at the default path, you can instruct Antora to look for the file in a different location.
path key specifies a filesystem path where Antora can locate the git credential store.
This path is configured under the
credentials keys in a playbook.
path key accepts an absolute filesystem path or a filesystem path relative to the playbook file.
git: credentials: (1) path: /home/user/.git-credentials (2)
|2||Type the key name
You can also specify an alternate git credentials path using the --git-credentials-path CLI option or GIT_CREDENTIALS_PATH environment variable.
Instead of using the
contents key accepts one set of credentials or the credentials for one git host using the
To specify more than one set of credentials or access private repositories on different git hosts, you need to populate the credential store interactively or directly.
You can also pass more than one set of credentials using the GIT_CREDENTIALS environment variable.
contents key is configured under the
git.credentials key in a playbook.
The value of
contents depends on the git host that serves the private content sources repository.
In general, the value takes the form of
<credentials> is a placeholder that references an environment variable (
$ENV_VARIABLE), a username/password pair (
username:password), or an access token (
<hostname> is the address of the git server (e.g.,
|We don’t recommend directly entering your git host username/password pair or access token into a playbook! You could accidentally expose them by pushing your playbook to a remote repository or CI server.|
In the example below, a reference to an environment variable named
GITHUB_TOKEN is placed where the host GitHub expects to locate an access token.
The credentials structure and location depends on the git host.
For instance, GitHub requires a colon (
:) be placed at the end of the token.
git: credentials: contents: https://$GITHUB_TOKEN:@github.com
Unfortunately, Antora does not yet support resolving environment variables located in the playbook file. However, you can emulate this behavior by using the following script to substitute the environment variable reference with a value prior to invoking Antora:
$ sed -i s/\$GITHUB_TOKEN/$GITHUB_TOKEN/ antora-playbook.yml && antora antora-playbook.yml
Despite this workaround, we still recommend populating the git credential store or passing your credentials using the
GIT_CREDENTIALS environment variable instead of using the