Como usar o Bencher no GitHub Actions
Dependendo do seu caso de uso, você pode configurar o Benchmarking Contínuo no GitHub Actions para o seu:
- Branch Base
- Pull Requests
- Pull Requests de Forks
- ⛑️ Mais seguro: Benchmark de PR de Fork e Upload a partir do Branch Padrão
- ⚠️ Mais arriscado: Benchmark de PR de Fork a partir do Branch Alvo com Revisores Obrigatórios
🐰 Certifique-se de ter criado um token da API e configurá-lo como um segredo do Repositório chamado
BENCHER_API_TOKEN
antes de continuar! Navegue atéSeu Repositório -> Configurações -> Segredos e variáveis -> Ações -> Novo segredo do repositório
. Nomeie o segredo comoBENCHER_API_TOKEN
e defina o valor do segredo para o seu token da API.
Ramo Base
Um pilar do Benchmarking Contínuo Estatístico é ter uma linha de base histórica para o seu ramo base. Essa linha de base histórica pode então ser utilizada para detectar regressões de desempenho em Pull Requests.
- Crie um arquivo
workflow
do GitHub Actions. (ex:.github/workflows/base_benchmarks.yml
) - Execute em eventos de
push
para o ramomain
. Veja a documentaçãoon
do GitHub Actions e a documentaçãopush
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 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 checkout do código-fonte do seu ramo base.
(ex:
uses: actions/checkout@v4
) - Instale o CLI Bencher usando a GitHub Action.
(ex:
uses: bencherdev/bencher@main
) - Use o subcomando CLI
bencher run
para executar os benchmarks do seu ramomain
. 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 docs--project
para mais detalhes. (ex:--project save-walter-white-1234abcd
) - Defina a opção
--token
para o segredo RepositórioBENCHER_API_TOKEN
. Veja os docs--token
para mais detalhes. (ex:--token '${{ secrets.BENCHER_API_TOKEN }}'
) - Defina a opção
--branch
para o nome do Ramo. Veja seleção de ramo para uma visão geral completa. (ex:--branch main
) - Defina a opção
--testbed
para o nome da Base de teste. Isso provavelmente deve corresponder à máquina selecionada emruns-on
. Veja os docs--tested
para mais detalhes. (ex:--testbed ubuntu-latest
) - Defina a opção
--adapter
para o adaptador de conjunto de benchmarks desejado. Veja adaptadores de conjunto de benchmarks para uma visão geral completa. (ex:--adapter json
) - Defina a flag
--err
para falhar o comando se um Alerta for gerado. Veja Limiares & Alertas para uma visão geral completa. (ex:--err
) - 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 em PRs.
Se você espera receber PRs apenas de branches dentro do mesmo repositório,
então você pode simplesmente criar outro fluxo de trabalho para ser executado on
eventos 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 de
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 fechado anteriormente 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 de cabeçalho de um pull request foi atualizada. Por exemplo, a branch de cabeçalho foi atualizada a partir da branch base ou novos commits foram enviados para a branch de cabeçalho.
Veja a documentação de
on
do GitHub Actions e documentação dopull_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
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
) -
Configure as permissões para o
GITHUB_TOKEN
parawrite
parapull-requests
. Dependendo das suas configurações do GitHub, isso pode não ser necessário. Mas para todas as organizações e repos pessoais criados após 02 Fev 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 trabalho 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 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 os benchmarks da sua 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 os docs de--project
para mais detalhes. (ex:--project save-walter-white-1234abcd
) -
Defina a opção
--token
para o segredo RepositórioBENCHER_API_TOKEN
. Veja os docs de--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. Veja seleção de branch para uma visão geral completa. (ex:--branch '${{ github.head_ref }}'
) -
Defina a opção
--branch-start-point
para o ponto de início da Branch base do PR usando o contextogithub
do GitHub Actions. Veja seleção de branch para uma visão geral completa. (ex:--branch-start-point '${{ github.base_ref }}'
) -
Defina a opção
--branch-start-point-hash
para o hash do ponto de início da Branch base do PR usando o eventopull_request
do GitHub Actions. Veja seleção de branch para uma visão geral completa. (ex:--branch-start-point-hash '${{ github.event.pull_request.base.sha }}'
) -
Defina a opção
--testbed
para o nome do Testbed. Isso provavelmente deve corresponder à máquina selecionada emruns-on
. Veja os docs de--tested
para mais detalhes. (ex:--testbed ubuntu-latest
) -
Defina a opção
--adapter
para o adaptador desejado do benchmark harness. Veja adaptadores de benchmark harness para uma visão geral completa. (ex:--adapter json
) -
Defina a flag
--err
para falhar o comando se um Alerta for gerado. Veja Threshold & Alerts para uma visão geral completa. (ex:--err
) -
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 os docs 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 a Partir de Forks
Se você planeja aceitar pull requests de forks, como é frequentemente o caso em projetos open source públicos,
então você precisará lidar com as coisas de maneira um pouco diferente.
Por razões de segurança, secrets como seu BENCHER_API_TOKEN
e o GITHUB_TOKEN
não estão disponíveis no GitHub Actions para PRs de forks.
Isso quer dizer que, se um contribuidor externo abrir um PR a partir de um fork, o exemplo acima não funcionará.
Existem duas opções para PRs de forks:
- ⛑️ Mais seguro: Benchmark Fork PR e Upload a Partir da Branch Padrão
- ⚠️ Mais arriscado: Benchmark Fork PR da Branch de Destino com Revisores Obrigatórios
Veja este artigo do GitHub Security Lab e este post do blog sobre a prevenção de solicitações de pwn para uma visão geral completa.
Benchmark de Forks de PR e Upload a partir do Branch Padrão
Esta é a maneira segura e sugerida de adicionar Benchmarking Contínuo para pull requests de forks.
Ela requer dois workflows separados.
O primeiro workflow executa e armazena em cache os resultados do benchmark no contexto de pull_request
.
Nenhum segredo, como o seu BENCHER_API_TOKEN
e o GITHUB_TOKEN
estão disponíveis lá.
Então, um segundo workflow faz o download dos resultados do benchmark armazenados em cache no contexto de workflow_run
e os envia para o Bencher.
Isso funciona porque o workflow_run
executa no contexto do branch padrão do repositório,
onde segredos como o seu BENCHER_API_TOKEN
e o GITHUB_TOKEN
estão disponíveis.
O número do pull request, o branch de origem e o branch base usados no workflow pull_request
inicial
também devem ser explicitamente passados para o workflow workflow_run
, já que eles não estão disponíveis lá.
Esses workflows só serão executados se existirem no branch padrão.
Veja usando dados do workflow de disparo para uma visão completa.
-
Crie um arquivo de
workflow
do GitHub Actions. (ex:.github/workflows/run_fork_pr_benchmarks.yml
) -
Dê um nome a este workflow para que ele possa ser referenciado pelo segundo workflow. (ex:
name: Executar e Armazenar em Cache os Benchmarks
) -
Execute em eventos de
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
- O branch de origem de um pull request foi atualizado. Por exemplo, o branch de origem foi atualizado a partir do branch base ou novos commits foram enviados para o branch de origem.
Veja a documentação do GitHub Actions
on
e documentação do GitHub Actionspull_request
para uma visão completa. (ex:on: pull_request: types: [opened, reopened, edited, synchronize]
) -
Crie um
job
no GitHub Actions. (ex:jobs: benchmark_fork_pr_branch
) -
Defina o tipo de máquina que o job será executado. Veja a documentação do GitHub Actions
runs-on
para uma visão completa. (ex:runs-on: ubuntu-latest
) -
Faça checkout do código fonte do branch do PR do fork. (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 do benchmark como artefato. (ex:
uses: actions/upload-artifact@v4
) -
Envie o objeto de evento de
pull_request
como artefato. (ex:uses: actions/upload-artifact@v4
)
- Crie um arquivo de
workflow
do GitHub Actions. (ex:.github/workflows/track_fork_pr_benchmarks.yml
) - Nomeie este segundo workflow.
(ex:
name: Acompanhar Benchmarks com Bencher
) - Encadeie os dois workflows com
o evento
workflow_run
. (ex:on: workflow_run: ...
) - Crie um
job
no GitHub Actions. (ex:jobs: track_fork_pr_branch
) - Execute este job apenas 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 que o job será executado.
Veja a documentação do GitHub Actions
runs-on
para uma visão completa. (ex:runs-on: ubuntu-latest
) - Defina os nomes dos arquivos de resultados do benchmark e do evento de
pull_request
como variáveis de ambiente. (ex:env: ...
) - Faça o download dos resultados do benchmark em cache e do evento de
pull_request
. (ex:uses: actions/github-script@v6
) - Extraia os resultados do benchmark em cache e o evento de
pull_request
. (ex:unzip ...
) - Exporte os dados necessários do evento de
pull_request
como variáveis de ambiente. (ex:core.exportVariable(...)
) - Instale a CLI do Bencher usando a Ação do GitHub.
(ex:
uses: bencherdev/bencher@main
) - Use o subcomando da CLI
bencher run
para acompanhar os benchmarks do seu branch de pull request de fork. Veja o subcomandobencher run
da CLI para uma visão completa. (ex:bencher run
) - Defina a opção
--project
para o slug do Projeto. Veja os docs da opção--project
para mais detalhes. (ex:--project save-walter-white-1234abcd
) - Defina a opção
--token
para o segredo RepositórioBENCHER_API_TOKEN
. Veja os docs da opção--token
para mais detalhes. (ex:--token '${{ secrets.BENCHER_API_TOKEN }}'
) - Defina a opção
--branch
para o número formatado do PR de fork usando o eventopull_request
do GitHub Actions. Veja a seleção de branch para uma visão completa. (ex:--branch '${{ env.PR_HEAD }}'
) - Defina a opção
--branch-start-point
para o ponto inicial do branch base do PR de fork usando o eventopull_request
do GitHub Actions. Veja a seleção de ponto inicial do branch para uma visão completa. (ex:--branch-start-point '${{ env.PR_BASE }}'
) - Defina a opção
--branch-start-point-hash
para o hash do ponto inicial do branch base do PR de fork usando o eventopull_request
do GitHub Actions. Veja a seleção de hash do ponto inicial do branch para uma visão completa. (ex:--branch-start-point-hash '${{ env.PR_BASE_SHA }}'
) - Defina a opção
--testbed
para o nome do Testbed. Isso provavelmente deve coincidir com a máquina selecionada emruns-on
. Veja os docs da opção--testbed
para mais detalhes. (ex:--testbed ubuntu-latest
) - Defina a opção
--adapter
para o adaptador do harness de benchmark desejado. Veja adaptadores do harness de benchmark para uma visão completa. (ex:--adapter json
) - Defina a flag
--err
para falhar o comando se um Alerta for gerado. Veja Threshold & Alerts para uma visão completa. (ex:--err
) - 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 os docs da opçã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 os docs da opçã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 o argumento do comando de benchmark para uma visão completa. (ex:--file "$BENCHMARK_RESULTS"
)
Benchmark de PRs de Fork em Relação à Branch Alvo com Revisores Obrigatórios
Para garantir que o código de um pull request de um fork é seguro, esta GitHub Action verifica se o fork é de outro repositório. Se o fork for de outro repositório, então precisará ser revisado.
⚠️ É muito, muito importante revisar cuidadosamente cada PR de fork antes de aprovar! Não fazer isso pode resultar em um pedido de comprometimento!
Se preferir não ter isso na sua consciência, veja [Benchmark de PR de Fork e Upload a partir da Branch Padrão][benchmark fork pr and upload from default branch] acima.
Para configurar este fluxo de trabalho, você precisa criar dois
Ambientes de Ações do GitHub.
Navegue até Seu Repositório -> Configurações -> Ambientes -> Novo ambiente
.
Crie dois novos ambientes, interno
e externo
.
O ambiente interno
não deve ter Regras de proteção de implantação
.
No entanto, o ambiente externo
deve ter Revisores obrigatórios
definidos para aqueles confiáveis para revisar PRs de fork antes de fazer o benchmark.
Veja este post do blog para uma visão geral completa.
Esta configuração funciona porque pull_request_target
é executado no contexto da branch alvo do pull request,
onde segredos como seu BENCHER_API_TOKEN
e o GITHUB_TOKEN
estão disponíveis.
Portanto, este fluxo de trabalho só será executado se existir na branch alvo.
Evite definir quaisquer segredos como variáveis de ambiente, como GITHUB_TOKEN
e BENCHER_API_TOKEN
.
Em vez disso, passe explicitamente seus segredos para bencher run
.
-
Crie um arquivo de
workflow
de Ações do GitHub. (ex:.github/workflows/pr_target_benchmarks.yml
) -
Execute em eventos de
pull_request
:opened
- Um pull request foi criado.reopened
- Um pull request fechado anteriormente 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 de cabeçalho de um pull request foi atualizada. Por exemplo, a branch de cabeçalho foi atualizada a partir da branch base ou novos commits foram enviados para a branch de cabeçalho.
Veja a documentação
on
das Ações do GitHub e a documentaçãopull_request
das Ações do GitHub para uma visão geral completa. (ex:on: pull_request: types: [opened, reopened, edited, synchronize]
) -
Crie o primeiro
job
das Ações do GitHub para verificar se o fluxo de trabalho requer revisão. (ex:jobs: fork_pr_requires_review
) -
Defina o
ambiente
parainterno
se e somente se o pull request for do mesmo repositório. Caso contrário, defina oambiente
paraexterno
, o que exigirá a aprovação de um revisor para continuar. ⚠️ NÃO REMOVA ESTA LINHA! (ex:environment: ${{ (github.event.pull_request.head.repo.full_name == github.repository && 'interno') || 'externo' }}
) -
Crie um segundo
job
das Ações do GitHub para executar seus benchmarks. (ex:benchmark_fork_pr_branch
) -
Faça com que o job
benchmark_fork_pr_branch
precise do jobfork_pr_requires_review
para ser executado. ⚠️ NÃO REMOVA ESTA LINHA! Veja a documentaçãoneeds
das Ações do GitHub para uma visão geral completa. (ex:needs: fork_pr_requires_review
) -
Defina o tipo de máquina em que o job será executado. Veja a documentação
runs-on
das Ações do GitHub para uma visão geral completa. (ex:runs-on: ubuntu-latest
) -
Faça checkout do código fonte do PR de fork. Como
pull_request_target
é executado no contexto da branch alvo do pull request, você ainda precisa fazer checkout da branch do pull request. (ex:uses: actions/checkout@v4
)- Especifique o repositório do PR de fork (ex:
repository: ${{ github.event.pull_request.head.repo.full_name }}
) - Especifique o hash do PR de fork (ex:
ref: ${{ github.event.pull_request.head.sha }}
) - Não persista suas credenciais de
git
(ex:persist-credentials: false
)
- Especifique o repositório do PR de fork (ex:
-
Instale o CLI do Bencher usando a Ação do GitHub. (ex:
uses: bencherdev/bencher@main
) -
Use o subcomando CLI
bencher run
para executar os benchmarks da branch do pull request de 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 docs da opção--project
para mais detalhes. (ex:--project save-walter-white-1234abcd
) -
Defina a opção
--token
para o segredo RepositórioBENCHER_API_TOKEN
. Veja os docs da opção--token
para mais detalhes. (ex:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
Defina a opção
--branch
para o número formatado do PR de fork usando o eventopull_request
das Ações do GitHub. Veja seleção de branch para uma visão geral completa. (ex:--branch '${{ github.event.number }}/merge'
) -
Defina a opção
--branch-start-point
para o ponto inicial da branch base do PR de fork usando o contextogithub
das Ações do GitHub. Veja seleção de branch para uma visão geral completa. (ex:--branch-start-point '${{ github.base_ref }}'
) -
Defina a opção
--branch-start-point-hash
para o hash do ponto inicial da branch base do PR de fork usando o eventopull_request
das Ações do GitHub. Veja seleção de branch para uma visão geral completa. (ex:--branch-start-point-hash '${{ github.event.pull_request.base.sha }}'
) -
Defina a opção
--testbed
para o nome do Testbed. Isso provavelmente deve corresponder à máquina selecionada emruns-on
. Veja os docs da opção--testbed
para mais detalhes. (ex:--testbed ubuntu-latest
) -
Defina a opção
--adapter
para o adaptador de harness desejado. Veja adaptadores de harness para uma visão geral completa. (ex:--adapter json
) -
Defina a flag
--err
para falhar o comando se um Alerta for gerado. Veja Limiares & Alertas para uma visão geral completa. (ex:--err
) -
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
das Ações do GitHub. Veja os docs da opçã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
)
🐰 Parabéns! Você aprendeu como usar o Bencher no GitHub Actions! 🎉