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 as permissões para o
GITHUB_TOKEN
comowrite
parachecks
. (ex:permissions: checks: write
) - 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 detectar regressões de desempenho em Pull Requests, você precisará executar seus benchmarks em PRs.
Se você espera ter apenas PRs de branches dentro do mesmo repositório,
então basta criar outro workflow para executar on
eventos de pull_request
do mesmo repositório.
⚠️ Esta solução só funciona se todos os PRs forem do mesmo repositório! Veja Pull Requests de Forks abaixo.
-
Crie um arquivo
workflow
do GitHub Actions. (ex:.github/workflows/pr_benchmarks.yml
) -
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 a branch base de um pull request foi alterada.synchronize
- A branch head de um pull request foi atualizada. Por exemplo, a branch head foi atualizada da branch base ou novos commits foram enviados para a branch head.
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
no GitHub Actions. (ex:jobs: benchmark_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 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
) -
Faça o checkout do código fonte da 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 executar seus benchmarks na branch do 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 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 da branch do PR usando a variável de ambiente padrãoGITHUB_HEAD_REF
do GitHub Actions. Veja a documentação--branch
para uma visão geral completa. (ex:--branch "$GITHUB_HEAD_REF"
) -
Defina o Ponto de Início para a Branch do PR:
- Defina a opção
--start-point
para o ponto de início da Branch do PR usando a variável de ambiente padrãoGITHUB_BASE_REF
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 o hashgit
do ponto de início da 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 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 a Branch do PR para o ponto de início. Isso evitará deriva nos 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--tested
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 Bencher Metric Format JSON (json
) que é gerado porbencher mock
. Veja adapters 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 }}'
) -
Especifique os argumentos do comando de benchmark. Veja comando de benchmark para uma visão geral completa. (ex:
bencher mock
)
Para limpar o branch do PR depois que seu PR for fechado,
você pode criar um fluxo de trabalho separado para executar eventos on
pull_request
com o tipo closed
.
Este fluxo de trabalho arquivará o 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
pull_request
:closed
- Um pull request foi fechado.
Veja a documentação
on
do GitHub Actions e a documentaçãopull_request
do GitHub Action para uma visão completa. (ex:on: pull_request: types: [closed]
) -
Crie um
job
do GitHub Actions. (ex:jobs: archive_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 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 o tipo de máquina em que o job será executado. Veja a documentação
runs-on
do GitHub Actions para uma visão 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 Ação do GitHub. (ex:
uses: bencherdev/bencher@main
) -
Use o subcomando
bencher archive
da CLI para arquivar o branch do PR. (ex:bencher archive
) -
Defina a opção
--project
para o identificador do Projeto. Veja os documentos--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--token
para mais detalhes. (ex:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
Defina a opção
--branch
para o nome do branch do PR usando a variável de ambiente padrãoGITHUB_HEAD_REF
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 somente se a conclusão do workflow anterior foi 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 de benchmark e do objeto de evento
pull_request
como variáveis de ambiente. (ex:env: ...
) - Baixe os resultados de benchmark em cache e o evento
pull_request
usando a Ação do GitHubaction-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 Bencher CLI usando a Ação do GitHub.
(ex:
uses: bencherdev/bencher@main
) - Use o subcomando CLI
bencher run
para rastrear os benchmarks do branch de pull do fork. 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 os documentos da opçã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 os documentos da opção--token
para mais detalhes. (ex:--token '${{ secrets.BENCHER_API_TOKEN }}'
) - Defina a opção
--branch
para o nome do branch PR do fork usando uma variável de ambiente intermediária. Veja os documentos da opção--branch
para uma visão geral completa. (ex:--branch "$PR_HEAD"
) - Defina o Ponto de Partida para o Branch PR do Fork:
- Defina a opção
--start-point
para o ponto de partida do Branch PR do Fork usando uma variável de ambiente intermediária. Veja os documentos da opção--start-point
para uma visão geral completa. (ex:--start-point "$PR_BASE"
) - Defina a opção
--start-point-hash
para o hash dogit
do ponto de partida do Branch PR do Fork usando uma variável de ambiente intermediária. Veja os documentos da opção--start-point-hash
para uma visão geral completa. (ex:--start-point-hash "$PR_BASE_SHA"
) - Defina o sinalizador
--start-point-clone-thresholds
para clonar os Limiares do ponto de partida. Veja os documentos de--start-point-clone-thresholds
para uma visão geral completa. (ex:--start-point-clone-thresholds
) - Defina o sinalizador
--start-point-reset
para sempre redefinir o Branch PR do Fork para o ponto de partida. Isso impedirá a deriva dos dados dos benchmarks. Veja os documentos do--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 provavelmente deve corresponder à máquina selecionada emruns-on
. Veja os documentos da opção--testbed
para mais detalhes. (ex:--testbed ubuntu-latest
) - Defina o sinalizador
--err
para falhar o comando se um Alerta for gerado. Veja os documentos de--err
para uma visão geral completa. (ex:--err
) - Defina a opção
--adapter
para Bencher Metric Format JSON (json
) que é gerado porbencher mock
. Veja adapters de harness de benchmark 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 os resultados como um comentário no Pull Request 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 }}'
) - Defina a opção
--ci-number
para o número do pull request usando uma variável de ambiente intermediária. Veja os documentos da opção--ci-number
para mais detalhes. (ex:--ci-number "$PR_NUMBER"
) - Defina a opção
--file
para o caminho do arquivo de resultados de benchmark. Veja comando de benchmark para uma visão geral completa. (ex:--file "$BENCHMARK_RESULTS"
)
Para limpar o branch de PR do fork após seu PR ser fechado,
você pode criar um fluxo de trabalho separado para executar em eventos on
pull_request_target
com o tipo closed
.
Este fluxo de trabalho arquivará o branch de 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
pull_request_target
:closed
- Um pull request foi fechado.
Consulte a documentação do
on
do GitHub Actions e a documentação dopull_request_target
do GitHub Actions para uma visão geral completa. (ex:on: pull_request_target: types: [closed]
) -
Crie um
job
do GitHub Actions. (ex:jobs: archive_pr_branch
) -
Defina o tipo de máquina na qual o job será executado. Consulte 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 do branch de 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
do CLI para arquivar o branch de PR. (ex:bencher archive
) -
Defina a opção
--project
para o slug do Projeto. Consulte a documentação de--project
para mais detalhes. (ex:--project save-walter-white-1234abcd
) -
Defina a opção
--token
para o segredo de RepositórioBENCHER_API_TOKEN
. Consulte a documentação de--token
para mais detalhes. (ex:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
Defina a opção
--branch
para o nome do branch de PR usando a variável de ambiente padrãoGITHUB_HEAD_REF
do GitHub Actions. (ex:--branch "$GITHUB_HEAD_REF"
)
🐰 Parabéns! Você aprendeu como usar o Bencher no GitHub Actions! 🎉