Как использовать Bencher в GitHub Actions
Depending on your use case, you can set up Continuous Benchmarking in GitHub Actions for your:
Make sure you have created an API token
and set it as a Repository secret named BENCHER_API_TOKEN
before continuing on!
Navigate to Your Repo -> Settings -> Secrets and variables -> Actions -> New repository secret
.
Name the secret BENCHER_API_TOKEN
and set the secret value to your API token.
In GitHub Actions,
secrets are not passed to the runner when a workflow is triggered from a forked repository.
Therefore, you will need to use a branch from the same repository
when adding any of the workflows below to your repository with a pull request.
If you try to add Bencher with a pull request from a fork,
then the BENCHER_API_TOKEN
secret will not be available.
${{ secrets.BENCHER_API_TOKEN }}
will be an empty string.
Основная ветка
Краеугольным камнем Статистического непрерывного бенчмаркинга является наличие исторического базового уровня для вашей основной ветки. Этот исторический базовый уровень затем может быть использован для обнаружения ухудшений производительности в Pull Requests.
- Создайте файл
workflow
для GitHub Actions. (например,.github/workflows/base_benchmarks.yml
) - Запустите при событиях
push
в веткуmain
. См. документацию GitHub Actionson
и документацию оpush
для GitHub Actions для получения общей информации. (например,on: push: branches: main
) - Создайте
job
для GitHub Actions. (например,jobs: benchmark_base_branch
) - Установите разрешения для
GITHUB_TOKEN
наwrite
дляchecks
. (например:permissions: checks: write
) - Установите тип машины, на которой будет выполняться задание.
См. документацию о
runs-on
для GitHub Actions для получения подробной информации. (например,runs-on: ubuntu-latest
) - Получите исходный код вашей основной ветки.
(например,
uses: actions/checkout@v4
) - Установите Bencher CLI, используя GitHub Action.
(например,
uses: bencherdev/bencher@main
) - Используйте подкaманды CLI
bencher run
для запуска бенчмарков вашей веткиmain
. См. подкaманды CLIbencher run
для получения полной информации. (например,bencher run
) - Установите опцию
--project
на шифр проекта. См. документацию о--project
для получения более подробной информации. (например,--project save-walter-white-1234abcd
) - Установите опцию
--token
на секрет RepositorийBENCHER_API_TOKEN
. См. документацию о--token
для получения более подробной информации. (например,--token '${{ secrets.BENCHER_API_TOKEN }}'
) - Установите опцию
--branch
на имя основной ветки. См. документацию о--branch
для получения полной информации. (например,--branch main
) - Установите опцию
--testbed
на имя Testbed. Это, вероятно, должно соответствовать машине, выбранной вruns-on
. См. документацию о--tested
для получения более подробной информации. (например,--testbed ubuntu-latest
) - Установите порог для ветки
main
, тестового стендаubuntu-latest
и измеренияlatency
:- Установите опцию
--threshold-measure
на встроенное измерениеlatency
, которое создаетсяbencher mock
. См. документацию о--threshold-measure
для получения более подробной информации. (например,--threshold-measure latency
) - Установите опцию
--threshold-test
на t-критерий Стьюдента (t_test
). См. документацию о--threshold-test
для получения полной информации. (например,--threshold-test t_test
) - Установите опцию
--threshold-max-sample-size
на максимальный размер выборки64
. См. документацию о--threshold-max-sample-size
для получения более подробной информации. (например,--threshold-max-sample-size 64
) - Установите опцию
--threshold-upper-boundary
на верхнюю границу0.99
. См. документацию о--threshold-upper-boundary
для получения более подробной информации. (например,--threshold-upper-boundary 0.99
) - Установите флаг
--thresholds-reset
, чтобы только указанное пороговое значение было активным. См. документацию о--thresholds-reset
для получения полной информации. (например,--thresholds-reset
)
- Установите опцию
- Установите флаг
--err
, чтобы команда завершалась с ошибкой, если будет сформировано оповещение. См. документацию о--err
для получения полной информации. (например,--err
) - Установите опцию
--adapter
на формат метрик Bencher в формате JSON (json
), который сгенерированbencher mock
. См. Адаптеры для бенчмарк-харнесов для получения полной информации. (например,--adapter json
) - Установите опцию
--github-actions
на токен аутентификации API GitHub, чтобы отправить результаты в виде комментария GitHub Checks, используя переменную окруженияGITHUB_TOKEN
для GitHub Actions. См. документацию о--github-actions
для получения более подробной информации. (например,--github-actions '${{ secrets.GITHUB_TOKEN }}'
) - Укажите аргументы для команды бенчмарков.
См. документацию о команде бенчмарков для получения полной информации.
(например,
bencher mock
)
Pull Requests
Чтобы отлавливать регрессии производительности в Pull Requests, вам нужно будет запускать свои тесты производительности на PRs.
Если вы ожидаете иметь PR только из веток внутри того же репозитория,
тогда вы можете просто создать другой workflow для запуска on
событий pull_request
из того же репозитория.
⚠️ Это решение работает только если все PR из того же репозитория! См. Pull Requests из Fork ниже.
-
Создайте файл
workflow
GitHub Actions. (пример:.github/workflows/pr_benchmarks.yml
) -
Запустите на событиях
pull_request
:opened
- Pull request был создан.reopened
- Ранее закрытый pull request был переоткрыт.edited
- Название или тело pull request было отредактировано, или базовая ветка pull request была изменена.synchronize
- Ветка head pull request была обновлена. Например, ветка head была обновлена из базовой ветки или новые коммиты были добавлены в ветку head.
См. документацию GitHub Actions
on
и документацию GitHub Actionspull_request
для полного обзора. (пример:on: pull_request: types: [opened, reopened, edited, synchronize]
) -
Создайте
job
GitHub Actions. (пример:jobs: benchmark_pr_branch
) -
Запустите на событиях
pull_request
только в том случае, если pull request из того же репозитория. ⚠️ НЕ УДАЛЯЙТЕ ЭТУ СТРОКУ! Для обработки Fork PRs см. Pull Requests из Fork ниже. (пример:if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
) -
Установите разрешения для
GITHUB_TOKEN
наwrite
дляpull-requests
. В зависимости от настроек GitHub, это может не требоваться. Но для всех организаций и личных репозиториев, созданных после 02 февраля 2023, это поведение является поведением по умолчанию. См. документацию GitHub для полного обзора. (пример:permissions: pull-requests: write
) -
Установите тип машины, на которой будет выполняться job. См. документацию GitHub Actions
runs-on
для полного обзора. (пример:runs-on: ubuntu-latest
) -
Проверьте исходный код ветки PR. (пример:
uses: actions/checkout@v4
) -
Установите Bencher CLI с использованием GitHub Action. (пример:
uses: bencherdev/bencher@main
) -
Используйте
bencher run
CLI подкоманду для запуска тестов производительности ветки pull request. См. подкомандуbencher run
CLI для полного обзора. (пример:bencher run
) -
Установите опцию
--project
на идентификатор проекта. См. документацию--project
для подробностей. (пример:--project save-walter-white-1234abcd
) -
Установите опцию
--token
на секрет репозиторияBENCHER_API_TOKEN
. См. документацию--token
для подробностей. (пример:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
Установите опцию
--branch
на имя ветки PR используя переменную окруженияGITHUB_HEAD_REF
по умолчанию GitHub Actions. См. документацию--branch
для полного обзора. (пример:--branch "$GITHUB_HEAD_REF"
) -
Установите начальную точку для ветки PR:
- Установите опцию
--start-point
на стартовую точку ветки PR используя переменную окруженияGITHUB_BASE_REF
по умолчанию GitHub Actions. См. документацию--start-point
для полного обзора. (пример:--start-point "$GITHUB_BASE_REF"
) - Установите опцию
--start-point-hash
наgit
хеш стартовой точки ветки PR используя событиеpull_request
GitHub Actions. См. документацию--start-point-hash
для полного обзора. (пример:--start-point-hash '${{ github.event.pull_request.base.sha }}'
) - Установите флаг
--start-point-clone-thresholds
, чтобы клонировать пороги из стартовой точки. См. документацию--start-point-clone-thresholds
для полного обзора. (пример:--start-point-clone-thresholds
) - Установите флаг
--start-point-reset
, чтобы всегда сбрасывать ветку PR в стартовую точку. Это предотвратит дрейф данных тестов производительности. См. документацию--start-point-reset
для полного обзора. (пример:--start-point-reset
)
- Установите опцию
-
Установите опцию
--testbed
на имя Testbed. Это, вероятно, должно совпадать с машиной, выбранной вruns-on
. См. документацию--testbed
для подробностей. (пример:--testbed ubuntu-latest
) -
Установите флаг
--err
, чтобы команда завершалась неудачей, если генерируется предупреждение. См. документацию--err
для полного обзора. (пример:--err
) -
Установите опцию
--adapter
на Bencher Metric Format JSON (json
), который генерируетсяbencher mock
. См. адаптеры тестовых сред для полного обзора. (пример:--adapter json
) -
Установите опцию
--github-actions
на токен аутентификации API GitHub для публикации результатов как комментарий к Pull Request с использованием переменной окруженияGITHUB_TOKEN
. См. документацию--github-actions
для подробностей. (пример:--github-actions '${{ secrets.GITHUB_TOKEN }}'
) -
Укажите аргументы команды теста производительности. См. команду теста производительности для полного обзора. (пример:
bencher mock
)
Чтобы очистить PR-ветку после закрытия PR, вы можете создать отдельный workflow, который будет запускаться on
событиях типа pull_request
с типом closed
. Этот workflow архивирует PR-ветку с помощью команды bencher archive
.
-
Создайте файл
workflow
для GitHub Actions. (например,.github/workflows/pr_benchmarks_closed.yml
) -
Запускать на событиях
pull_request
:closed
- запрос на включение изменений был закрыт.
См. документацию по GitHub Actions
on
и документацию по GitHub Actionspull_request
для полного обзора. (например,on: pull_request: types: [closed]
) -
Создайте
job
для GitHub Actions. (например,jobs: archive_pr_branch
) -
Запускайте на событиях
pull_request
только если запрос на включение изменений из того же репозитория. ⚠️ НЕ УДАЛЯЙТЕ ЭТУ СТРОКУ! Для обработки Fork PR см. ниже Запросы на включение изменений из форков. (например,if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
) -
Установите тип машины, на которой будет выполняться работа. См. документацию по GitHub Actions
runs-on
для полного обзора. (например,runs-on: ubuntu-latest
) -
Выполните проверку исходного кода PR-ветки. (например,
uses: actions/checkout@v4
) -
Установите Bencher CLI, используя GitHub Action. (например,
uses: bencherdev/bencher@main
) -
Используйте подкоманду CLI
bencher archive
для архивирования PR-ветки. (например,bencher archive
) -
Установите для опции
--project
значение идентификатора проекта (slug). См. документацию по--project
опции для более подробной информации. (например,--project save-walter-white-1234abcd
) -
Установите для опции
--token
значение секрета РепозиторияBENCHER_API_TOKEN
. См. документацию по--token
опции для более подробной информации. (например,--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
Установите для опции
--branch
значение имени PR-ветки, используя переменную среды по умолчанию GitHub ActionsGITHUB_HEAD_REF
. (например,--branch "$GITHUB_HEAD_REF"
)
Запросы на вытягивание из форков
Если вы планируете принимать запросы на вытягивание из форков, как это часто бывает в публичных open source проектах, то вам потребуется немного по-другому с этим справляться. По соображениям безопасности, такие данные, как ваш BENCHER_API_TOKEN
и GITHUB_TOKEN
, недоступны в GitHub Actions для запросов на вытягивание из форков. То есть, если внешний участник открывает PR из форка, приведенный выше пример не будет работать. Смотрите это описание безопасности от лаборатории GitHub и этот пост в блоге для полного обзора о предотвращении атак pwn requests.
Это безопасный и рекомендуемый способ добавления Непрерывного Бенчмаркинга к запросам на вытягивание из форков. Он требует двух отдельных рабочих процессов. Первый рабочий процесс запускается и кэширует результаты бенчмаркинга в контексте pull_request
. Там недоступны такие секреты, как ваш BENCHER_API_TOKEN
и GITHUB_TOKEN
. Затем второй рабочий процесс загружает кешированные результаты бенчмаркинга в контексте workflow_run
и загружает их в Bencher. Это работает, потому что workflow_run
запускается в контексте основной ветки репозитория, где доступны такие секреты, как ваш BENCHER_API_TOKEN
и GITHUB_TOKEN
. Номер запроса на вытягивание, ветка источника и базовая ветка, используемые в первоначальном рабочем процессе pull_request
, также должны быть явно переданы в рабочий процесс workflow_run
, так как они там недоступны. Эти рабочие процессы будут выполняться только если они существуют в основной ветке. Смотрите использование данных от запускающего рабочего процесса для полного обзора.
-
Создайте первый файл
workflow
GitHub Actions. (например:.github/workflows/fork_pr_benchmarks_run.yml
) -
Назовите этот workflow так, чтобы его можно было использовать во втором workflow. (например:
name: Run Benchmarks
) -
Запускайте на событиях
pull_request
:opened
- Создан новый pull request.reopened
- Повторно открыт ранее закрытый pull request.edited
- Изменен заголовок или тело pull request, или изменена базовая ветка pull request.synchronize
- Обновлена головная ветка pull request. Например, головная ветка была обновлена из базовой ветки или в головную ветку были отправлены новые коммиты.
См. документацию по
on
в GitHub Actions и документацию поpull_request
в GitHub Actions для полного обзора. (например:on: pull_request: types: [opened, reopened, edited, synchronize]
) -
Создайте
job
в GitHub Actions. (например:jobs: benchmark_fork_pr_branch
) -
Установите тип машины, на которой будет выполняться job. См. документацию по
runs-on
в GitHub Actions для полного обзора. (например:runs-on: ubuntu-latest
) -
Выполните checkout исходного кода ветки fork PR. (например:
uses: actions/checkout@v4
) -
Запустите тесты производительности и сохраните результаты в файл. (например:
/bin/echo '{ ... }' > benchmark_results.json
) -
Загрузите файл с результатами тестов производительности как артефакт. (например:
uses: actions/upload-artifact@v4
) -
Загрузите объект события
pull_request
как артефакт. (например:uses: actions/upload-artifact@v4
)
- Создайте первый файл
workflow
для GitHub Actions. (например,.github/workflows/fork_pr_benchmarks_track.yml
) - Назовите этот workflow вторым workflow.
(например,
name: Track Benchmarks with Bencher
) - Свяжите два workflow с помощью
события
workflow_run
. (например,on: workflow_run: ...
) - Создайте
job
для GitHub Actions. (например,jobs: track_fork_pr_branch
) - Запустите этот job только в случае успешного завершения предыдущего workflow, используя
событие
workflow_run
GitHub Actions. (например,if: github.event.workflow_run.conclusion == 'success'
) - Установите тип машины, на которой будет выполнено задание.
См. документацию GitHub Actions
runs-on
для полного обзора. (например,runs-on: ubuntu-latest
) - Установите результаты бенчмарков и имена файлов объекта события
pull_request
как переменные окружения. (например,env: ...
) - Скачайте кешированные результаты бенчмарков и событие
pull_request
используя действиеaction-download-artifact
GitHub Actions. (например,uses: dawidd6/action-download-artifact@v6
) - Экспортируйте необходимые данные из события
pull_request
как переменные окружения. (например,core.exportVariable(...)
) - Установите Bencher CLI, используя GitHub Action.
(например,
uses: bencherdev/bencher@main
) - Используйте подкоманду CLI
bencher run
для отслеживания бенчмарков ветки форка pull. См. подкоманду CLIbencher run
для полного обзора. (например,bencher run
) - Установите опцию
--project
на проектный ключ. См. документацию--project
для более подробной информации. (например,--project save-walter-white-1234abcd
) - Установите опцию
--token
на секретBENCHER_API_TOKEN
репозитория. См. документацию--token
для более подробной информации. (например,--token '${{ secrets.BENCHER_API_TOKEN }}'
) - Установите опцию
--branch
на имя ветки форка PR, используя промежуточную переменную окружения. См. документацию--branch
для полного обзора. (например,--branch "$PR_HEAD"
) - Установите начальную точку для ветки форка PR:
- Установите опцию
--start-point
на начальную точку ветки форка PR, используя промежуточную переменную окружения. См. документацию--start-point
для полного обзора. (например,--start-point "$PR_BASE"
) - Установите опцию
--start-point-hash
на хэшgit
начальной точки ветки форка PR, используя промежуточную переменную окружения. См. документацию--start-point-hash
для полного обзора. (например,--start-point-hash "$PR_BASE_SHA"
) - Установите флаг
--start-point-clone-thresholds
для клонирования порогов из начальной точки. См. документацию--start-point-clone-thresholds
для полного обзора. (например,--start-point-clone-thresholds
) - Установите флаг
--start-point-reset
для всегда сброса ветки форка PR к начальной точке. Это предотвратит смещение данных бенчмарков. См. документацию--start-point-reset
для полного обзора. (например,--start-point-reset
)
- Установите опцию
- Установите опцию
--testbed
на имя тестового стенда. Это, вероятно, должно совпадать с выбранной машиной вruns-on
. См. документацию--tested
для более подробной информации. (например,--testbed ubuntu-latest
) - Установите флаг
--err
для провала команды в случае генерации Предупреждения. См. документацию--err
для полного обзора. (например,--err
) - Установите опцию
--adapter
на Bencher Metric Format JSON (json
), который генерируетсяbencher mock
. См. бенчмаркинг адаптеров для полного обзора. (например,--adapter json
) - Установите опцию
--github-actions
на токен аутентификации GitHub API для размещения результатов в комментарии к Pull Request, используя переменную окруженияGITHUB_TOKEN
GitHub Actions. См. документацию--github-actions
для более подробной информации. (например,--github-actions '${{ secrets.GITHUB_TOKEN }}'
) - Установите опцию
--ci-number
на номер pull request, используя промежуточную переменную окружения. См. документацию--ci-number
для более подробной информации. (например,--ci-number "$PR_NUMBER"
) - Установите опцию
--file
на путь к файлу результатов бенчмарков. См. команду бенчмаркинга для полного обзора. (например,--file "$BENCHMARK_RESULTS"
)
Чтобы очистить ветку PR форка после закрытия её PR, вы можете создать отдельный рабочий процесс, который будет запускаться на события pull_request_target
с типом closed
. Этот рабочий процесс заархивирует ветку PR форка с помощью команды bencher archive
.
-
Создайте файл
workflow
для GitHub Actions. (например,.github/workflows/fork_pr_benchmarks_closed.yml
) -
Запускайте на событиях
pull_request_target
:closed
- Пул-реквест был закрыт.
См. документацию по GitHub Actions
on
и документацию по GitHub Actionspull_request_target
для полного обзора. (например,on: pull_request_target: types: [closed]
) -
Создайте задание
job
для GitHub Actions. (например,jobs: archive_pr_branch
) -
Установите тип машины, на которой будет выполнено задание. См. документацию по GitHub Actions
runs-on
для полного обзора. (например,runs-on: ubuntu-latest
) -
Выполните проверку исходного кода ветки PR. (например,
uses: actions/checkout@v4
) -
Установите Bencher CLI, используя действие GitHub Action. (например,
uses: bencherdev/bencher@main
) -
Используйте подкоманду CLI
bencher archive
для архивирования ветки PR. (например,bencher archive
) -
Установите опцию
--project
на идентификатор проекта. Подробнее см. в документации по--project
. (например,--project save-walter-white-1234abcd
) -
Установите опцию
--token
на секрет репозиторияBENCHER_API_TOKEN
. Подробнее см. в документации по--token
. (например,--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
Установите опцию
--branch
на имя ветки PR, используя переменную среды по умолчаниюGITHUB_HEAD_REF
для GitHub Actions. (например,--branch "$GITHUB_HEAD_REF"
)
🐰 Поздравляем! Вы научились использовать Bencher в GitHub Actions! 🎉