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

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

У нас есть проект 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, нужно выполнить следующие шаги:

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

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

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

  1. Перейдите на страницу репозитория с содержимым.
  2. На панели навигации выберите Настройки → Access tokens.
  3. Нажмите кнопку Добавить новый токен.

  4. Заполните форму 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.

  5. Нажмите кнопку Create project access token.

  6. Скопируйте содержимое токена в надёжное место — очень скоро он понадобится.

  7. На панели навигации выберите Manage → Участники.

    Помимо вас в списке участников будет пользователь с именем, указанным ранее в поле Token name, и меткой Бот. Нажмите на ссылку с именем этого пользователя.

  8. На странице бота отображается его имя, а под именем — строка следующего вида:

     @project_12345678_bot_12309210214*1230

    Часть после символа @ — идентификатор бота. Его тоже сохраните в надёжное место.

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

  1. Перейдите на страницу репозитория с настройками Antora.
  2. На панели навигации выберите Настройки → CI/CD.
  3. Разверните список Переменные и нажмите кнопку Add varible.

  4. Заполните форму Add variable следующим образом:

    • Тип — Variable (default).
    • Окружения — Все (по умолчанию).

    • Visibility — Маскируемая.

      Нам не надо, чтобы содержимое токена отображалось в журналах сборки. Это дыра в безопасности.

    • Protect variable — выключите. Значение переменной будет доступно во всех ветках и для всех тегов.

    • Expand variable reference — оставьте включенным.

    • Описание (optional) — тут можно указать что-то вроде «Токен для доступа к репозиторию с содержимым».

    • Ключ — DEPLOY_TOKEN.

    • Value — введите содержимое токена.

  5. Нажмите кнопку Add variable.

    Создание переменной, хранящей значение токена, завершено.

  6. В списке Переменные нажмите кнопку Add variable ещё раз и заполните форму Add variable следующим образом:

    • Тип — Variable (default).
    • Окружения — Все (по умолчанию).

    • Visibility — Visible.

      Нет смысла скрывать имя пользователя.

    • Protect variable — выключите.

    • Expand vairable reference — оставьте включенным.

    • Описание (optional) — можно указать что-то вроде «ID бота, используемого для CI/CD».

    • Ключ — DEPLOY_USER.

    • Value — введите идентификатор бота, полученный ранее.

  7. Нажмите кнопку 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:

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

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

  1. На панели навигации выберите Настройки → Веб-обработчики.
  2. Нажмите кнопку Add new webhook.

  3. Заполните форму Веб-обработчики:

    • 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.
  4. Нажмите кнопку Сохранить изменения.
  5. Перейдите на страницу созданного веб-обработчика.

  6. Нажмите кнопку Тест и в выпадающем списке выберите тип события, которое нужно проверить.

    Триггер сработает по-настоящему.