Интеграция с CI-системой GitLab

Интеграция с CI-системой GitLab позволяет:

• автоматически передавать результаты тестов из пайплайна GitLab в ТестОпс с помощью allurectl;
• запускать пайплайн GitLab из интерфейса ТестОпс через запуск джобы ТестОпс;
• синхронизировать статус запуска пайплайна сразу в обеих системах — ТестОпс и GitLab.

В настроенной интеграции одна джоба ТестОпс соответствует одному пайплайну GitLab, а один запуск джобы — одному запуску соответствующего пайплайна.

Примечание

Чтобы настроить или удалить любую интеграцию ТестОпс с внешней системой, необходима глобальная роль «Администратор» в инстансе ТестОпс и, как правило, права администратора инстанса внешней системы.

Настройка интеграции

Чтобы настроить интеграцию с CI-системой GitLab:

1. Настройте связь от ТестОпс к GitLab:

   1. Создайте токен в GitLab.
   2. Подключите интеграцию с GitLab на уровне инстанса ТестОпс.
   3. Добавьте настроенное подключение к GitLab в проект ТестОпс.

2. Настройте связь от GitLab к ТестОпс:

   1. Создайте API-токен в ТестОпс.
   2. Укажите созданный API-токен из ТестОпс в GitLab.
   3. Измените пайплайн в GitLab.
   4. Запустите и проверьте пайплайн в GitLab.
   5. Настройте созданную джобу в ТестОпс.

3. Параметризируйте джобу в ТестОпс и пайплайн в GitLab (при необходимости).

1. Настройте связь от ТестОпс к GitLab

1.1. Создайте токен в GitLab

1. В GitLab нажмите на ваш аватар и перейдите в раздел Preferences.

2. В сайдбаре слева перейдите в раздел Access Tokens.

3. Если форма создания токена не появилась, над списком токенов нажмите Add new token.

4. Заполните поля:

   • Token name — название токена, которое поможет вам распознать интеграцию (например, Токен для ТестОпс).
   • Expiration date — срок действия токена. После указанной даты интеграция перестанет работать. Чтобы возобновить ее работу, вам нужно будет создать новый токен.

5. В секции Select scopes поставьте галочки напротив api и read_api.

6. Нажмите Create token.

   После обновления страницы вы должны увидеть созданный токен.

7. Нажмите иконку копирования под Your token, чтобы скопировать токен в буфер обмена.

   Cохраните токен в безопасном месте, он понадобится для подключения интеграции с GitLab в ТестОпс.

Совет

Вы также можете использовать токен доступа проекта (project access token) вместо личного токена доступа, но в этом случае интеграция будет ограничена одним проектом.

1.2. Подключите интеграцию с GitLab на уровне инстанса ТестОпс

1. Перейдите в ваш инстанс ТестОпс.

2. Перейдите в раздел Администрирование → Интеграции.

3. Нажмите Добавить интеграцию.

4. В списке доступных интеграций выберите GitLab.

