0060 — Antora + Gitlab

17 нояб. 2024

Содержимое страницы

Статья будет дополняться.

Постановка задачи

У нас есть проект Antora, состоящий из следующих компонентов:

project-antora — репозиторий с настройками Antora;
project-content — репозиторий с содержимым;
стандартная тема оформления.

Пусть у нас все репозитории приватные и хранятся в GitLab. Доступ к указанным репозиториям по SSH уже настроен.

Нужно настроить CI/CD таким образом, чтобы при коммите в репозитории project-antora или project-content автоматически запускались сборка и развёртывание проекта.

Для сборки проекта мы будем использовать официальный Docker-образ Antora:

antora/antora:latest

Особенность в том, что внутрь контейнера надо как-то передать учётные данные, используя которые Antora сможет загрузить приватный репозиторий GitLab с содержимым.

В документации Antora я нашёл сведения о том, что клонирование репозиториев с использованием SSH-ключей больше не работает и поддерживаться не будет. Вместо этого предлагается использовать токены OAuth2.

Примеры кода со страницы Private Repository Authentication у меня не заработали. Я получал то предложение ввести имя пользователя и пароль, то ошибки доступа.

Эта статья — результат моих изысканий для решения описанной проблемы.

Итак, чтобы настроить CI/CD для Antora с использованием приватных репозиториев GitLab, нужно выполнить следующие шаги:

Создать в репозитории project-content токен OAuth2, предоставляющий доступ на чтение.
Создать в репозитории project-antora секрет для хранения созданного токена.
Каким-то образом получить токен из переменной и передать в контейнер с Antora, чтобы она смогла сделать git pull и собрать проект.

Звучит не сложно, правда?

Настройка репозитория с содержимым

Перейдите на страницу репозитория с содержимым.
На панели навигации выберите Настройки → Access tokens.
Нажмите кнопку Добавить новый токен.
Заполните форму Add a project access token:
- Token name — укажите название токена. Ни на что, кроме восприятия, не влияет.
- Срок действия — можно указать произвольно. Если очистить это поле, то токен будет действовать целый год.
- Select a role — выберите Developer.
  Должно хватить и Guest, но у меня почему-то токен с этой ролью не давал нужного доступа.
- Select scopes — включите эти чекбоксы:
  - read_repository
  - write_repository
    Не знаю, на кой чёрт для git pull нужно разрешение write_repository, но без этого будет ошибка 403 Access denied.
Нажмите кнопку Create project access token.
Скопируйте содержимое токена в надёжное место — очень скоро он понадобится.
На панели навигации выберите Manage → Участники.
Помимо вас в списке участников будет пользователь с именем, указанным ранее в поле Token name, и меткой Бот. Нажмите на ссылку с именем этого пользователя.
На странице бота отображается его имя, а под именем — строка следующего вида:
```
@project_12345678_bot_12309210214*1230
```
Часть после символа @ — идентификатор бота. Его тоже сохраните в надёжное место.

Настройка репозитория Antora

Перейдите на страницу репозитория с настройками Antora.
На панели навигации выберите Настройки → CI/CD.
Разверните список Переменные и нажмите кнопку Add varible.
Заполните форму Add variable следующим образом:
- Тип — Variable (default).
- Окружения — Все (по умолчанию).
- Visibility — Маскируемая.
  Нам не надо, чтобы содержимое токена отображалось в журналах сборки. Это дыра в безопасности.
- Protect variable — выключите. Значение переменной будет доступно во всех ветках и для всех тегов.
- Expand variable reference — оставьте включенным.
- Описание (optional) — тут можно указать что-то вроде «Токен для доступа к репозиторию с содержимым».
- Ключ — DEPLOY_TOKEN.
- Value — введите содержимое токена.
Нажмите кнопку Add variable.
Создание переменной, хранящей значение токена, завершено.
В списке Переменные нажмите кнопку Add variable ещё раз и заполните форму Add variable следующим образом:
- Тип — Variable (default).
- Окружения — Все (по умолчанию).
- Visibility — Visible.
  Нет смысла скрывать имя пользователя.
- Protect variable — выключите.
- Expand vairable reference — оставьте включенным.
- Описание (optional) — можно указать что-то вроде «ID бота, используемого для CI/CD».
- Ключ — DEPLOY_USER.
- Value — введите идентификатор бота, полученный ранее.
Нажмите кнопку Add variable.
Создание переменной, хранящей имя бота, завершено.

Настройка CI/CD на уровне проекта

