Git凭证路径和内容

为了让Antora访问私有存储库，您必须提供身份验证凭据，以便访问这些私有存储库。默认情况下，Antora将在默认的git凭证存储中查找这些身份验证凭据。当您使用替代的git凭证存储位置或未在默认存储中填充凭据时，您可以使用credentials.path或credentials.contents键将您的凭据传递给Antora。

默认的git凭证存储和路径

当git主机请求对私有内容源存储库进行身份验证时，Antora内置的凭证管理器会自动检查$HOME/.git-credentials（或$XDG_CONFIG_HOME/git/credentials，如果之前的位置不存在）中的凭据。git凭证存储的默认路径是$HOME/.git-credentials（如果之前的位置不存在，则为$XDG_CONFIG_HOME/git/credentials）。

凭证键

credentials键设置在git键下。

示例1. antora-playbook.adoc

git: (1)
  credentials: (2)

1	输入父键`git`，后跟冒号（`:`），然后按`Enter`。
2	`credentials`键是`git`的子级。输入键名`credentials`，后跟冒号（`:`），然后按`Enter`。

credentials键接受一个键值对，指定到git凭证文件的替代文件系统路径（path）或git凭证文件的内容（contents）。contents键和path键是互斥的。也就是说，在您的playbook中只能设置其中一个。

路径键

您可以指定一个不同的位置，让Antora在那里查找文件，而不是使用默认路径上的凭证存储。path键指定Antora可以定位git凭证存储的文件系统路径。此路径在playbook中的git和credentials键下进行配置。path键接受绝对文件系统路径或相对于playbook文件的文件系统路径。

示例2. antora-playbook.yml

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

1	`path`键嵌套在`credentials`下
2	输入键名`path`，后跟冒号（`:`）。在冒号后，输入一个空格，然后是指向git凭证存储的文件系统路径。

您还可以使用--git-credentials-path CLI选项或GIT_CREDENTIALS_PATH环境变量指定替代的git凭证路径。

内容键

我们强烈建议不要直接使用contents键，而是使用填充默认凭证存储或通过GIT_CREDENTIALS环境变量传递凭据。这个键实际上只用于自动生成的playbook文件。

contents键接受一个凭据集或使用contents键为一个git主机提供凭据。要指定多个凭据集或访问不同git主机上的私有存储库，您需要交互式地填充凭证存储或直接填充。您还可以使用GIT_CREDENTIALS环境变量传递多个凭据集。

contents键在playbook中的git.credentials键下进行配置。contents的值取决于提供私有内容源存储库的git主机。通常，该值采用https://<凭据>@<主机名>的形式，其中<凭据>是一个引用环境变量（$ENV_VARIABLE）、用户名/密码对（username:password）或访问令牌（token）的占位符。<主机名>是git服务器的地址（例如，gitlab.com）。

我们不建议直接在playbook中输入git主机的用户名/密码对或访问令牌！您可能会通过将playbook推送到远程存储库或CI服务器而意外暴露它们。

在下面的示例中，将一个名为GITHUB_TOKEN的环境变量引用放在GitHub期望找到访问令牌的位置。在token的末尾，GitHub要求放置一个冒号（:）。

示例3. antora-playbook.yml

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

不幸的是，Antora目前还不支持解析位于playbook文件中的环境变量。但是，您可以通过使用以下脚本在调用Antora之前将环境变量引用替换为值来模拟这种行为：

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

尽管有这种解决方法，我们仍建议填充git凭证存储或使用GIT_CREDENTIALS环境变量传递您的凭据，而不是使用contents键。