发布到GitLab Pages

GitLab是一个DevOps平台，提供了发布基于Antora的文档到网络所需的一切。在这个页面上，我们将探讨如何使用GitLab来发布您的第一个文档站点使用Antora。

GitLab概述

每个GitLab项目都提供代码托管（git存储库）、持续集成（GitLab CI）和静态网页托管与重定向支持（GitLab Pages）。因此，GitLab非常适合从源到发布站点管理整个基于Antora的文档站点。

要使用GitLab CI/CD发布Antora站点，您需要：

  • 一个playbook项目，它起初是一个本地git存储库，用于存储Antora playbook文件。

  • 零个或多个内容项目，每个项目都有一个git存储库，用于托管内容文件。

  • 在playbook项目的git存储库根目录中命名为.gitlab-ci.yml的文件，该文件提供了CI/CD配置。

在继续之前，我们建议学习核心CI/CD概念和GitLab文档中关于.gitlab-ci.yml文件的概述。

开始

首先，在GitLab上创建一个新项目来托管您的playbook项目。按照该页面上的说明将本地git存储库推送到GitLab。如果您的playbook引用其他内容源存储库，请确保将它们也推送到GitLab。

接下来，您需要配置CI/CD。您只需要在playbook存储库的默认分支中设置GitLab CI/CD。Antora将自动从playbook中声明的其他存储库中获取内容。

我们将从一个基本的GitLab CI/CD配置文件开始，该文件使用Antora Docker镜像构建一个带有Antora的站点，并将其发布到GitLab Pages。

示例1. .gitlab-ci.yml构建和部署Antora站点 
image:
  name: antora/antora
pages:
  stage: deploy
  interruptible: true
  script:
  - antora --fetch --redirect-facility=gitlab --to-dir=public antora-playbook.yml
  artifacts:
    paths:
    - public

将.gitlab-ci.yml文件提交到git并推送到远程存储库。这将触发第一个CI/CD流水线。如果流水线成功，您的站点将可以在页面设置页面上列出的URL访问。URL通常遵循这种模式：

https://<group-name>.gitlab.io/<project-name>

即使项目是私有的，站点也将是公开的。

您可以参考playbook项目，了解使用GitLab Pages构建和发布Antora站点的另一个示例，该示例利用了GitLab CI/CD的一些附加功能。

自定义构建

到目前为止，我们依赖Antora Docker镜像在CI/CD中运行Antora。Antora Docker镜像仅提供Antora核心组件，不包括任何扩展。

虽然使用Antora Docker镜像是快速启动的便捷方式，但我们强烈建议在playbook项目中声明站点的依赖关系（或扩展Docker镜像）。通过这样做，您可以保持构建的自包含性和可移植性。如果您依赖额外的软件包，如@antora/lunr-extension和asciidoctor-kroki，这一点尤为重要。

假设您的playbook项目中有以下package.json文件，声明了对Antora、Antora Lunr Extension和Asciidoctor Kroki的依赖。

示例2. package.json 
{
  "name": "my-docs-site",
  "description": "My Docs Site",
  "private": true,
  "devDependencies": {
    "antora": "~3.0",
    "@antora/lunr-extension": "1.0.0-alpha.8",
    "asciidoctor-kroki": "0.15.4"
  }
}

您首先需要运行npm i来生成package-lock.json文件并提交这两个文件。

有了这个配置，您可以修改您的GitLab CI/CD配置以基于node:16-alpine，这是Antora Docker使用的基础镜像。然后，您需要在每次构建时获取依赖项，因为基础镜像不提供Antora。

示例3. .gitlab-ci.yml 
image:
  name: node:16-alpine (1)
variables:
  ANTORA_CACHE_DIR: .cache/antora (2)
  NODE_OPTIONS: --max-old-space-size=4096 (3)
before_script:
- npm ci (4)
pages:
  stage: deploy
  interruptible: true
  rules:
  - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH (5)
  cache:
    paths:
    - .cache (2)
  script:
  - npx antora --fetch --redirect-facility=gitlab antora-playbook.yml (6)
  artifacts:
    paths:
    - public (7)
1 Antora Docker使用的基础镜像，如果您正在本地安装软件包到playbook项目中，可以使用该镜像。
2 在运行之间存储存储库和UI捆绑包缓存。
3 （可选）增加为Node.js保留的内存，以允许Antora处理更重的构建。
4 安装package-lock.js文件中定义的依赖项。使用npm ci而不是npm i确保依赖项的版本在运行之间保持稳定。
5 仅在此存储库的默认分支上运行。
6 使用npx调用Antora，它将定位并运行项目中安装的antora命令。--fetch标志确保Antora从上一次运行保存的缓存中获取更新。
7 public目录是发布站点到GitLab Pages的预定义文件夹。

如果您的任何内容存储库是私有的，您可以在此环境中定义一个GIT_CREDENTIALS CI/CD变量，其中包含Antora访问这些存储库的凭据。您可以在内容存储库中设置部署令牌，以使playbook项目（因此Antora）的CI/CD流水线对这些存储库具有只读访问权限。

如果您希望Antora在有任何警告或非致命错误时使CI/CD流水线失败，请在antora命令中添加--log-failure-level=warn。或者，您可以在playbook中设置runtime.log.failure_level键，使其成为永久设置。