# Настройка GitLab CI для сборки проектов gsf-cli

Инструкция по настройке CI процесса для автоматической сборки `applib`.

## 1. Настройка `gitlab-runner`

Инструкция применима к хосту сборки с `debian like` системой.

### 1.1 Настройка раннера в GitLab проекте

1. Перейдите в нужный проект.
2. Откройте меню: `Settings` → `CI/CD`.
3. Разверните секцию `Runners`.
4. Нажмите **"New project runner"**.
5. Укажите:
   - **Tag** — метка, по которой будет запускаться раннер.
   - **Runner description** — описание раннера.
6. **Отключите** опцию `Run untagged jobs`.

После нажатия вы перейдёте на страницу справки по регистрации gitlab-runner.

Выберите нужную операционную систему и сохраните предложенную команду регистрации.

---

### 1.2. Установка GitLab Runner

На хосте сборки выполните следующие команды:

```bash
# Скачивание бинарного файла GitLab Runner
sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64

# Выдача прав на исполнение
sudo chmod +x /usr/local/bin/gitlab-runner

# Создание системного пользователя
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

# Установка раннера как systemd-сервиса
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner

# Запуск сервиса
sudo gitlab-runner start
```

---

### 1.3. Регистрация раннера

Выполните команду регистрации, полученную на этапе `Настройка раннера в GitLab проекте`:

**Пример:**

```bash
sudo gitlab-runner register --url http://gitlablocal --token glrt-t3_m2-zeUzFHMysT3QDwmsT
```

Данная команда выдаст диалоговое окно, в котором:

- Укажите **имя** раннера (можно оставить по умолчанию).
- Выберите тип исполнителя: `shell`.
- Убедитесь, что вы используете **тот же tag**, что был указан на этапе `Настройка раннера в GitLab проекте`.

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

---

### 1.4. Проверка

Для проверки работоспособности раннера, создайте минимальный `.gitlab-ci.yml` (Укажите корректный тэг раннера):

```yaml
test-job:
  tags:
    - <your-runner-tag>
  script:
    - echo "Runner работает!"
```

---

### Возможные проблемы

Если при запуске пайплайна, он выдает такую ошибку:

```{bash}
Running with gitlab-runner 18.0.3 (4e717029)
  on gsf-cli-runner t3_bF2zm, system ID: s_3f8d99cb7822
Preparing the "shell" executor
00:00
Using Shell (bash) executor...
Preparing environment
00:00
Running on gsf-cli-ci...
ERROR: Job failed: prepare environment: exit status 1. Check https://docs.gitlab.com/runner/shells/#shell-profile-loading for more information
```

Тогда требуется:

- в файле `/home/gitlab-runner/.bash_logout` закомментировать строки:

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

- перезапустить сервис `gitlab-runner`

  ```bash
  sudo systemctl restart  gitlab-runner.service
  ```

## 2. Установка и настройка GSF-CLI на хосте сборки

### Программное обеспечение, которое потребуется для сборки

