Como usar o Bencher no GitHub Actions
Dependendo do seu caso de uso, você pode configurar Benchmarking Contínuo no GitHub Actions para o seu:
Certifique-se de criar um token de API e configurá-lo como um segredo de Repositório chamado BENCHER_API_TOKEN
antes de continuar! Navegue até Seu Repositório -> Configurações -> Segredos e variáveis -> Ações -> Novo segredo de repositório
. Nomeie o segredo como BENCHER_API_TOKEN
e defina o valor do segredo para o seu token de API.
No GitHub Actions, segredos não são passados para o runner quando um workflow é acionado a partir de um repositório bifurcado. Portanto, você precisará usar um branch do mesmo repositório ao adicionar qualquer um dos workflows abaixo ao seu repositório com um pull request. Se você tentar adicionar o Bencher com um pull request de um fork, então o segredo BENCHER_API_TOKEN
não estará disponível. ${{ secrets.BENCHER_API_TOKEN }}
será uma string vazia.
Ramificação Base
Um alicerce do Benchmarking Estatístico Contínuo é ter uma linha de base histórica para sua ramificação base. Essa linha de base histórica pode então ser usada para detectar regressões de desempenho nos Pull Requests.
- Crie um arquivo
workflow
do GitHub Actions. (ex:.github/workflows/base_benchmarks.yml
) - Execute em eventos de
push
para a ramificaçãomain
. Veja a documentação deon
do GitHub Actions e a documentação depush
do GitHub Actions para uma visão geral completa. (ex:on: push: branches: main
) - Crie um
job
do GitHub Actions. (ex:jobs: benchmark_base_branch
) - Defina o tipo de máquina em que o job será executado.
Veja a documentação de
runs-on
do GitHub Actions para uma visão geral completa. (ex:runs-on: ubuntu-latest
) - Faça o checkout do código-fonte da sua ramificação base.
(ex:
uses: actions/checkout@v4
) - Instale o Bencher CLI usando a Ação do GitHub.
(ex:
uses: bencherdev/bencher@main
) - Use o subcomando
bencher run
do CLI para executar os benchmarks da sua ramificaçãomain
. Veja o subcomandobencher run
do CLI para uma visão geral completa. (ex:bencher run
) - Configure a opção
--project
para o slug do Projeto. Veja os documentos de--project
para mais detalhes. (ex:--project save-walter-white-1234abcd
) - Configure a opção
--token
para o segredo RepositorioBENCHER_API_TOKEN
. Veja os documentos de--token
para mais detalhes. (ex:--token '${{ secrets.BENCHER_API_TOKEN }}'
) - Configure a opção
--branch
para o nome da Ramificação base. Veja os documentos de--branch
para uma visão geral completa. (ex:--branch main
) - Configure a opção
--testbed
para o nome do Testbed. Isso deve provavelmente coincidir com a máquina selecionada emruns-on
. Veja os documentos de--tested
para mais detalhes. (ex:--testbed ubuntu-latest
) - Configure o Limite para a Ramificação
main
, Testbedubuntu-latest
, e Medidalatency
:- Configure a opção
--threshold-measure
para a medidalatency
embutida que é gerada porbencher mock
. Veja os documentos de--threshold-measure
para mais detalhes. (ex:--threshold-measure latency
) - Configure a opção
--threshold-test
para um teste-t de Student (t_test
). Veja os documentos de--threshold-test
para uma visão geral completa. (ex:--threshold-test t_test
) - Configure a opção
--threshold-max-sample-size
para o tamanho máximo da amostra de64
. Veja os documentos de--threshold-max-sample-size
para mais detalhes. (ex:--threshold-max-sample-size 64
) - Configure a opção
--threshold-upper-boundary
para o Limite Superior de0.99
. Veja os documentos de--threshold-upper-boundary
para mais detalhes. (ex:--threshold-upper-boundary 0.99
) - Defina a flag
--thresholds-reset
para que somente o Limite especificado esteja ativo. Veja os documentos de--thresholds-reset
para uma visão geral completa. (ex:--thresholds-reset
)
- Configure a opção
- Defina a flag
--err
para falhar o comando se um Alerta for gerado. Veja os documentos de--err
para uma visão geral completa. (ex:--err
) - Configure a opção
--adapter
para o Bencher Metric Format JSON (json
) que é gerado porbencher mock
. Veja adapters do harness de benchmark para uma visão geral completa. (ex:--adapter json
) - Configure a opção
--github-actions
para o token de autenticação da API do GitHub para publicar resultados como um comentário de Checks do GitHub usando a variável de ambienteGITHUB_TOKEN
do GitHub Actions. Veja os documentos de--github-actions
para mais detalhes. (ex:--github-actions '${{ secrets.GITHUB_TOKEN }}'
) - Especifique os argumentos do comando de benchmark.
Veja comando de benchmark para uma visão geral completa.
(ex:
bencher mock
)
Pull Requests
Para identificar regressões de desempenho em Pull Requests, você precisará executar seus benchmarks nos PRs.
Se você espera ter PRs apenas de branches dentro do mesmo repositório,
então pode simplesmente criar outro fluxo de trabalho para rodar eventos on
pull_request
do mesmo repositório.
⚠️ Esta solução só funciona se todos os PRs forem do mesmo repositório! Veja Pull Requests a partir de Forks abaixo.
-
Crie um arquivo
workflow
do GitHub Actions. (ex:.github/workflows/pr_benchmarks.yml
) -
Execute em eventos
pull_request
:opened
- Um pull request foi criado.reopened
- Um pull request previamente fechado foi reaberto.edited
- O título ou corpo de um pull request foi editado, ou o branch base de um pull request foi alterado.synchronize
- Um branch de cabeça de pull request foi atualizado. Por exemplo, o branch de cabeça foi atualizado a partir do branch base ou novos commits foram enviados ao branch de cabeça.
Veja a documentação
on
do GitHub Actions e a documentaçãopull_request
do GitHub Actions para uma visão geral completa. (ex:on: pull_request: types: [opened, reopened, edited, synchronize]
) -
Crie um
job
do GitHub Actions. (ex:jobs: benchmark_pr_branch
) -
Execute em eventos
pull_request
se e somente se o pull request for do mesmo repositório. ⚠️ NÃO REMOVA ESTA LINHA! Para lidar com Fork PRs veja Pull Requests a partir de Forks abaixo. (ex:if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
) -
Defina as permissões para o
GITHUB_TOKEN
comowrite
parapull-requests
. Dependendo das suas configurações no GitHub, isso pode não ser necessário. Mas para todas as organizações e repositórios pessoais criados após 02 de fevereiro de 2023, esse é o comportamento padrão. Veja a documentação do GitHub para uma visão geral completa. (ex:permissions: pull-requests: write
) -
Defina o tipo de máquina em que o trabalho será executado. Veja a documentação
runs-on
do GitHub Actions para uma visão geral completa. (ex:runs-on: ubuntu-latest
) -
Faça o checkout do código fonte do branch do PR. (ex:
uses: actions/checkout@v4
) -
Instale o Bencher CLI usando a GitHub Action. (ex:
uses: bencherdev/bencher@main
) -
Use o subcomando CLI
bencher run
para rodar seus benchmarks do branch de pull request. Veja o subcomando CLIbencher run
para uma visão geral completa. (ex:bencher run
) -
Defina a opção
--project
para o slug do Projeto. Veja a documentação--project
para mais detalhes. (ex:--project save-walter-white-1234abcd
) -
Defina a opção
--token
para o segredo de RepositórioBENCHER_API_TOKEN
. Veja a documentação--token
para mais detalhes. (ex:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
Defina a opção
--branch
para o nome do branch do PR usando o contextogithub
do GitHub Actions. Veja a documentação--branch
para uma visão geral completa. (ex:--branch '${{ github.head_ref }}'
) -
Defina o Ponto Inicial para o Branch do PR:
- Defina a opção
--start-point
para o ponto inicial do Branch do PR usando o contextogithub
do GitHub Actions. Veja a documentação--start-point
para uma visão geral completa. (ex:--start-point '${{ github.base_ref }}'
) - Defina a opção
--start-point-hash
para ogit
hash do ponto inicial do Branch do PR usando o eventopull_request
do GitHub Actions. Veja a documentação--start-point-hash
para uma visão geral completa. (ex:--start-point-hash '${{ github.event.pull_request.base.sha }}'
) - Defina a flag
--start-point-clone-thresholds
para clonar os Limiares do ponto inicial. Veja a documentação--start-point-clone-thresholds
para uma visão geral completa. (ex:--start-point-clone-thresholds
) - Defina a flag
--start-point-reset
para sempre redefinir o Branch do PR para o ponto inicial. Isso evitará o desvio de dados de benchmark. Veja a documentação--start-point-reset
para uma visão geral completa. (ex:--start-point-reset
)
- Defina a opção
-
Defina a opção
--testbed
para o nome do Testbed. Este provavelmente deve coincidir com a máquina selecionada emruns-on
. Veja a documentação--tested
para mais detalhes. (ex:--testbed ubuntu-latest
) -
Defina a flag
--err
para falhar o comando se um Alerta for gerado. Veja a documentação--err
para uma visão geral completa. (ex:--err
) -
Defina a opção
--adapter
para Formato de Métrica Bencher JSON (json
) que é gerado porbencher mock
. Veja adapters de benchmarks para uma visão geral completa. (ex:--adapter json
) -
Defina a opção
--github-actions
para o token de autenticação da API do GitHub para postar resultados como um comentário no Pull Request usando a variável de ambienteGITHUB_TOKEN
do GitHub Actions. Veja a documentação--github-actions
para mais detalhes. (ex:--github-actions '${{ secrets.GITHUB_TOKEN }}'
) -
Especifique os argumentos do comando do benchmark. Veja comando do benchmark para uma visão geral completa. (ex:
bencher mock
)
Para limpar a branch do PR após seu fechamento,
você pode criar um fluxo de trabalho separado para executar on
eventos de pull_request
com o tipo closed
.
Este fluxo de trabalho arquivará a branch do PR usando o comando bencher archive
.
-
Crie um arquivo de
workflow
do GitHub Actions. (ex:.github/workflows/pr_benchmarks_closed.yml
) -
Execute em eventos de
pull_request
:closed
- Um pull request foi fechado.
Veja a documentação do GitHub Actions
on
e a documentação dopull_request
do GitHub Actions para uma visão geral completa. (ex:on: pull_request: types: [closed]
) -
Crie um
job
do GitHub Actions. (ex:jobs: archive_pr_branch
) -
Execute em eventos de
pull_request
se e somente se o pull request for do mesmo repositório. ⚠️ NÃO REMOVA ESTA LINHA! Para lidar com PRs de Forks veja Pull Requests de Forks abaixo. (ex:if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
) -
Defina as permissões para o
GITHUB_TOKEN
comowrite
parapull-requests
. Dependendo das suas configurações do GitHub, isso pode não ser necessário. Mas para todas as organizações e repositórios pessoais criados após 02 de fevereiro de 2023, este é o comportamento padrão. Veja a documentação do GitHub para uma visão geral completa. (ex:permissions: pull-requests: write
) -
Defina o tipo de máquina no qual o job será executado. Veja a documentação do
runs-on
do GitHub Actions para uma visão geral completa. (ex:runs-on: ubuntu-latest
) -
Faça checkout do código fonte da branch do PR. (ex:
uses: actions/checkout@v4
) -
Instale o Bencher CLI usando a Ação do GitHub. (ex:
uses: bencherdev/bencher@main
) -
Use o subcomando
bencher archive
da CLI para arquivar a branch do PR. (ex:bencher archive
) -
Defina a opção
--project
para o slug do Projeto. Veja os documentos do--project
para mais detalhes. (ex:--project save-walter-white-1234abcd
) -
Defina a opção
--token
para o segredo RepositórioBENCHER_API_TOKEN
. Veja os documentos do--token
para mais detalhes. (ex:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
Defina a opção
--branch
para o nome da branch do PR usando o contextogithub
do GitHub Actions. (ex:--branch '${{ github.head_ref }}'
)
Pull Requests de Forks
Se você planeja aceitar pull requests de forks, como é frequentemente o caso em projetos de código aberto público, então você precisará lidar com as coisas de maneira um pouco diferente. Por razões de segurança, segredos como seu BENCHER_API_TOKEN
e o GITHUB_TOKEN
não estão disponíveis no GitHub Actions para PRs de fork. Ou seja, se um colaborador externo abrir um PR a partir de um fork, o exemplo acima não funcionará. Veja este artigo do GitHub Security Lab e esta postagem no blog sobre como prevenir requests maliciosos para uma visão completa.
Esta é a maneira segura e sugerida de adicionar Benchmarking Contínuo a pull requests de forks. Requer dois fluxos de trabalho separados. O primeiro fluxo de trabalho executa e armazena em cache os resultados do benchmark no contexto pull_request
. Nenhum segredo, como seu BENCHER_API_TOKEN
e o GITHUB_TOKEN
, está disponível lá. Então, um segundo fluxo de trabalho baixa os resultados do benchmark em cache no contexto workflow_run
e os envia para o Bencher. Isso funciona porque workflow_run
é executado no contexto do branch padrão do repositório, onde segredos como seu BENCHER_API_TOKEN
e o GITHUB_TOKEN
estão disponíveis. O número do pull request, o branch head e o branch base usados no fluxo de trabalho inicial pull_request
também devem ser explicitamente passados para o fluxo de trabalho workflow_run
, pois não estão disponíveis lá. Esses fluxos de trabalho só serão executados se existirem no branch padrão. Veja usando dados do workflow que disparou a execução para uma visão completa.
-
Crie um primeiro arquivo de
workflow
do GitHub Actions. (ex:.github/workflows/fork_pr_benchmarks_run.yml
) -
Nomeie esse workflow para que ele possa ser referenciado pelo segundo workflow. (ex:
name: Run Benchmarks
) -
Execute em eventos de
pull_request
:opened
- Um pull request foi criado.reopened
- Um pull request anteriormente fechado foi reaberto.edited
- O título ou corpo de um pull request foi editado, ou o branch base de um pull request foi alterado.synchronize
- O branch head de um pull request foi atualizado. Por exemplo, o branch head foi atualizado do branch base ou novos commits foram enviados para o branch head.
Consulte a documentação de
on
do GitHub Actions e a documentação depull_request
do GitHub Actions para uma visão completa. (ex:on: pull_request: types: [opened, reopened, edited, synchronize]
) -
Crie um
job
do GitHub Actions. (ex:jobs: benchmark_fork_pr_branch
) -
Defina o tipo de máquina em que o job será executado. Consulte a documentação de
runs-on
do GitHub Actions para uma visão completa. (ex:runs-on: ubuntu-latest
) -
Faça o checkout do código-fonte do fork PR. (ex:
uses: actions/checkout@v4
) -
Execute seus benchmarks e salve os resultados em um arquivo. (ex:
/bin/echo '{ ... }' > benchmark_results.json
) -
Envie o arquivo de resultados de benchmark como um artefato. (ex:
uses: actions/upload-artifact@v4
) -
Envie o objeto de evento
pull_request
como um artefato. (ex:uses: actions/upload-artifact@v4
)
- Crie um primeiro arquivo de
workflow
do GitHub Actions. (ex:.github/workflows/fork_pr_benchmarks_track.yml
) - Nomeie este workflow como segundo workflow.
(ex:
name: Track Benchmarks with Bencher
) - Encadeie os dois workflows com
o evento
workflow_run
. (ex:on: workflow_run: ...
) - Crie um
job
do GitHub Actions. (ex:jobs: track_fork_pr_branch
) - Execute este job apenas se a conclusão do workflow anterior for um sucesso usando
o evento
workflow_run
do GitHub Actions. (ex:if: github.event.workflow_run.conclusion == 'success'
) - Defina o tipo de máquina em que o job será executado.
Veja a documentação
runs-on
do GitHub Actions para uma visão geral completa. (ex:runs-on: ubuntu-latest
) - Defina os nomes dos arquivos de resultados do benchmark e do objeto do evento
pull_request
como variáveis de ambiente. (ex:env: ...
) - Baixe os resultados do benchmark em cache e o evento
pull_request
usando o GitHub Actionaction-download-artifact
. (ex:uses: dawidd6/action-download-artifact@v6
) - Exporte os dados necessários do evento
pull_request
como variáveis de ambiente. (ex:core.exportVariable(...)
) - Instale o CLI do Bencher usando o GitHub Action.
(ex:
uses: bencherdev/bencher@main
) - Use o subcomando CLI
bencher run
para rastrear os benchmarks do branch do fork pull. Veja o subcomando CLIbencher run
para uma visão geral completa. (ex:bencher run
) - Defina a opção
--project
para o slug do Projeto. Veja a documentação--project
para mais detalhes. (ex:--project save-walter-white-1234abcd
) - Defina a opção
--token
para o segredo do RepositórioBENCHER_API_TOKEN
. Veja a documentação--token
para mais detalhes. (ex:--token '${{ secrets.BENCHER_API_TOKEN }}'
) - Defina a opção
--branch
para o nome do branch do fork PR usando [o contextogithub
do GitHub Actions][github actions context]. Veja a documentação--branch
para uma visão geral completa. (ex:--branch '${{ env.PR_HEAD }}'
) - Defina o Ponto de Início para o Branch do fork PR:
- Defina a opção
--start-point
para o ponto de início do Branch do fork PR usando [o contextogithub
do GitHub Actions][github actions context]. Veja a documentação--start-point
para uma visão geral completa. (ex:--start-point '${{ env.PR_BASE }}'
) - Defina a opção
--start-point-hash
para o hashgit
do ponto de início do Branch do fork PR usando o eventopull_request
do GitHub Actions. Veja a documentação--start-point-hash
para uma visão geral completa. (ex:--start-point-hash '${{ env.PR_BASE_SHA }}'
) - Defina o flag
--start-point-clone-thresholds
para clonar os Limiares do ponto de início. Veja a documentação--start-point-clone-thresholds
para uma visão geral completa. (ex:--start-point-clone-thresholds
) - Defina o flag
--start-point-reset
para sempre redefinir o Branch do fork PR para o ponto de início. Isso evitará a deriva dos dados de benchmark. Veja a documentação--start-point-reset
para uma visão geral completa. (ex:--start-point-reset
)
- Defina a opção
- Defina a opção
--testbed
para o nome do Testbed. Isso deve provavelmente corresponder à máquina selecionada emruns-on
. Veja a documentação--testbed
para mais detalhes. (ex:--testbed ubuntu-latest
) - Defina o flag
--err
para falhar o comando se um Alerta for gerado. Veja a documentação--err
para uma visão geral completa. (ex:--err
) - Defina a opção
--adapter
para o Formato Métrico JSON do Bencher (json
) que é gerado porbencher mock
. Veja adaptadores de benchmark harness para uma visão geral completa. (ex:--adapter json
) - Defina a opção
--github-actions
para o token de autenticação da API do GitHub para postar resultados como um comentário no Pull Request usando a variável de ambienteGITHUB_TOKEN
do GitHub Actions. Veja a documentação--github-actions
para mais detalhes. (ex:--github-actions '${{ secrets.GITHUB_TOKEN }}'
) - Defina a opção
--ci-number
para o número do pull request. Veja a documentação--ci-number
para mais detalhes. (ex:--ci-number '${{ env.PR_NUMBER }}'
) - Defina a opção
--file
para o caminho do arquivo de resultados do benchmark. Veja comando de benchmark para uma visão geral completa. (ex:--file "$BENCHMARK_RESULTS"
)
Para limpar o branch do PR do fork após o PR ser fechado,
você pode criar um workflow separado para rodar on
eventos de pull_request
com o tipo closed
.
Esse workflow arquivará o branch do PR do fork usando o comando bencher archive
.
-
Crie um arquivo de
workflow
do GitHub Actions. (ex:.github/workflows/fork_pr_benchmarks_closed.yml
) -
Execute em eventos de
pull_request
:closed
- Um pull request foi fechado.
Veja a documentação do
on
do GitHub Actions e a documentação dopull_request
do GitHub Actions para uma visão completa. (ex:on: pull_request: types: [closed]
) -
Crie um
job
do GitHub Actions. (ex:jobs: archive_pr_branch
) -
Defina as permissões para o
GITHUB_TOKEN
comowrite
parapull-requests
. Dependendo das suas configurações do GitHub, isso pode não ser necessário. Mas para todas as organizações e repositórios pessoais criados após 02 de fevereiro de 2023, este é o comportamento padrão. Veja a documentação do GitHub para uma visão completa. (ex:permissions: pull-requests: write
) -
Defina o tipo de máquina em que o job será executado. Veja a documentação do
runs-on
do GitHub Actions para uma visão completa. (ex:runs-on: ubuntu-latest
) -
Faça checkout do código-fonte do branch do PR. (ex:
uses: actions/checkout@v4
) -
Instale o Bencher CLI usando a GitHub Action. (ex:
uses: bencherdev/bencher@main
) -
Use o subcomando da CLI
bencher archive
para arquivar o branch do PR. (ex:bencher archive
) -
Defina a opção
--project
para o slug do Projeto. Veja a documentação de--project
para mais detalhes. (ex:--project save-walter-white-1234abcd
) -
Defina a opção
--token
para o segredo RepositoryBENCHER_API_TOKEN
. Veja a documentação de--token
para mais detalhes. (ex:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
Defina a opção
--branch
para o nome do branch do PR usando o contextogithub
do GitHub Actions. (ex:--branch '${{ github.head_ref }}'
)
🐰 Parabéns! Você aprendeu como usar o Bencher no GitHub Actions! 🎉