Настройки CI/CD делаются путём правки файла .gitlab-ci.yml в корневом каталоге проекта project-antora. Как я уже писал выше, предполагается, что доступ по SSH у вас уже настроен, а значит, создать локальную копию проекта — не проблема.

Итак, с корневом каталоге проекта создайте файл .gitlab-ci.yml в вот таким содержимым:

---
stages:
  - build
  - deploy

variables:
  GIT_CREDENTIALS: 'https://${DEPLOY_USER}:${DEPLOY_TOKEN}@gitlab.com'

before_script:
  - echo $GIT_CREDENTIALS > ~/.git-credentials

build-job:
  stage: build
  image: antora/antora:latest
  script:
    - antora antora-playbook.yml
  artifacts:
    paths:
      - build

deploy-job:
  stage: deploy
  script:
    - mv build/ public/
  artifacts:
    paths:
      - build/

CI/CD здесь состоит из двух этапов:

build — сборка проекта;
deploy — развёртывание собранного проекта.

Самая интересная часть — variables. Здесь описана переменная GIT_CREDENTIALS, имеющая следующий вид:

https://${DEPLOY_USER}:${DEPLOY_TOKEN}@gitlab.com

Значения DEPLOY_USER и DEPLOY_TOKEN берутся из переменных, созданных ранее. То есть итоговая строка будет иметь примерно такой вид:

https://project_12345678_bot_12309210214*1230:glpat-V1*****Wc@gitlab.com

Этого вполне достаточно для авторизации. Указывать полный путь к репозиторию нет необходимости.

Перед запуском этапа build выполняются действия, описанные в шаге before_script. Здесь содержимое переменной GIT_CREDENTIALS записывается в файл ~/.git-credentials.

Этот файл не простой, а особенный. Его формат описан в документации Git. Здесь же просто скажу, что при попытке получить доступ к репозиторию Git заглянёт в этот файл и посмотрит, нет ли там нужных учётных данных. Если они есть, он их использует, а это как раз то, что нам и нужно, чтобы Antora в контейнере смогла скачать репозиторий с содержимым.

Файл antora-playbook.yml заполните без указания учётных данных:

---
site:
  title: Site title
  start_page: index.adoc
content:
  sources:
    - url: https://gitlab.com/organization/project-content.git
      branches: HEAD
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true
asciidoc:
  attributes:
    experimental: ""
    hide-uri-scheme: '@'
    idprefix: ''
    idseparator: '-'
    page-pagination: ''
output:
  dir: ./public

Настройка веб-обработчика (web-hook)

Прямо сейчас сборка и деплой запускаются автоматически при любых изменениях в репозитории project-antora. Теперь настроим всё так, чтобы сборка и развёртывание запускались автоматически при изменениях в репозитории project-content.

Создайте токен для проекта project-antora:

На панели навигации выберите Настройки → Основные.
Скопируйте куда-нибудь значение из поля ID проекта — оно скоро понадобится.
На панели навигации выберите Настройки → CI/CD.
Разверните список Pipeline trigger tokens и нажмите кнопку Добавить новый токен.
Укажите описание токена, например, Web Hook Token.
Нажмите кнопку Create pipeline trigger token.
Скопируйте содержимое токена в буфер обмена.

Настройте веб-обработчик (web-hook) в проекте project-content:

На панели навигации выберите Настройки → Веб-обработчики.
Нажмите кнопку Add new webhook.
Заполните форму Веб-обработчики:
- URL — введите ссылку следующего вида:
```
https://gitlab.com/api/v4/projects/<PROJECT_ID>/ref/<BRANCH>/trigger/pipeline?token=<TOKEN>
```
  Здесь:
  - <PROJECT_ID> — полученный ранее идентификатор проекта, скрипт CI/CD которого нужно запустить при событии в нашем репозитории.
  - <BRANCH> — на какой ветке проекта нужно запустить обработчик. В данном случае это main.
  - <TOKEN> — полученный ранее токен, предоставляющий доступ к проекту project-antora.
- Name (optional) — произвольное название веб-обработчика, например, CI/CD trigger.
- Secret token — оставьте пустым.
- Trigger — включите нужные чекбоксы. Чтобы скрипт CI/CD запускался при пуше в ветку master:
  1. Включите События отправки.
  2. Выберите Wildcard pattern.
  3. Введите main.
Нажмите кнопку Сохранить изменения.
Перейдите на страницу созданного веб-обработчика.
Нажмите кнопку Тест и в выпадающем списке выберите тип события, которое нужно проверить.
Триггер сработает по-настоящему.