Git Credentials Path and Contents

In order for Antora to access private repositories, you must supply it with authentication credentials in order to access these private repositories. By default, Antora will look for these authentication credentials in the default git credentials store. When you’re using an alternate git credential store location or haven’t populated the default store with credentials, you can use the credentials.path or credentials.contents keys to pass your credentials to Antora.

Default git credentials store and path

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

The credentials key is set under the git key.

Example 1. antora-playbook.adoc

git: (1)
  credentials: (2)

1	Enter the parent key `git`, followed by a colon (`:`), and then press `Enter`.
2	The `credentials` key is a child of `git`. Enter the key’s name, `credentials`, followed by a colon (`:`), and then press `Enter`.

The credentials key accepts a key-value pair that specifies an alternate filesystem path (path) to a git credentials file or the contents of the git credentials file (contents). The contents key and the path key are mutually exclusive. That is, you can only set one or the other in your playbook.

path key

Instead of using the credential store at the default path, you can instruct Antora to look for the file in a different location. The path key specifies a filesystem path where Antora can locate the git credential store. This path is configured under the git and credentials keys in a playbook. The path key accepts an absolute filesystem path or a filesystem path relative to the playbook file.

Example 2. antora-playbook.yml

git:
  credentials: (1)
    path: /home/user/.git-credentials (2)

1	The `path` key is nested under `credentials`
2	Type the key name `path`, followed by a colon (`:`). After the colon, enter a blank space, and then the filesystem path to the git credential store.

You can also specify an alternate git credentials path using the --git-credentials-path CLI option or GIT_CREDENTIALS_PATH environment variable.

contents key

Instead of using the contents key, we highly recommend populating the default credential store with your credentials or passing them using the GIT_CREDENTIALS environment variable. This key is really only intended for an auto-generated playbook file.

The contents key accepts one set of credentials or the credentials for one git host using the contents key. 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.

The 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 https://<credentials>@<hostname>, where <credentials> is a placeholder that references an environment variable ($ENV_VARIABLE), a username/password pair (username:password), or an access token (token). <hostname> is the address of the git server (e.g., gitlab.com).

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.

Example 3. antora-playbook.yml

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 contents key.