Подготовка GitLab Runner и Jenkins Agent

Подготовка GitLab Runner и Jenkins Agent#

Эта глава нужна для сборки в CI. Выберите GitLab или Jenkins и подготовьте агент на выделенном Linux-хосте. Команды ниже рассчитаны на Debian-подобную систему. Для локальной сборки сразу переходите к Linux или Windows.

Агент выполняет команды от своего пользователя. Позже этому же пользователю понадобятся рабочий каталог GSF CLI, мастер-ключ и учётные данные. Не настраивайте их от root, если job работает от другой учётной записи.

GitLab Runner#

В этом варианте используется shell executor. Он имеет доступ к постоянному workspace и сохранённым credentials. Такой runner подходит для доверенного проекта и защищённых веток.

Создание runner в GitLab#

  1. Откройте проект и перейдите в Settings → CI/CD → Runners.

  2. Нажмите New project runner. Задайте описание и tag, например gsf-build.

  3. Отключите Run untagged jobs.

  4. После создания включите Protected и Lock to current projects. Runner будет обслуживать защищённые ветки и теги только назначенного проекта.

Сохраните предложенную GitLab команду регистрации с токеном вида glrt-.... Этот токен подключает runner к GitLab; для доступа GSF CLI к исходникам позднее используются отдельные учётные данные.

Установка на хосте#

Уточните версию GitLab у администратора. Выберите GitLab Runner с теми же major.minor и задайте полный тег версии вместо v<gitlab-major.minor.patch>, например v18.0.3 для соответствующей установки GitLab.

Выполните от пользователя с правом sudo:

sudo apt-get update
sudo apt-get install -y ca-certificates curl git

RUNNER_VERSION="v<gitlab-major.minor.patch>"
sudo curl -fL --output /usr/local/bin/gitlab-runner \
  "https://s3.dualstack.us-east-1.amazonaws.com/gitlab-runner-downloads/${RUNNER_VERSION}/binaries/gitlab-runner-linux-amd64"
sudo chmod 0755 /usr/local/bin/gitlab-runner

id gitlab-runner >/dev/null 2>&1 || \
  sudo useradd --comment "GitLab Runner" --create-home gitlab-runner --shell /bin/bash

sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start
gitlab-runner --version
sudo gitlab-runner status

Бинарный файл в примере предназначен для amd64. В закрытой сети заранее доставьте эту же версию через разрешённый внутренний репозиторий. Системные пакеты тоже должны быть доступны внутри контура.

Порядок ручной установки описан в документации GitLab.

Корпоративный сертификат GitLab#

Если GitLab использует сертификат внутреннего центра сертификации, настройте доверие до регистрации runner. Если внутренний сертификат нужен уже для загрузки установочных файлов, выполните этот шаг до загрузки.

Получите корневой и промежуточные CA-сертификаты в формате PEM. Добавьте каждый сертификат отдельным файлом с расширением .crt:

sudo install -m 0644 /path/to/company-root-ca.crt \
  /usr/local/share/ca-certificates/company-root-ca.crt
sudo update-ca-certificates

Повторите команду install для промежуточных CA, если они нужны, и снова выполните update-ca-certificates.

При ошибке x509: certificate signed by unknown authority дополнительно передайте цепочку CA самому runner:

sudo install -d -m 0755 /etc/gitlab-runner/certs
sudo install -m 0644 /path/to/gitlab-ca-chain.pem \
  /etc/gitlab-runner/certs/gitlab.example.org.crt
sudo systemctl restart gitlab-runner.service

Имя файла должно совпадать с hostname GitLab, без номера порта. Замените gitlab.example.org своим именем сервера. Не используйте GIT_SSL_NO_VERIFY вместо установки сертификата.

Подробнее — сертификаты GitLab Runner.

Регистрация и ограничение параллельных заданий#

Выполните команду, полученную при создании runner. Пример:

sudo gitlab-runner register \
  --config /etc/gitlab-runner/config.toml \
  --url "https://gitlab.example.org" \
  --token "<runner-authentication-token>"

Укажите имя runner и выберите executor shell. Метки задайте в настройках runner в GitLab; если диалог регистрации запросит tag, используйте ту же метку.

Путь --config в этой инструкции указывается явно: сервис должен читать тот же /etc/gitlab-runner/config.toml, в который записана регистрация. Не смешивайте системную конфигурацию и конфигурацию в домашнем каталоге пользователя.

