Cómo usar Bencher en 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.
Rama Base
Una piedra angular de Benchmarking Continuo Estadístico es tener una línea base histórica para tu rama base. Esta línea base histórica puede luego usarse para detectar regresiones de rendimiento en las Pull Requests.
- Crear un archivo de
workflow
para GitHub Actions. (ej:.github/workflows/base_benchmarks.yml
) - Ejecutar en eventos de
push
a la ramamain
. Consulta la documentaciónon
de GitHub Actions y la documentación depush
de GitHub Actions para una visión completa. (ej:on: push: branches: main
) - Crear un
job
de GitHub Actions. (ej:jobs: benchmark_base_branch
) - Establece los permisos para el
GITHUB_TOKEN
awrite
parachecks
. (ej:permissions: checks: write
) - Establecer el tipo de máquina en la que se ejecutará el job.
Consulta la documentación
runs-on
de GitHub Actions para una visión completa. (ej:runs-on: ubuntu-latest
) - Revisa tu código fuente de la rama base.
(ej:
uses: actions/checkout@v4
) - Instala la CLI de Bencher usando la Acción de GitHub.
(ej:
uses: bencherdev/bencher@main
) - Usa el subcomando
bencher run
de la CLI para ejecutar tus benchmarks de la ramamain
. Consulta el subcomandobencher run
de la CLI para una visión completa. (ej:bencher run
) - Establece la opción
--project
al slug del Proyecto. Consulta la documentación de--project
para más detalles. (ej:--project save-walter-white-1234abcd
) - Establece la opción
--token
al secreto de RepositorioBENCHER_API_TOKEN
. Consulta la documentación de--token
para más detalles. (ej:--token '${{ secrets.BENCHER_API_TOKEN }}'
) - Establece la opción
--branch
al nombre de la Rama base. Consulta la documentación de--branch
para una visión completa. (ej:--branch main
) - Establece la opción
--testbed
al nombre del Testbed. Esto debería probablemente coincidir con la máquina seleccionada enruns-on
. Consulta la documentación de--testbed
para más detalles. (ej:--testbed ubuntu-latest
) - Establece el Umbral para la Rama
main
, Testbedubuntu-latest
y la Medidalatency
:- Establece la opción
--threshold-measure
a la Medida incorporadalatency
que generabencher mock
. Consulta la documentación de--threshold-measure
para más detalles. (ej:--threshold-measure latency
) - Establece la opción
--threshold-test
a una prueba t de Student (t_test
). Consulta la documentación de--threshold-test
para una visión completa. (ej:--threshold-test t_test
) - Establece la opción
--threshold-max-sample-size
al tamaño máximo de muestra de64
. Consulta la documentación de--threshold-max-sample-size
para más detalles. (ej:--threshold-max-sample-size 64
) - Establece la opción
--threshold-upper-boundary
al Límite Superior de0.99
. Consulta la documentación de--threshold-upper-boundary
para más detalles. (ej:--threshold-upper-boundary 0.99
) - Establece la bandera
--thresholds-reset
para que solo el Umbral especificado esté activo. Consulta la documentación de--thresholds-reset
para una visión completa. (ej:--thresholds-reset
)
- Establece la opción
- Establece la bandera
--err
para que el comando falle si se genera una Alerta. Consulta la documentación de--err
para una visión completa. (ej:--err
) - Establece la opción
--adapter
al Formato JSON de Métricas de Bencher (json
) que generabencher mock
. Consulta adaptadores de harness de benchmark para una visión completa. (ej:--adapter json
) - Establece la opción
--github-actions
al token de autenticación de la API de GitHub para publicar resultados como un comentario de Checks de GitHub usando la variable de entornoGITHUB_TOKEN
de GitHub Actions. Consulta la documentación de--github-actions
para más detalles. (ej:--github-actions '${{ secrets.GITHUB_TOKEN }}'
) - Especifica los argumentos del comando del benchmark.
Consulta comando de benchmark para una visión completa.
(ej:
bencher mock
)
Pull Requests
Para detectar regresiones de rendimiento en las Pull Requests, necesitarás ejecutar tus benchmarks en las PRs.
Si solo esperas tener PRs desde ramas dentro del mismo repositorio,
entonces simplemente puedes crear otro flujo de trabajo para ejecutar on
eventos de pull_request
desde el mismo repositorio.
⚠️ ¡Esta solución solo funciona si todas las PRs son del mismo repositorio! Consulta Pull Requests desde Forks a continuación.
-
Crea un archivo de
workflow
de GitHub Actions. (ej:.github/workflows/pr_benchmarks.yml
) -
Ejecuta en eventos de
pull_request
:opened
- Se creó una pull request.reopened
- Se reabrió una pull request previamente cerrada.edited
- Se editó el título o el cuerpo de una pull request, o se cambió la rama base de una pull request.synchronize
- Se actualizó la rama de encabezado de una pull request. Por ejemplo, se actualizó la rama de encabezado desde la rama base o se hicieron nuevos commits a la rama de encabezado.
Revisa la documentación de GitHub Actions
on
y la documentación de GitHub Actionspull_request
para una visión completa. (ej:on: pull_request: types: [opened, reopened, edited, synchronize]
) -
Crea un
job
de GitHub Actions. (ej:jobs: benchmark_pr_branch
) -
Ejecuta en eventos de
pull_request
si y solo si la pull request es del mismo repositorio. ⚠️ ¡NO ELIMINES ESTA LÍNEA! Para manejar PRs de Forks, consulta Pull Requests desde Forks a continuación. (ej:if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
) -
Establece los permisos para el
GITHUB_TOKEN
awrite
parapull-requests
. Dependiendo de tu configuración de GitHub, esto puede no ser necesario. Pero para todas las organizaciones y repos personales creados después del 02 de febrero de 2023, este es el comportamiento predeterminado. Consulta la documentación de GitHub para una visión completa. (ej:permissions: pull-requests: write
) -
Establece el tipo de máquina en la que se ejecutará el trabajo. Consulta la documentación de GitHub Actions
runs-on
para una visión completa. (ej:runs-on: ubuntu-latest
) -
Clona el código fuente de la rama PR. (ej:
uses: actions/checkout@v4
) -
Instala el Bencher CLI usando la GitHub Action. (ej:
uses: bencherdev/bencher@main
) -
Usa la subcomando CLI
bencher run
para ejecutar tus benchmarks de la rama de la pull request. Consulta la subcomando CLIbencher run
para una visión completa. (ej:bencher run
) -
Establece la opción
--project
al slug del Proyecto. Consulta los documentos de--project
para más detalles. (ej:--project save-walter-white-1234abcd
) -
Establece la opción
--token
al secreto RepositoryBENCHER_API_TOKEN
. Consulta los documentos de--token
para más detalles. (ej:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
Establece la opción
--branch
al nombre de la rama PR usando la variable de entorno predeterminadaGITHUB_HEAD_REF
de GitHub Actions. Consulta los documentos de--branch
para una visión completa. (ej:--branch "$GITHUB_HEAD_REF"
) -
Establece el Punto de Inicio para la Rama PR:
- Establece la opción
--start-point
al punto de inicio de la Rama PR usando la variable de entorno predeterminadaGITHUB_BASE_REF
de GitHub Actions. Consulta los documentos de--start-point
para una visión completa. (ej:--start-point "$GITHUB_BASE_REF"
) - Establece la opción
--start-point-hash
al hashgit
del punto de inicio de la Rama PR usando el eventopull_request
de GitHub Actions. Consulta los documentos de--start-point-hash
para una visión completa. (ej:--start-point-hash '${{ github.event.pull_request.base.sha }}'
) - Establece la bandera
--start-point-clone-thresholds
para clonar los Umbrales desde el punto de inicio. Consulta los documentos de--start-point-clone-thresholds
para una visión completa. (ej:--start-point-clone-thresholds
) - Establece la bandera
--start-point-reset
para siempre restablecer la Rama PR al punto de inicio. Esto evitará la deriva de datos de benchmark. Consulta los documentos de--start-point-reset
para una visión completa. (ej:--start-point-reset
)
- Establece la opción
-
Establece la opción
--testbed
al nombre del Testbed. Esto debería coincidir con la máquina seleccionada enruns-on
. Consulta los documentos de--tested
para más detalles. (ej:--testbed ubuntu-latest
) -
Establece la bandera
--err
para fallar el comando si se genera una Alerta. Consulta los documentos de--err
para una visión completa. (ej:--err
) -
Establece la opción
--adapter
al Formato de Métrica Bencher JSON (json
) que es generado porbencher mock
. Consulta adaptadores de harness de benchmark para una visión completa. (ej:--adapter json
) -
Establece la opción
--github-actions
al token de autenticación de la API de GitHub para publicar resultados como un comentario en la Pull Request usando la variable de entornoGITHUB_TOKEN
de GitHub Actions. Consulta los documentos de--github-actions
para más detalles. (ej:--github-actions '${{ secrets.GITHUB_TOKEN }}'
) -
Especifica los argumentos del comando de benchmark. Consulta comando de benchmark para una visión completa. (ej:
bencher mock
)
Para limpiar la rama de PR después de que su PR esté cerrado, puedes crear un flujo de trabajo separado para ejecutarse on
eventos de pull_request
con el tipo closed
. Este flujo de trabajo archivará la rama del PR usando el comando bencher archive
.
-
Crea un archivo de
workflow
de GitHub Actions. (ej:.github/workflows/pr_benchmarks_closed.yml
) -
Ejecutar en eventos
pull_request
:closed
- Una solicitud de extracción fue cerrada.
Consulta la documentación de GitHub Actions
on
y la documentación de GitHub Actionspull_request
para una visión completa. (ej:on: pull_request: types: [closed]
) -
Crea un
job
de GitHub Actions. (ej:jobs: archive_pr_branch
) -
Ejecutar en eventos
pull_request
si y solo si la solicitud de extracción es del mismo repositorio. ⚠️ ¡NO ELIMINES ESTA LÍNEA! Para manejar PRs de Forks, consulta Solicitudes de Extracción desde Forks a continuación. (ej:if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
) -
Establecer el tipo de máquina en la que el trabajo se ejecutará. Consulta la documentación de GitHub Actions
runs-on
para una visión completa. (ej:runs-on: ubuntu-latest
) -
Checkout del código fuente de la rama PR. (ej:
uses: actions/checkout@v4
) -
Instala el CLI de Bencher usando la Acción de GitHub. (ej:
uses: bencherdev/bencher@main
) -
Utiliza el subcomando
bencher archive
del CLI para archivar la rama PR. (ej:bencher archive
) -
Configura la opción
--project
al identificador del Proyecto. Consulta la documentación de--project
para más detalles. (ej:--project save-walter-white-1234abcd
) -
Configura la opción
--token
al secreto de RepositoryBENCHER_API_TOKEN
. Consulta la documentación de--token
para más detalles. (ej:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
Configura la opción
--branch
al nombre de la rama PR usando la variable de entorno predeterminadaGITHUB_HEAD_REF
de GitHub Actions. (ej:--branch "$GITHUB_HEAD_REF"
)
Pull Requests desde Forks
Si planeas aceptar pull requests desde forks, como suele ser el caso en proyectos de código abierto público,
entonces tendrás que manejar las cosas de manera un poco diferente.
Por razones de seguridad, secretos como tu BENCHER_API_TOKEN
y el GITHUB_TOKEN
no están disponibles en GitHub Actions para PRs desde forks.
Es decir, si un contribuyente externo abre un PR desde un fork, el ejemplo anterior no funcionará.
Consulta este artículo del GitHub Security Lab
y esta entrada de blog
sobre cómo prevenir solicitudes de pwn para obtener una visión completa.
Esta es la forma segura y recomendada de añadir Continuous Benchmarking a los pull requests desde forks.
Requiere dos flujos de trabajo separados.
El primer flujo de trabajo ejecuta y almacena en caché los resultados del benchmark en el contexto de pull_request
.
No hay secretos como tu BENCHER_API_TOKEN
y el GITHUB_TOKEN
disponibles allí.
Entonces, un segundo flujo de trabajo descarga los resultados del benchmark almacenados en caché en el contexto de workflow_run
y los sube a Bencher.
Esto funciona porque workflow_run
se ejecuta en el contexto de la rama por defecto del repositorio,
donde los secretos como tu BENCHER_API_TOKEN
y el GITHUB_TOKEN
están disponibles.
El número de pull request, la rama principal y la rama base utilizada en el flujo de trabajo inicial pull_request
también deben pasarse explícitamente al flujo de trabajo workflow_run
ya que no están disponibles allí.
Estos flujos de trabajo solo se ejecutarán si existen en la rama predeterminada.
Consulta usando datos del flujo de trabajo desencadenante para obtener una visión completa.
-
Crea un primer archivo de
workflow
de GitHub Actions. (ej:.github/workflows/fork_pr_benchmarks_run.yml
) -
Nombra este flujo de trabajo para que pueda ser referenciado por el segundo flujo de trabajo. (ej:
name: Run Benchmarks
) -
Ejecuta en eventos de
pull_request
:opened
- Se creó una solicitud de extracción.reopened
- Se reabrió una solicitud de extracción previamente cerrada.edited
- Se editó el título o cuerpo de una solicitud de extracción, o se cambió la rama base de una solicitud de extracción.synchronize
- Se actualizó la rama de cabecera de una solicitud de extracción. Por ejemplo, se actualizó la rama de cabecera desde la rama base o se empujaron nuevos commits a la rama de cabecera.
Consulta la documentación de
on
de GitHub Actions y la documentación depull_request
de GitHub Actions para una vista completa. (ej:on: pull_request: types: [opened, reopened, edited, synchronize]
) -
Crea un
job
de GitHub Actions. (ej:jobs: benchmark_fork_pr_branch
) -
Establece el tipo de máquina en el que se ejecutará el trabajo. Consulta la documentación de
runs-on
de GitHub Actions para una vista completa. (ej:runs-on: ubuntu-latest
) -
Verifica el código fuente de la rama PR del fork. (ej:
uses: actions/checkout@v4
) -
Ejecuta tus pruebas de rendimiento y guarda los resultados en un archivo. (ej:
/bin/echo '{ ... }' > benchmark_results.json
) -
Sube el archivo de resultados de pruebas de rendimiento como artefacto. (ej:
uses: actions/upload-artifact@v4
) -
Sube el objeto del evento
pull_request
como artefacto. (ej:uses: actions/upload-artifact@v4
)
- Crea un primer archivo de
workflow
de GitHub Actions. (ej:.github/workflows/fork_pr_benchmarks_track.yml
) - Nombra este flujos de trabajo segundo flujo de trabajo.
(ej:
name: Track Benchmarks with Bencher
) - Encadena los dos flujos de trabajo con
el evento
workflow_run
. (ej:on: workflow_run: ...
) - Crea un
job
de GitHub Actions. (ej:jobs: track_fork_pr_branch
) - Ejecuta este job solo si la conclusión del flujo de trabajo anterior fue un éxito usando
el evento
workflow_run
de GitHub Actions. (ej:if: github.event.workflow_run.conclusion == 'success'
) - Establece el tipo de máquina en la que se ejecutará el job.
Consulta la documentación de
runs-on
de GitHub Actions para un resumen completo. (ej:runs-on: ubuntu-latest
) - Establece los resultados del benchmark y los nombres de archivo de evento de
pull_request
como variables de entorno. (ej:env: ...
) - Descarga los resultados en caché del benchmark y el evento
pull_request
usando la acción de GitHubaction-download-artifact
. (ej:uses: dawidd6/action-download-artifact@v6
) - Exporta los datos necesarios del evento
pull_request
como variables de entorno. (ej:core.exportVariable(...)
) - Instala el CLI de Bencher usando la acción de GitHub.
(ej:
uses: bencherdev/bencher@main
) - Usa el subcomando CLI
bencher run
para rastrear los benchmarks de la rama de pull de tu fork. Consulta el subcomando CLI elbencher run
para un resumen completo. (ej:bencher run
) - Establece la opción
--project
al slug del Proyecto. Consulta los documentos del la--project
para más detalles. (ej:--project save-walter-white-1234abcd
) - Establece la opción
--token
al secreto del RepositorioBENCHER_API_TOKEN
. Consulta los documentos del el--token
para más detalles. (ej:--token '${{ secrets.BENCHER_API_TOKEN }}'
) - Establece la opción
--branch
al nombre de la rama del PR del fork usando una variable de entorno intermedia. Consulta los documentos del el--branch
para un resumen completo. (ej:--branch "$PR_HEAD"
) - Establece el Punto de Inicio para la Rama del PR del fork:
- Establece la opción
--start-point
al punto de inicio de la Rama del PR del fork usando una variable de entorno intermedia. Consulta los documentos del el--start-point
para un resumen completo. (ej:--start-point "$PR_BASE"
) - Establece la opción
--start-point-hash
al hashgit
del punto de inicio de la rama del PR del fork usando una variable de entorno intermedia. Consulta los documentos del el--start-point-hash
para un resumen completo. (ej:--start-point-hash "$PR_BASE_SHA"
) - Establece la bandera
--start-point-clone-thresholds
para clonar los Umbrales desde el punto de inicio. Consulta los documentos del los--start-point-clone-thresholds
para un resumen completo. (ej:--start-point-clone-thresholds
) - Establece la bandera
--start-point-reset
para siempre restablecer la rama del PR del fork al punto de inicio. Esto evitará la deriva de datos del benchmark. Consulta los documentos del el--start-point-reset
para un resumen completo. (ej:--start-point-reset
)
- Establece la opción
- Establece la opción
--testbed
al nombre del Testbed. Esto probablemente debería coincidir con la máquina seleccionada enruns-on
. Consulta los documentos del el--tested
para más detalles. (ej:--testbed ubuntu-latest
) - Establece la bandera
--err
para que el comando falle si se genera una Alerta. Consulta los documentos del el--err
para un resumen completo. (ej:--err
) - Establece la opción
--adapter
al Formato de Métrica Bencher JSON (json
) que es generado porbencher mock
. Consulta los documentos del adaptadores de harness de benchmark para un resumen completo. (ej:--adapter json
) - Establece la opción
--github-actions
al token de autenticación del API de GitHub para publicar los resultados como un comentario en el Pull Request usando la variable de entornoGITHUB_TOKEN
de GitHub Actions. Consulta los documentos del el--github-actions
para más detalles. (ej:--github-actions '${{ secrets.GITHUB_TOKEN }}'
) - Establece la opción
--ci-number
al número de pull request usando una variable de entorno intermedia. Consulta los documentos del el--ci-number
para más detalles. (ej:--ci-number "$PR_NUMBER"
) - Establece la opción
--file
a la ruta del archivo de resultados del benchmark. Consulta los documentos del comando de benchmark para un resumen completo. (ej:--file "$BENCHMARK_RESULTS"
)
Para limpiar la rama del PR del fork después de que se cierre su PR,
puedes crear un flujo de trabajo separado para ejecutar en eventos on
pull_request_target
con el tipo closed
.
Este flujo de trabajo archivará la rama del PR del fork utilizando el comando bencher archive
.
-
Crea un archivo de
workflow
de GitHub Actions. (ej:.github/workflows/fork_pr_benchmarks_closed.yml
) -
Ejecuta en eventos
pull_request_target
:closed
- Se cerró un pull request.
Consulta la documentación sobre
on
de GitHub Actions y la documentación sobrepull_request_target
de GitHub Actions para una visión general completa. (ej:on: pull_request_target: types: [closed]
) -
Crea un
job
de GitHub Actions. (ej:jobs: archive_pr_branch
) -
Establece el tipo de máquina en que correrá el trabajo. Consulta la documentación sobre
runs-on
de GitHub Actions para una visión general completa. (ej:runs-on: ubuntu-latest
) -
Revisa el código fuente de la rama del PR. (ej:
uses: actions/checkout@v4
) -
Instala el Bencher CLI usando la acción de GitHub. (ej:
uses: bencherdev/bencher@main
) -
Usa el subcomando CLI
bencher archive
para archivar la rama del PR. (ej:bencher archive
) -
Establece la opción
--project
con el slug del Proyecto. Consulta los documentos de la opción--project
para más detalles. (ej:--project save-walter-white-1234abcd
) -
Establece la opción
--token
con el secreto RepositorioBENCHER_API_TOKEN
. Consulta los documentos de la opción--token
para más detalles. (ej:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
Establece la opción
--branch
con el nombre de la rama del PR usando la variable de entorno predeterminadaGITHUB_HEAD_REF
de GitHub Actions. (ej:--branch "$GITHUB_HEAD_REF"
)
🐰 ¡Felicidades! ¡Has aprendido cómo usar Bencher en GitHub Actions! 🎉