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

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

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

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

Поддерживаются как основной сервер GitHub (github.com), так и инстансы GitHub Enterprise Server.

Примечание

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

  • Администрирование — необходимы права администратора инстанса;
  • Настройки в конкретном проекте — необходима роль владельца этого проекта.

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

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

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

    1. Создайте токен в GitHub.

    2. На уровне инстанса ТестОпс добавьте интеграцию с GitHub, указав:

      • название интеграции;
      • URL-адрес GitHub;
      • URL-адрес GitHub API.

    3. На уровне инстанса или проекта ТестОпс включите добавленную интеграцию для проекта, указав созданный токен из GitHub.

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

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

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

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

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

GitHub поддерживает два типа токенов доступа: fine-grained и classic (см. Managing your personal access tokens в документации GitHub). Для интеграции с ТестОпс вы можете использовать любой тип токена.

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

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

  3. В сайдбаре слева перейдите в раздел Personal access tokens → Fine-grained tokens.

  4. Нажмите Generate new token.

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

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

  6. В секции Repository access выберите один из вариантов:

    • All repositories — предоставить токену доступ ко всем репозиториям. Этот вариант подходит, если вы планируете настроить интеграцию для всего инстанса GitHub.
    • Only select repositories — предоставить токену доступ только к определенным репозиториям. В появившемся выпадающем списке выберите репозитории, содержащие workflow, которые вы планируете использовать.

  7. В секции Permissions нажмите + Add permissions.

  8. В списке доступных разрешений поставьте галочку напротив Actions.

    Чтобы закрыть список, нажмите вне его области.

  9. В списке добавленных разрешений напротив Actions выберите уровень доступа Access: Read and write.

  10. Нажмите Generate token.

  11. В открывшемся окне подтверждения повторно нажмите Generate token.

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

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

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

1.2. Добавьте интеграцию с GitHub в ТестОпс ​

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

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

  3. Нажмите + Добавить интеграцию в правом верхнем углу.

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

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

    • Название — название, которое поможет вам распознать интеграцию, например, GitHub production.

    • Endpoint — базовый URL-адрес GitHub:

      • Для github.com используйте https://github.com.
      • Для GitHub Enterprise Server используйте URL-адрес вашего инстанса GitHub.

    • Endpoint для вызовов API — URL-адрес GitHub API:

      • Для github.com убедитесь, что указано https://api.github.com.
      • Для GitHub Enterprise Server используйте ⟨URL-адрес вашего инстанса GitHub⟩/api/v3.

  6. Если вы используете GitHub Enterprise Server с самоподписанным SSL-сертификатом, поставьте галочку напротив Отключить проверку сертификата.

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

1.3. Включите интеграцию для проекта ТестОпс ​

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

  1. Перейдите в раздел Администрирование → Интеграции.
  2. В списке настроенных интеграций найдите и откройте вашу интеграцию с GitHub.
  3. Перейдите на вкладку Проекты.
  4. Справа от поля поиска нажмите +.
  5. В выпадающем списке Проект выберите нужный проект ТестОпс.
  6. В секции Секрет введите токен доступа GitHub, который вы сохранили на шаге 1.1.
  7. Нажмите Проверить соединение. Если токен указан верно, через несколько секунд появится сообщение «Соединение установлено».
  8. Нажмите Добавить интеграцию.

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

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

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

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

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

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

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

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

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

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

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

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

  2. Перейдите на вкладку Settings.

  3. В сайдбаре слева перейдите в раздел Secrets and variables → Actions.

  4. Нажмите New repository secret.

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

    • Name — ALLURE_TOKEN.
    • Secret — API-токен, который вы сохранили на шаге 2.1.

  6. Нажмите Add secret.

2.3. Измените workflow в GitHub ​

Примечание