Откройте файл:

sudoedit /etc/gitlab-runner/config.toml

Установите следующие значения в существующей конфигурации:

concurrent = 1

[[runners]]
limit = 1
executor = "shell"

Не заменяйте этим фрагментом весь файл и не добавляйте второй блок [[runners]] для уже зарегистрированного runner. Сохраните сгенерированные url, token и остальные параметры.

sudo gitlab-runner verify
sudo systemctl restart gitlab-runner.service
sudo systemctl --no-pager --full status gitlab-runner.service

Ограничение нужно для общего workspace /opt/global/gsf-cli/workspace: две сборки не должны одновременно менять его содержимое и файлы credentials одного пользователя.

Справка GitLab: регистрация и настройки runner.

Проверка runner#

Защитите тестовую ветку в GitLab. Создайте в ней .gitlab-ci.yml, указав свой tag:

test-job:
  tags:
    - gsf-build
  script:
    - test "$(whoami)" = "gitlab-runner"
    - test "$HOME" = "/home/gitlab-runner"
    - git --version

Runner должен быть online, а job — завершиться успешно. Если job остаётся в ожидании, проверьте tag и защиту ветки: защищённый runner не берёт задания из обычной незащищённой ветки.

При ошибке подготовки окружения:

Preparing the "shell" executor
Using Shell (bash) executor...
Preparing environment
ERROR: Job failed: prepare environment: exit status 1

проверьте /home/gitlab-runner/.bash_logout. Если там есть блок очистки консоли, закомментируйте его:

if [ "$SHLVL" = 1 ]; then
    [ -x /usr/bin/clear_console ] && /usr/bin/clear_console -q
fi

Перезапустите сервис:

sudo systemctl restart gitlab-runner.service

Причина описана в разделе GitLab о загрузке профиля shell.

После проверки переходите к установке GSF CLI на Linux. Используйте там пользователя gitlab-runner; конфигурация сборочного pipeline находится в конце этой же главы Linux.

Jenkins Agent#

Здесь агент подключается к Jenkins по SSH. На хосте уже должен быть пользователь, под которым Jenkins сможет открыть SSH-соединение. Его имя заменяет <agent_user> в командах ниже.

Рабочий каталог и Java#

Создайте каталог и передайте его пользователю агента:

GSF_AGENT_USER="<agent_user>"
GSF_AGENT_GROUP="$(id -gn "$GSF_AGENT_USER")"
sudo mkdir -p /opt/JenkinsSlave
sudo chown -R "$GSF_AGENT_USER:$GSF_AGENT_GROUP" /opt/JenkinsSlave

Для агента и прикладной сборки используйте JDK 21. Если в репозитории вашей ОС доступен OpenJDK 21:

sudo apt-get update
sudo apt-get install -y openjdk-21-jdk git
/usr/lib/jvm/java-21-openjdk-amd64/bin/java -version

Если такого пакета нет, установите JDK 21 из принятого в вашей организации дистрибутива и используйте его фактический путь. В закрытой сети установочные файлы должны быть доставлены заранее.

Версия Jenkins должна поддерживать запуск на Java 21; требования распространяются и на агент. Таблица совместимости приведена в политике Java для Jenkins.

Подключение узла#

В интерфейсе Jenkins создайте новый узел и выберите тип Постоянный агент. Заполните параметры:

Параметр

Значение

Удалённая корневая директория

/opt/JenkinsSlave

Метки

Например, gsf-build

Использование

Собирать только проекты с метками, совпадающими с этим узлом

Способ запуска

Launch agents via SSH

Host

Адрес подготовленного хоста

Credentials

SSH-учётные данные пользователя <agent_user>

Число исполнителей

1 для общего workspace GSF CLI

В Advanced… укажите нестандартный SSH-порт, если используется не 22. В поле JavaPath задайте путь к Java 21, особенно если на хосте установлены несколько JDK:

/usr/lib/jvm/java-21-openjdk-amd64/bin/java

Сохраните узел, откройте его и нажмите Launch agent. После успешного подключения проверьте журнал агента и его статус в Jenkins.

Переходите к установке GSF CLI на Linux, сохранив пользователя агента. В конце главы приведён пример сборочного задания Jenkins с сохранением applib и appsrc.

Содержание