5. Заполните поля:

   • Название подключения — введите название, которое поможет вам распознать интеграцию (например, GitLab production).

   • Endpoint — введите URL-адрес вашего инстанса GitLab (например, https://gitlab.example.com/).

   • Тип учетных данных — нажмите на выпадающий список и выберите тип учетных данных GitLab, который будет поддерживать интеграция:

     • Все (глобальные и проектные) — интеграция может работать как с глобальными, так и с проектными учетными данными;
     • Только глобальные — интеграция может работать только с глобальными учетными данными;
     • Только проектные — интеграция может работать только с проектными учетными данными.

     Примечание

     Подробнее о поддерживаемых типах учетных данных см. Интеграции с внешними системами → Глобальные и проектные учетные данные

6. Если ваш инстанс GitLab использует самоподписанный SSL-сертификат, уберите галочку напротив Проверка SSL-сертификата.

7. Если интеграция может работать с глобальными учетными данными GitLab, в секции Глобальные учетные данные введите токен доступа GitLab, который вы сохранили на шаге 1.1.

8. Нажмите Добавить подключение.

1.3. Добавьте настроенное подключение к GitLab в проект ТестОпс

Чтобы добавить настроенное подключение к GitLab в нужный проект ТестОпс, воспользуйтесь одним из способов:

1. В ТестОпс перейдите в раздел Администрирование → Интеграции.

2. В списке настроенных интеграций найдите и откройте интеграцию с GitLab.

3. В списке настроенных подключений найдите и откройте ваше подключение к GitLab.

4. Нажмите Добавить в проект.

5. В списке доступных проектов выберите нужный проект ТестОпс.

6. Если интеграция может работать и с глобальными, и с проектными учетными данными GitLab, в поле Тип учетных данных нажмите на выпадающий список и выберите вариант, который будет использоваться в проекте:

   • Проектные — использовать проектные учетные данные для подключения к GitLab;
   • Глобальные — использовать глобальные учетные данные для подключения к GitLab.

7. Если интеграция будет работать с проектными учетными данными GitLab, в секции Проектные учетные данные введите токен доступа GitLab, который вы сохранили на шаге 1.1.

8. Нажмите Добавить в проект.

2. Настройте связь от GitLab к ТестОпс

Выполните шаги ниже, чтобы настроить вторую часть двусторонней связи: отправку статусов пайплайнов и результатов тестов из GitLab в ТестОпс.

2.1. Создайте токен в ТестОпс

1. В ТестОпс нажмите на ваш аватар и перейдите в раздел API-токены.

2. Нажмите + Токен.

3. Введите название токена, которое поможет вам распознать интеграцию (например, Токен для GitLab).

4. Нажмите Создать.

   ТестОпс сгенерирует токен и отобразит его в модальном окне.

5. Нажмите иконку Копировать, чтобы скопировать токен в буфер обмена.

   Cохраните токен в безопасном месте, он понадобится для настройки интеграции в GitLab.

6. Нажмите Готово.

2.2. Укажите токен в GitLab

1. В GitLab откройте проект, для которого вы настраиваете интеграцию.

2. В сайдабре слева перейдите в раздел Settings → CI/CD.

3. Разверните раздел Variables.

4. В секции Project variables нажмите Add variable.

5. В появившемся окне заполните поля:

   • Type — нажмите на выпадающий список и выберите Variable;
   • Visibility — выберите Masked;
   • Key — введите ALLURE_TOKEN;
   • Value — введите API-токен, который вы сохранили на шаге 2.1.

6. Нажмите Add variable, чтобы сохранить настройки.

2.3. Измените пайплайн в GitLab

Примечание

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

1. В GitLab откройте репозиторий, для которого вы настраиваете интеграцию.

2. Откройте файл .gitlab-ci.yml.

3. Добавьте команду before_script, которая загружает allurectl и делает его исполняемым.

   Совет

   В приведенном ниже примере используется curl для загрузки файла. Если curl не включен в образ Docker, который вы используете для джобы, используйте wget или аналогичный инструмент.

   Вы также можете создать и использовать собственный образ Docker с allurectl.

4. Добавьте или расширьте блок variables. Он должен включать переменные со значениями:

   • ALLURE_ENDPOINT — URL-адрес инстанса ТестОпс.

   • ALLURE_PROJECT_ID — ID проекта ТестОпс.

   • ALLURE_RESULTS — путь к директории с результатами тестов (например, build/allure-results).

     Если в вашем проекте несколько директорий с результатами тестов, вы можете разделить их запятыми или использовать шаблон с подстановочными символами (например, modules/*/build/allure-results).

5. Оберните команду, которая запускает тесты, в команду ./allurectl watch.

Пример изменения пайплайна

Предположим, вы работаете с Java-проектом, в котором файл .gitlab-ci.yml выглядит следующим образом:

test:
  stage: test
  image: gradle
  script:
    - gradle clean test

Чтобы настроить интеграцию с ТестОпс, вам необходимо изменить файл по примеру ниже:

test:
  stage: test
  image: gradle
  variables:
    ALLURE_ENDPOINT: https://testops.example.com
    ALLURE_PROJECT_ID: 1
    ALLURE_RESULTS: build/allure-results
  before_script:
    - curl -fsSL https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_amd64 -o allurectl
    - chmod +x allurectl
  script:
    - ./allurectl watch -- gradle clean test

2.4. Запустите и проверьте пайплайн в GitLab

1. В GitLab откройте репозиторий, для которого вы настраиваете интеграцию.

2. Перейдите к запуску пайплайна, инициированному последним коммитом.

   Примечание

   Если у вас отключен автоматический запуск пайплайнов после коммитов, выполните запуск вручную.

3. Дождитесь, когда завершится выполнение пайплайна.

4. В деталях выполнения пайплайна нажмите на джобу, которая запускает тесты.

5. Ближе к концу лога найдите ссылку на запуск в ТестОпс.

   

6. Перейдите по ссылке в ТестОпс и откройте результаты одного из тестов.

7. В карточке результата теста в левом нижнем углу найдите ссылку на пайплайн GitLab.

   

8. Перейдите по ссылке в GitLab, чтобы убедиться, что она работает корректно.

2.5. Настройте джобу в ТестОпс

1. Перейдите в ваш проект ТестОпс.

2. Перейдите в раздел Джобы.

   В списке будет отображаться новая джоба, автоматически добавленная во время запуска на шаге 2.4.

3. Напротив добавленной джобы нажмите ⋯ → Настроить.

4. В появившемся окне заполните поля:

   • Название — введите название, которое поможет вам распознать джобу.
   • Сервер сборки — нажмите на выпадающий список и выберите название подключения к GitLab, которую вы добавили на шаге 1.2.
   • Джоба может быть использована для запуска тестов — поставьте галочку, чтобы пользователи могли запускать джобу из ТестОпс.

5. Нажмите Отправить.

3. Параметризируйте джобы

GitLab использует переменные окружения для передачи параметров в пайплайны. ТестОпс интегрирует эту функцию с собственной концепцией Окружения, которая позволяет вам как задавать параметры для новых джоб, так и видеть параметры, установленные для джоб, запущенных вне ТестОпс.

Важно

Если в репозитории вашего проекта есть несколько веток, обязательно создайте переменную окружения Branch в ТестОпс и передайте ее в вашу джобу. Это специальное имя укажет GitLab, какую из веток нужно использовать.

3.1. Установите значения по умолчанию в GitLab

Примечание

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

1. В GitLab откройте репозиторий, для которого вы настраиваете интеграцию.

2. Откройте файл .gitlab-ci.yml.

3. Добавьте переменные и их значения по умолчанию в блок variables пайплайна или джобы.

   Пример

   test:
     stage: test
     image: gradle
     variables:
       ALLURE_ENDPOINT: https://testops.example.com
       ALLURE_PROJECT_ID: 1
       ALLURE_RESULTS: build/allure-results
       PRODUCT_VERSION: "1.23"
       TESTS_BROWSER: chrome
     before_script:
       - curl -fsSL https://github.com/allure-framework/allurectl/releases/latest/download/allurectl_linux_amd64 -o allurectl
       - chmod +x allurectl
     script:
       - ./allurectl watch -- gradle clean test

3.2. Добавьте глобальные переменные окружения в ТестОпс

1. Перейдите в ваш инстанс ТестОпс.

2. Перейдите в раздел Администрирование → Окружения.

3. Для каждой переменной, которую вы хотите добавить:

   1. Нажмите + Создать.
   2. Введите глобальное название переменной.
   3. Нажмите Отправить.

   

3.3. Сопоставьте переменные окружения пайплайна с глобальными переменными окружения в ТестОпс

1. Перейдите в ваш проект ТестОпс.

2. Перейдите в раздел Настройки → Окружение.

3. Для каждой переменной, которую вы хотите использовать:

   1. Нажмите + Создать, если переменной нет в списке. Если переменная уже существует, напротив ее названия нажмите иконку Редактировать.
   2. В поле Ключ введите название переменной в Gitlab из шага 3.1.
   3. В поле Переменная окружения нажмите на выпадающий список и выберите глобальное название переменной в ТестОпс из шага 3.2.
   4. Нажмите Отправить.

   

3.4. Добавьте параметры в джобу ТестОпс

1. Перейдите в раздел Джобы.

2. Напротив джобы, которую вы хотите параметризировать, нажмите ⋯ → Настроить.

3. Для каждой переменной, которую вы хотите добавить, в секции Параметры нажмите Добавить и заполните поля:

   • Название — введите название переменной в GitLab из шага 3.1.
   • Значение — введите значение по умолчанию, такое же, как значение из шага 3.1.
   • Переменная окружения — нажмите на выпадающий список и выберите глобальное название переменной в ТестОпс из шага 3.2.

   

4. Нажмите Отправить.

Удаление интеграции

Вы можете удалить интеграцию с GitLab двумя способами — на уровне всего инстанса ТестОпс (через раздел Администрирование) или на уровне отдельного проекта (через настройки проекта).

Важно

Последствия удаления интеграции:

• Удаление на уровне инстанса — связь с инстансом GitLab будет удалена из всех джоб ТестОпс, которые относятся к интеграции:

  • Иконки для запуска и обновления этих джоб в разделе Джобы станут неактивными.
  • Результаты запусков тестов из GitLab не будут отправляться в инстанс ТестОпс.

• Удаление на уровне проекта — связь с инстансом GitLab будет удалена из джобы ТестОпс, которая относится к интеграции и находится в этом проекте:

  • Иконки для запуска и обновления этой джобы в разделе Джобы останутся активными.
  • ТестОпс не сможет запустить тесты из проекта на стороне GitLab. После закрытия запуска результаты этих тестов получат статус «Неизвестный».
  • Результаты запусков тестов из GitLab не будут отправляться в проект ТестОпс.

Во время удаления интеграции с CI-системой GitLab также будет удалена интеграция с таск-трекером GitLab. Подробнее о последствиях см. Интеграция с таск-трекером GitLab → Удаление интеграции.

1. В ТестОпс перейдите в раздел Администрирование → Интеграции.

2. В списке настроенных интеграций найдите и откройте интеграцию с GitLab.

3. В списке настроенных подключений найдите ваше подключение к GitLab и убедитесь, что оно не используется в проектах ТестОпс.

   Если интеграция подключена к проектам, удалите ее из них. Для этого откройте карточку подключения к GitLab и напротив названия каждого проекта нажмите ⋯ → Удалить из проекта → Да, удалить.

4. Напротив нужного подключения к GitLab нажмите ⋯ → Удалить → Да, удалить.