如何在 GitHub Actions 中使用 Bencher
根据您的使用情况,您可以在 GitHub Actions 中为以下内容设置持续基准测试:
确保您已创建 API 令牌并将其设置为名为 BENCHER_API_TOKEN
的仓库密钥后再继续!导航到 Your Repo -> Settings -> Secrets and variables -> Actions -> New repository secret
。将密钥命名为 BENCHER_API_TOKEN
并将密钥值设置为您的 API 令牌。
在 GitHub Actions 中,当工作流从分支仓库触发时,密钥不会传递给运行器。因此,当您通过拉取请求将以下任何工作流添加到您的仓库时,需要使用_相同_仓库中的分支。如果尝试从一个分支的拉取请求中添加 Bencher,那么 BENCHER_API_TOKEN
密钥将不可用。${{ secrets.BENCHER_API_TOKEN }}
将为空字符串。
基础分支
统计连续基准测试 的基础是为您的基础分支建立一个历史基线。 这个历史基线可以用于检测 Pull Request 中的性能回归。
- 创建一个 GitHub Actions
workflow
文件。 (例如:.github/workflows/base_benchmarks.yml
) - 在
main
分支的push
事件上运行。 请参阅 GitHub Actionson
文档 和 GitHub Actionspush
文档 以获得完整概述。 (例如:on: push: branches: main
) - 创建一个 GitHub Actions
job
。 (例如:jobs: benchmark_base_branch
) - 将
GITHUB_TOKEN
的权限设置为对checks
具有write
权限。 (例如:permissions: checks: write
) - 设置运行该作业的机器类型。
请参阅 GitHub Actions
runs-on
文档 以获取完整概述。 (例如:runs-on: ubuntu-latest
) - 检出您的基础分支源代码。
(例如:
uses: actions/checkout@v4
) - 使用 GitHub Action 安装 Bencher CLI。
(例如:
uses: bencherdev/bencher@main
) - 使用
bencher run
CLI 子命令 来运行您的main
分支基准测试。 请参阅bencher run
CLI 子命令 以获取完整概述。 (例如:bencher run
) - 将
--project
选项设置为项目标识符。 请参阅--project
文档 了解更多详情。 (例如:--project save-walter-white-1234abcd
) - 将
--token
选项设置为BENCHER_API_TOKEN
存储库密钥。 请参阅--token
文档 了解更多详情。 (例如:--token '${{ secrets.BENCHER_API_TOKEN }}'
) - 将
--branch
选项设置为基础分支名称。 请参阅--branch
文档 了解完整概述。 (例如:--branch main
) - 将
--testbed
选项设置为测试平台名称。 这应与在runs-on
中选择的机器相匹配。 请参阅--tested
文档 了解更多详情。 (例如:--testbed ubuntu-latest
) - 为
main
分支、ubuntu-latest
测试平台和latency
测量设置阈值:- 将
--threshold-measure
选项设置为由bencher mock
生成的内置latency
测量。 请参阅--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 Metric Format JSON (json
),该格式由bencher mock
生成。 请参阅 基准配置适配器 了解完整概述。 (例如:--adapter json
) - 设置
--github-actions
选项为 GitHub API 身份验证令牌,以使用 GitHub ActionsGITHUB_TOKEN
环境变量 作为 GitHub Checks 评论发布结果。 请参阅--github-actions
文档 了解更多详情。 (例如:--github-actions '${{ secrets.GITHUB_TOKEN }}'
) - 指定基准测试命令参数。
请参阅 基准测试命令 了解完整概述。
(例如:
bencher mock
)
Pull Requests
为了在拉取请求中捕获性能回归,您需要在 PR 上运行基准测试。
如果您只期望从同一个仓库的分支中获得拉取请求,那么您可以简单地创建另一个工作流来在同一仓库的 pull_request
事件上运行。
⚠️ 此解决方案仅适用于所有 PR 来自同一个仓库的情况! 请参见下面的来自 Fork 的拉取请求。
-
创建一个 GitHub Actions
workflow
文件。 (例如:.github/workflows/pr_benchmarks.yml
) -
在
pull_request
事件上运行:opened
- 创建了一个拉取请求。reopened
- 重新打开了一个先前关闭的拉取请求。edited
- 编辑了拉取请求的标题或正文,或更改了拉取请求的基分支。synchronize
- 更新了拉取请求的头分支。 例如,头分支是从基分支更新的,或新的提交被推送到头分支。
查看 GitHub Actions
on
文档 和 GitHub Actionspull_request
文档 以获取完整概览。 (例如:on: pull_request: types: [opened, reopened, edited, synchronize]
) -
创建一个 GitHub Actions
job
。 (例如:jobs: benchmark_pr_branch
) -
如果且仅当拉取请求来自同一仓库时,在
pull_request
事件上运行。 ⚠️ 不要删除此行! 处理 Fork PR 请参见下面的来自 Fork 的拉取请求。 (例如:if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
) -
将
GITHUB_TOKEN
的权限 设置为write
以用于pull-requests
。 依赖于您的 GitHub 设置,这可能不是必需的。 但对于 2023 年 2 月 2 日之后创建的所有组织和个人仓库,这是默认行为。 查看 GitHub 文档 以获取完整概览。 (例如:permissions: pull-requests: write
) -
设置运行作业的机器类型。 查看 GitHub Actions
runs-on
文档 以获取完整概览。 (例如:runs-on: ubuntu-latest
) -
检出 PR 分支的源代码。 (例如:
uses: actions/checkout@v4
) -
使用 GitHub Action 安装 Bencher CLI。 (例如:
uses: bencherdev/bencher@main
) -
使用
bencher run
CLI 子命令运行您的拉取请求分支基准测试。 查看bencher run
CLI 子命令 以获取完整概览。 (例如:bencher run
) -
将
--project
选项设置为项目 slug。 查看--project
文档 以获取详细信息。 (例如:--project save-walter-white-1234abcd
) -
将
--token
选项设置为BENCHER_API_TOKEN
仓库密钥。 查看--token
文档 以获取详细信息。 (例如:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
使用 GitHub Actions
GITHUB_HEAD_REF
默认环境变量 设置--branch
选项为 PR 分支名称。 查看--branch
文档 以获取完整概览。 (例如:--branch "$GITHUB_HEAD_REF"
) -
设置 PR 分支的起点:
- 使用 GitHub Actions
GITHUB_BASE_REF
默认环境变量 将--start-point
选项设置为 PR 分支起点。 查看--start-point
文档 以获取完整概览。 (例如:--start-point "$GITHUB_BASE_REF"
) - 使用 GitHub Actions
pull_request
事件 将--start-point-hash
选项设置为 PR 分支起点的git
hash。 查看--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
)
- 使用 GitHub Actions
-
将
--testbed
选项设置为 Testbed 名称。此名称应与runs-on
中选择的机器匹配。 查看--tested
文档 以获取更多详细信息。 (例如:--testbed ubuntu-latest
) -
设置
--err
标志以在生成警报时使命令失败。 查看--err
文档 以获取完整概览。 (例如:--err
) -
将
--adapter
选项设置为 由bencher mock
生成的 Bencher Metric Format JSON (json
)。 查看 基准测试适配器 以获取完整概览。 (例如:--adapter json
) -
使用 GitHub Actions
GITHUB_TOKEN
环境变量 将--github-actions
选项设置为 GitHub API 身份验证令牌,以便将结果作为评论发布在拉取请求上。 查看--github-actions
文档 以获取更多详细信息。 (例如:--github-actions '${{ secrets.GITHUB_TOKEN }}'
) -
指定基准测试命令参数。 查看 基准测试命令 以获取完整概览。 (例如:
bencher mock
)
为了在 PR 关闭后清理 PR 分支,
您可以创建一个独立的工作流,在 pull_request
事件中运行 on
,其类型为 closed
。
这个工作流将使用 bencher archive
命令来归档 PR 分支。
-
创建一个 GitHub Actions
workflow
文件。 (例如:.github/workflows/pr_benchmarks_closed.yml
) -
运行于
pull_request
事件:closed
- 一个拉取请求已关闭。
查看 GitHub Actions
on
文档 和 GitHub Actionspull_request
文档 以获取完整概述。 (例如:on: pull_request: types: [closed]
) -
创建一个 GitHub Actions
job
。 (例如:jobs: archive_pr_branch
) -
仅当且仅当拉取请求来自同一存储库时才在
pull_request
事件上运行。 ⚠️ 切勿移除此行! 处理 Fork PR 请参见下面的 来自 Fork 的自动请求。 (例如: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
) -
使用 GitHub Action 安装 Bencher CLI。 (例如:
uses: bencherdev/bencher@main
) -
使用
bencher archive
CLI 子命令归档 PR 分支。 (例如:bencher archive
) -
设置
--project
选项为项目的 slug。 查看--project
文档 以获取更多详细信息。 (例如:--project save-walter-white-1234abcd
) -
将
--token
选项设置为BENCHER_API_TOKEN
存储库密钥。 查看--token
文档 以获取更多详细信息。 (例如:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
使用 GitHub Actions
GITHUB_HEAD_REF
默认环境变量 将--branch
选项设置为 PR 分支名称。 (例如:--branch "$GITHUB_HEAD_REF"
)
从 Fork 中的拉取请求
如果您计划接受来自 fork 的拉取请求,这通常在公共开源项目中发生,那么您需要稍微不同地处理事情。出于安全原因,像 BENCHER_API_TOKEN
和 GITHUB_TOKEN
这样的秘密在针对 fork 提交的 GitHub Actions 中不可用。也就是说,如果外部贡献者从 fork 中打开拉取请求,上述示例将 不 能工作。请参阅这个 GitHub Security Lab 的文章 和 这篇博客文章,以了解完整概述如何防止恶意请求。
这是为 fork 的拉取请求添加持续基准测试的安全和建议方法。它需要两个独立的工作流。第一个工作流在 pull_request
上下文中运行并缓存基准结果。在这里,像 BENCHER_API_TOKEN
和 GITHUB_TOKEN
这样的秘密不可用。然后,第二个工作流在 workflow_run
上下文中下载缓存的基准结果并将它们上传到 Bencher。这有效是因为 workflow_run
在仓库默认分支的上下文中运行,在那里,像 BENCHER_API_TOKEN
和 GITHUB_TOKEN
这样的秘密是可用的。在初始 pull_request
工作流中使用的拉取请求编号、head 分支和 base 分支也必须显式传递到 workflow_run
工作流中,因为它们在那里不可用。这些工作流仅在它们存在于_默认_分支时才会运行。有关完整概述,请参阅使用触发工作流的数据。
-
创建第一个 GitHub Actions
workflow
文件。 (例如:.github/workflows/fork_pr_benchmarks_run.yml
) -
为此工作流程命名,以便可以被第二个工作流程引用。 (例如:
name: Run Benchmarks
) -
在
pull_request
事件上运行:opened
- 创建了一个拉取请求。reopened
- 重新打开了一个先前关闭的拉取请求。edited
- 拉取请求的标题或正文被编辑,或拉取请求的基分支被更改。synchronize
- 拉取请求的头分支被更新。 例如,头分支从基分支更新或者有新的提交被推送到头分支。
查看 GitHub Actions
on
文档 和 GitHub Actionspull_request
文档,了解完整概况。 (例如:on: pull_request: types: [opened, reopened, edited, synchronize]
) -
创建一个 GitHub Actions
job
。 (例如:jobs: benchmark_fork_pr_branch
) -
设置作业将在哪种类型的机器上运行。 查看 GitHub Actions
runs-on
文档 了解完整概况。 (例如:runs-on: ubuntu-latest
) -
检出fork PR分支的源代码。 (例如:
uses: actions/checkout@v4
) -
运行基准测试并将结果保存到文件。 (例如:
/bin/echo '{ ... }' > benchmark_results.json
) -
将基准测试结果文件作为工件上传。 (例如:
uses: actions/upload-artifact@v4
) -
将
pull_request
事件对象作为工件上传。 (例如:uses: actions/upload-artifact@v4
)
- 创建第一个 GitHub Actions
workflow
文件。 (例如:.github/workflows/fork_pr_benchmarks_track.yml
) - 将此工作流程命名为第二个工作流程。
(例如:
name: Track Benchmarks with Bencher
) - 使用
workflow_run
事件来链接两个工作流程。 (例如:on: workflow_run: ...
) - 创建一个 GitHub Actions
job
。 (例如:jobs: track_fork_pr_branch
) - 仅在上一个工作流程的结论为成功时运行此工作,
使用GitHub Actions
workflow_run
事件。 (例如:if: github.event.workflow_run.conclusion == 'success'
) - 设置作业运行的机器类型。
查看GitHub Actions
runs-on
文档以获得完整概述。 (例如:runs-on: ubuntu-latest
) - 将基准测试结果和
pull_request
事件对象文件名设置为环境变量。 (例如:env: ...
) - 使用dawidd6/action-download-artifact@v6 下载缓存的基准测试结果和
pull_request
事件。 (例如:uses: dawidd6/action-download-artifact@v6
) - 从
pull_request
事件中导出必要的数据作为环境变量。 (例如:core.exportVariable(...)
) - 使用Bencher GitHub Action安装 Bencher CLI。
(例如:
uses: bencherdev/bencher@main
) - 使用
bencher run
CLI 子命令来跟踪您的 fork pull 分支基准测试。 参见bencher run
CLI 子命令以获取完整概述。 (例如:bencher run
) - 将
--project
选项设置为项目标识符。 有关更多详细信息,请参见--project
文档。 (例如:--project save-walter-white-1234abcd
) - 将
--token
选项设置为BENCHER_API_TOKEN
库密钥。 有关更多详细信息,请参见--token
文档。 (例如:--token '${{ secrets.BENCHER_API_TOKEN }}'
) - 使用中间环境变量设置
--branch
选项为 fork PR 分支名称。 查看--branch
文档以获得完整概述。 (例如:--branch "$PR_HEAD"
) - 设置fork PR 分支的起始点:
- 使用中间环境变量将
--start-point
选项设置为 fork PR 分支的起始点。 查看--start-point
文档以获得完整概述。 (例如:--start-point "$PR_BASE"
) - 使用中间环境变量将
--start-point-hash
选项设置为 fork PR 分支起始点的git
哈希。 查看--start-point-hash
文档以获得完整概述。 (例如:--start-point-hash "$PR_BASE_SHA"
) - 设置
--start-point-clone-thresholds
标志以从起始点克隆阈值。 查看--start-point-clone-thresholds
文档以获得完整概述。 (例如:--start-point-clone-thresholds
) - 设置
--start-point-reset
标志以始终将 fork PR 分支重置为起始点。 这将防止基准数据漂移。 查看--start-point-reset
文档以获得完整概述。 (例如:--start-point-reset
)
- 使用中间环境变量将
- 将
--testbed
选项设置为测试床名称。 这应与runs-on
中选择的机器匹配。 有关更多详细信息,请参见--testbed
文档。 (例如:--testbed ubuntu-latest
) - 设置
--err
标志以在生成警报时使命令失败。 查看--err
文档以获得完整概述。 (例如:--err
) - 将
--adapter
选项设置为由bencher mock
生成的 Bencher Metric Format JSON (json
)。 查看基准测试工具适配器以获得完整概述。 (例如:--adapter json
) - 使用GitHub Actions
GITHUB_TOKEN
环境变量将--github-actions
选项设置为 GitHub API 身份验证令牌,以将结果作为评论发布在 Pull Request 上。 查看--github-actions
文档以获取更多详细信息。 (例如:--github-actions '${{ secrets.GITHUB_TOKEN }}'
) - 使用中间环境变量将
--ci-number
选项设置为 Pull Request 编号。 有关更多详细信息,请参见--ci-number
文档。 (例如:--ci-number "$PR_NUMBER"
) - 将
--file
选项设置为基准测试结果文件路径。 查看基准命令获取完整概述。 (例如:--file "$BENCHMARK_RESULTS"
)
要在 PR 关闭后清理 fork PR 分支,您可以创建一个单独的工作流来在 pull_request_target
事件中使用 closed
类型运行。该工作流将使用 bencher archive
命令归档 fork PR 分支。
-
创建一个 GitHub Actions
workflow
文件。 (例如:.github/workflows/fork_pr_benchmarks_closed.yml
) -
运行在
pull_request_target
事件上:closed
- 一个拉取请求被关闭。
查看 GitHub Actions
on
文档 和 GitHub Actionspull_request_target
文档 以获取完整概览。 (例如:on: pull_request_target: types: [closed]
) -
创建一个 GitHub Actions
job
。 (例如:jobs: archive_pr_branch
) -
设置作业运行的机器类型。 查看 GitHub Actions
runs-on
文档 以获取完整概览。 (例如:runs-on: ubuntu-latest
) -
检出 PR 分支源代码。 (例如:
uses: actions/checkout@v4
) -
使用GitHub Action 安装 Bencher CLI。 (例如:
uses: bencherdev/bencher@main
) -
使用
bencher archive
CLI 子命令归档 PR 分支。 (例如:bencher archive
) -
设置
--project
选项为项目简码。 查看--project
文档 以获取更多详情。 (例如:--project save-walter-white-1234abcd
) -
设置
--token
选项为BENCHER_API_TOKEN
Repository 密钥。 查看--token
文档 以获取更多详情。 (例如:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
设置
--branch
选项为 PR 分支名称,使用GitHub ActionsGITHUB_HEAD_REF
默认环境变量。 (例如:--branch "$GITHUB_HEAD_REF"
)
🐰 恭喜你!你已经学会了如何在 GitHub Actions 中使用 Bencher!🎉