Вам необходимо изменить каждый workflow, который запускает тесты и участвует в интеграции.

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

  2. Перейдите в директорию .github/workflows.

  3. Откройте YAML-файл вашего workflow.

  4. В блоке workflow_dispatch → inputs добавьте параметры:

    • ALLURE_JOB_RUN_ID,
    • ALLURE_USERNAME.

    Важно

    Для обоих параметров укажите атрибут required в значении false. Это означает, что параметры можно оставить пустыми при запуске workflow в GitHub, но они должны быть обязательно определены. Без этих параметров запуск workflow со стороны ТестОпс не будет работать и вы получите ошибку 422. Подробнее см. Устранение неполадок.

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

    • ALLURE_ENDPOINT — URL-адрес инстанса ТестОпс.
    • ALLURE_PROJECT_ID — ID проекта ТестОпс.
    • ALLURE_TOKEN — ${{ secrets.ALLURE_TOKEN }}.
    • ALLURE_JOB_RUN_ID — ${{ github.event.inputs.ALLURE_JOB_RUN_ID }}.
    • ALLURE_RESULTS — путь к директории с результатами тестов (например, build/allure-results). Если в вашем репозитории несколько директорий с результатами тестов, вы можете разделить их запятыми или использовать шаблон с подстановочными символами (например, modules/*/build/allure-results).

  6. Перед командой запуска тестов добавьте шаг, загружающий allurectl.

    Совет

    Рекомендуем использовать готовый GitHub Action allure-framework/setup-allurectl@v1.

    Вариант загрузки и настройки allurectl без использования GitHub Action описан в примерах ниже.

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

    Если ваш инстанс ТестОпс использует самоподписанный SSL-сертификат, используйте вместо этого команду allurectl --insecure watch.

Пример изменения workflow

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

yaml
name: Run tests

on:
  push:

jobs:
  all-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up JDK
        uses: actions/setup-java@v3
        with:
          distribution: oracle
          java-version: 17

      - name: Build with Gradle
        run: ./gradlew clean test

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

yaml
name: Run tests

on:
  push:
  workflow_dispatch:
    inputs:
      ALLURE_JOB_RUN_ID:
        description: "TestOps service parameter. Leave blank"
        required: false
      ALLURE_USERNAME:
        description: "TestOps service parameter. Leave blank"
        required: false

env:
  ALLURE_ENDPOINT: https://testops.example.com
  ALLURE_PROJECT_ID: 1
  ALLURE_TOKEN: ${{ secrets.ALLURE_TOKEN }}
  ALLURE_JOB_RUN_ID: ${{ github.event.inputs.ALLURE_JOB_RUN_ID }}
  ALLURE_RESULTS: "build/allure-results"

jobs:
  all-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up JDK
        uses: actions/setup-java@v3
        with:
          distribution: oracle
          java-version: 17

      - name: Install allurectl
        uses: allure-framework/setup-allurectl@v1

      - name: Build with Gradle
        run: allurectl watch -- ./gradlew clean test

2.4. Запустите и проверьте workflow в GitHub ​

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

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

    Примечание

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

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

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

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

    Ссылка на запуск ТестОпс находится в логах запуска workflow.

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

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

    Ссылка на workflow GitHub находится в карточке результата теста в левом нижнем углу.

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

3. Параметризируйте джобу в ТестОпс и workflow в GitHub ​

GitHub использует блок inputs в YAML-файле для передачи параметров в контекст workflow. Чтобы параметризировать workflow, необходимо добавить нужные параметры в этот блок и затем указать их в блоке env. Это позволит использовать указанные параметры как переменные окружения в тестах.

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

3.1. Укажите параметры в workflow GitHub ​

Примечание

Вам необходимо изменить каждый workflow, который запускает тесты и участвует в интеграции.

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

  2. Перейдите в директорию .github/workflows.

  3. Откройте YAML-файл вашего workflow.

  4. Добавьте параметры для запуска workflow, их описания и значения по умолчанию в блок inputs. Например:

    yaml
    name: Run tests

on:
  workflow_dispatch:
    inputs:
      <...>
      TESTS_BROWSER:
        description: "Browser to use for tests"
        required: true
        default: "chrome"
      PRODUCT_VERSION:
        description: "Product version"
        required: true
        default: "1.23"

  5. Укажите эти же значения в блоке env для передачи информации в ваши тесты через переменные окружения. Например:

    yaml
    env:
  <...>
  TESTS_BROWSER: ${{ github.event.inputs.TESTS_BROWSER }}
  PRODUCT_VERSION: ${{ github.event.inputs.PRODUCT_VERSION }}

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

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

Перед тем как использовать значения переменных окружения из workflow GitHub, создайте глобальные переменные окружения на уровне инстанса ТестОпс, которые будут хранить эти данные:

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

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

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

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

    Названия переменных окружения добавляются в разделе «Администрирование».

    Важно

    Обязательно создайте глобальную переменную окружения Branch, так как она необходима для работы ТестОпс с API GitHub. Без нее запуск workflow из интерфейса ТестОпс будет невозможен.

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

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

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

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

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

    Сопоставление переменных окружения GitHub и ТестОпс находится в настройках проекта.

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

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

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

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

    • Название — название переменной в GitHub из шага 3.1.

    • Значение — значение по умолчанию, которое должно использоваться, если не указано другое значение для конкретного запуска.

      Примечание

      Обратите внимание, что рекомендуется устанавливать одинаковые значения по умолчанию как в ТестОпс, так и в GitHub. В таком случае запуск workflow получит одно и то же окружение независимо от источника запуска.

      Подробнее о настройке джобы см. Джобы → Параметры джобы.

    • Переменная окружения — глобальное название переменной в ТестОпс из шага 3.2.

    В окне можно указать несколько переменных окружения.

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

3.5. Запустите workflow через ТестОпс ​

На предыдущих шагах вы настроили джобу в ТестОпс, указав все параметры, которые нужно передавать в workflow GitHub. Эти параметры будут использоваться при запуске workflow из интерфейса ТестОпс.

Параметры указаны рядом с названием джобы.

Чтобы выполнить тесты в определенном окружении:

  1. Создайте запуск в интерфейсе ТестОпс любым из доступных способов (подробнее см. Запуски → Создание запуска для тестовых прогонов, инициированных из ТестОпс).

  2. В окне создания запуска в секции Окружение нажмите Добавить.

    ТестОпс добавит параметры джобы в форму и заполнит их значениями по умолчанию.

    Значения параметров можно ввести или выбрать из списка.

  3. При необходимости измените указанные значения параметров.

    Если вам нужно запустить workflow несколько раз с разным окружением, создайте новые наборы переменных окружения. В этом случае ТестОпс отправит запрос в GitHub на выполнение нескольких workflow с различными параметрами.

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

Примеры workflow GitHub ​

Как упоминалось выше, allurectl можно добавить в workflow двумя способами:

  • Через GitHub Action allure-framework/setup-allurectl@v1, который:

    1. Скачивает allurectl.
    2. Создает параметры на основе контекста workflow или данных, полученных от ТестОпс.
    3. Передает параметры конфигурации, необходимые для загрузки результатов тестов.

  • Через скрипт внутри workflow (если GitHub Action недоступен или ограничен), который:

    1. Скачивает allurectl.
    2. Создает необходимые параметры на основе контекста workflow.

Ниже приведены примеры простых workflow с использованием GitHub Action allure-framework/setup-allurectl@v1 и скрипта внутри workflow. В них используется pytest и показаны все элементы, необходимые для корректной передачи результатов тестов из GitHub в ТестОпс и запуска workflow из интерфейса ТестОпс.

yaml
name: run-and-upload-to-testops

on:
  workflow_dispatch:
    inputs:
      TESTS_ENDPOINT:
        description: "System under test"
        required: true
        default: https://system.under.test
      TESTS_BROWSER:
        description: "Browser to be used in tests"
        required: true
        default: chrome
      ALLURE_JOB_RUN_ID:
        description: "TestOps service parameter. Leave blank"
        required: false
      ALLURE_USERNAME:
        description: "TestOps service parameter. Leave blank"
        required: false

env:
  ALLURE_RESULTS: "allure-results"
  ALLURE_JOB_RUN_ID: ${{ github.event.inputs.ALLURE_JOB_RUN_ID }}

jobs:
  all-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install dependencies for pytest and allure framework integration
        run: |
          python -m pip install --upgrade pip
          pip install allure-pytest pytest
      - name: install and configure allurectl using GH Action
        uses: allure-framework/setup-allurectl@v1
        with:
          allure-endpoint: https://testops.example.com
          allure-token: ${{ secrets.ALLURE_TOKEN }}
          allure-project-id: 9999
      - name: Run pytest tests
        run: |
          allurectl watch -- pytest ./test --alluredir=${ALLURE_RESULTS} --capture=no || true
        env:
          TESTS_ENDPOINT: ${{ github.event.inputs.TESTS_ENDPOINT }}
          TESTS_BROWSER: ${{ github.event.inputs.TESTS_BROWSER }}
          GITHUB_TESTS_BRANCH: ${{ github.ref_name }}

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

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

Важно

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

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

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

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

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

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

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

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

  3. Перейдите на вкладку Проекты и убедитесь, что интеграция не используется в проектах ТестОпс.

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

  4. Перейдите на вкладку Конфигурация.

  5. Нажмите Удалить интеграцию.

  6. Нажмите Удалить.

Устранение неполадок ​

Ошибка 422 при запуске workflow GitHub через интерфейс ТестОпс ​

Обычно ошибка 422 возникает при попытке запустить GitHub workflow, использующий workflow_dispatch, если параметры, определенные в блоке workflow_dispatch → inputs, не совпадают с параметрами, передаваемыми из джобы ТестОпс.

Как упоминалось выше, чтобы ТестОпс мог запускать workflow GitHub, в блоке inputs должны быть указаны два обязательных параметра:

  • ALLURE_JOB_RUN_ID,
  • ALLURE_USERNAME.

Оба параметра должны иметь атрибут required в значении false. На стороне ТестОпс эти параметры устанавливаются автоматически, без участия пользователя, поэтому их не нужно указывать в параметрах джобы ТестОпс.

Если логика вашего workflow GitHub требует дополнительных обязательных данных (например, название браузера или название системы для тестирования), эти параметры должны быть настроены в ТестОпс как параметры конфигурации джобы.

Пример конфигурации workflow с обязательными параметрами

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

yaml
name: Integration of TestOps with GitHub
on:
  workflow_dispatch:
    inputs:
      ALLURE_JOB_RUN_ID:
        description: "TestOps service parameter. Leave blank."
        required: false
      ALLURE_USERNAME:
        description: "TestOps service parameter. Leave blank"
        required: false
      TEST_BROWSER:
        description: "Browser for tests"
        required: true
        default: chrome
      TEST_ENDPOINT:
        description: "System under test"
        required: false
        default: https://staging.system.under.test

В этом случае в ТестОпс в настройках джобы должны быть указаны два обязательных параметра:

  1. TEST_BROWSER — обязателен, так как в workflow_dispatch определен атрибутом required в значении true.
  2. Branch — обязателен, несмотря на то, что не указан явно в блоке inputs. Этот параметр связан с переменной окружения Branch в GitHub (в обоих случаях используется заглавная буква B), а его значение требуется для работы API GitHub (используется в параметре ref).

Параметр TEST_ENDPOINT в настройках джобы ТестОпс может быть добавлен опционально, так как в workflow_dispatch определен атрибутом required в значении false.

Примеры поведения GitHub при попытке запустить настроенную джобу:

Результат запускаКонфигурация джобы в ТестОпс
Будет работать корректно.
Все параметры присутствуют в workflow_dispatch → inputs		В окне конфигурации джобы указаны все обязательные параметры.
Будет работать корректно.
Присутствует параметр TEST_BROWSER, обязательный в workflow_dispatch → inputs		В окне конфигурации джобы указаны все обязательные параметры.
Не будет работать, ошибка 422.
Параметр RELEASE_ID отсутствует в workflow_dispatch → inputs		В окне конфигурации джобы указан параметр, отсутствующий в inputs.
Не будет работать, ошибка 422.
Отсутствует параметр TEST_BROWSER, обязательный в workflow_dispatch → inputs		В окне конфигурации джобы отсутствует обязательный параметр "TEST_BROWSER".

Чтобы исправить ошибку 422, синхронизируйте параметры джобы ТестОпс с параметрами workflow GitHub, указанными в workflow_dispatch → inputs.

Logo © 2025 Все права защищены. Сайт принадлежит компании ООО «Инструменты тестирования»