- [Java 21](https://github.com/bell-sw/Liberica/releases/download/21.0.6%2B10/bellsoft-jdk21.0.6+10-linux-amd64-full.deb)
- [Sbt 1.10.7](https://github.com/sbt/sbt/releases/download/v1.10.7/sbt-1.10.7.zip)
- [Утилита gsf-cli](https://repo.global-system.ru/artifactory/common/ru/bitec/gsf-cli-linux/SNAPSHOT/gsf-cli-linux-SNAPSHOT.zip)

### 2.1. Установка требуемых пакетов

```bash
sudo apt update && sudo apt install -y sudo wget git mc zip unzip
```

---

### 2.2. Подготовка директорий

Создайте рабочие каталоги:

```bash
sudo mkdir -p /opt/global/tmp
sudo mkdir -p /opt/global/builds
```

---

### 2.3. Загрузка необходимых компонентов

```bash
# GSF CLI
sudo wget -P /opt/global/tmp https://repo.global-system.ru/artifactory/common/ru/bitec/gsf-cli-linux/SNAPSHOT/gsf-cli-linux-SNAPSHOT.zip

# sbt
sudo wget -P /opt/global/tmp https://github.com/sbt/sbt/releases/download/v1.10.7/sbt-1.10.7.zip

# JDK 21 от BellSoft
sudo wget -P /opt/global/tmp https://github.com/bell-sw/Liberica/releases/download/21.0.6%2B10/bellsoft-jdk21.0.6+10-linux-amd64-full.deb
```

---

### 2.4. Установка и распаковка компонентов

```bash
# Установка JDK
sudo apt install /opt/global/tmp/bellsoft-jdk21.0.6+10-linux-amd64-full.deb

# Распаковка SBT
sudo unzip /opt/global/tmp/sbt-1.10.7.zip -d /opt/global

# Распаковка GSF CLI
sudo unzip /opt/global/tmp/gsf-cli-linux-SNAPSHOT.zip -d /opt/global/gsf-cli
```

---

### 2.5. Установка GSF CLI

```bash
sudo /opt/global/gsf-cli/bin/installpkg.sh
sudo /opt/global/gsf-cli/bin/initvenv.sh
```

---

### 2.6. Настройка сборочного проекта

#### Конфигурационный файл

Создайте конфигурационный файл:

```bash
sudo nano /opt/global/builds/config.json
```

cо следующим содержимым (укажите корректный `project_branch` и `project_source`)

- `project_source` — url на конфигурационный проект
- `project_branch` — ветка конфигурационного проекта

```json
{
  "sbt_home": "/opt/global/sbt",
  "svn_path": "",
  "projects": [
    {
      "project_branch": "test",
      "jdk_home": "/usr/lib/jvm/bellsoft-java21-amd64/",
      "name": "main",
      "project_source": "https://extgit.global-system.ru/pgtest.git",
      "project_source_type": "vcs",
      "publish_type": "SNAPSHOT",
      "vcs_type": "git"
    }
  ]
}
```

Детальное описание файла можно посмотреть [тут](100_конфигурационные_файлы.md)

#### Регистрация приватного ключа

```bash
sudo /opt/global/gsf-cli/config.sh register_private_key -c /opt/global
```

#### Установка необходимых учётных данных

```bash
sudo /opt/global/gsf-cli/credential_manager.sh set -u <url> -l <login> -p <password>
```

Указывайте учетные данные для необходимых репозиториев, указанных в файле default.yaml из конфигурационного проекта.

**Пример:**

```{bash}
sudo /opt/global/gsf-cli/credential_manager.sh set -u https://git.global-system.ru/ -l ts.user -p testtest
```

Если у вас закрытая среда, то ознакомьтесь с [документацией](37_сборка_в_закрытой_среде.md)

---

### 2.7. Активация headless-режима

Включаем `headless` режим, для отключение диалога с пользователем в процессе сборки.

```bash
sudo /opt/global/gsf-cli/config.sh enable_headless
```

---

### 2.8. Загрузка конфигурации

Команда для загрузки конфигурации из `config.json`.

```{{attention}}
Данную операцию нужно выполнять каждый раз, после внесения изменений в config.json!
```

```bash
sudo /opt/global/gsf-cli/config.sh load_config -f /opt/global/builds/config.json
```

---

### 2.9. Смена владельца директории

Сделайте владельцем директории с `gsf-cli`, пользователя, который был создан в шаге `Установка GitLab Runner`, в данном примере это `gitlab-runner`

```bash
sudo chown gitlab-runner:gitlab-runner /opt/global -R
```

## 3. Конфигурация пайплайна

Создайте файл `.gitlab-ci.yml` в корне проекта.

Минимальная конфигурация `.gitlab-ci.yml` для сборки проекта:

```yaml
stages:
  - build

ssh_execute:
  stage: build
  tags:
    - <runner_tag>
  script:
    - |
      /opt/global/gsf-cli/manage.sh --all build
```

После выполнения данного пайплайна в папке `/opt/global/gsf-cli/workspace/sources/<project_name>/application/build/publish/applib` будет собранное прикладное решение.

---