如何在 GitHub Actions 中使用 Bencher

根据您的使用情况，您可以在 GitHub Actions 中为以下内容设置持续基准测试：

• 基础分支
• 拉取请求
• 来自分支的拉取请求
• 裸机上的 Pull Requests

确保您已创建项目 API 密钥并将其设置为名为 BENCHER_API_KEY 的仓库密钥后再继续！导航到 Your Repo -> Settings -> Secrets and variables -> Actions -> New repository secret。将密钥命名为 BENCHER_API_KEY 并将密钥值设置为您的项目 API 密钥。

在 GitHub Actions 中，当工作流从分支仓库触发时，密钥不会传递给运行器。因此，当您通过拉取请求将以下任何工作流添加到您的仓库时，需要使用_相同_仓库中的分支。如果尝试从一个分支的拉取请求中添加 Bencher，那么 BENCHER_API_KEY 密钥将不可用。${{ secrets.BENCHER_API_KEY }} 将为空字符串。

基础分支

统计连续基准测试 的基础是为您的基础分支建立一个历史基线。 这个历史基线可以用于检测 Pull Request 中的性能回归。

on:
  push:
    branches: main

jobs:
  benchmark_base_branch:
    name: Continuous Benchmarking with Bencher
    permissions:
      checks: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: bencherdev/bencher@main
      - name: Track base branch benchmarks with Bencher
        run: |
          bencher run \
          --project project-abc4567-wxyz123456789 \
          --key '${{ secrets.BENCHER_API_KEY }}' \
          --branch main \
          --testbed ubuntu-latest \
          --threshold-measure latency \
          --threshold-test t_test \
          --threshold-max-sample-size 64 \
          --threshold-upper-boundary 0.99 \
          --thresholds-reset \
          --error-on-alert \
          --adapter json \
          --github-actions '${{ secrets.GITHUB_TOKEN }}' \
          bencher mock

1. 创建一个 GitHub Actions workflow 文件。 (例如：.github/workflows/base_benchmarks.yml)
2. 在 main 分支的 push 事件上运行。 请参阅 GitHub Actions on 文档 和 GitHub Actions push 文档 以获得完整概述。 (例如：on: push: branches: main)
3. 创建一个 GitHub Actions job。 (例如：jobs: benchmark_base_branch)
4. 将GITHUB_TOKEN 的权限设置为对checks具有write权限。 （例如：permissions: checks: write）
5. 设置运行该作业的机器类型。 请参阅 GitHub Actions runs-on 文档 以获取完整概述。 (例如：runs-on: ubuntu-latest)
6. 检出您的基础分支源代码。 (例如：uses: actions/checkout@v6)
7. 使用 GitHub Action 安装 Bencher CLI。 (例如：uses: bencherdev/bencher@main)
8. 使用 bencher run CLI 子命令 来运行您的 main 分支基准测试。 请参阅 bencher run CLI 子命令 以获取完整概述。 (例如：bencher run)
9. 将 --project 选项设置为项目标识符。 请参阅 --project 文档 了解更多详情。 (例如：--project project-abc4567-wxyz123456789)
10. 将 --key 选项设置为 BENCHER_API_KEY 存储库密钥。 请参阅 --key 文档 了解更多详情。 (例如：--key '${{ secrets.BENCHER_API_KEY }}')
11. 将 --branch 选项设置为基础分支名称。 请参阅 --branch 文档 了解完整概述。 (例如：--branch main)
12. 将 --testbed 选项设置为测试平台名称。 这应与在 runs-on 中选择的机器相匹配。 请参阅 --tested 文档 了解更多详情。 (例如：--testbed ubuntu-latest)
13. 为 main 分支、ubuntu-latest 测试平台和 latency 测量设置阈值：
    1. 将 --threshold-measure 选项设置为由 bencher mock 生成的内置 latency 测量。 请参阅 --threshold-measure 文档 了解更多详情。 (例如：--threshold-measure latency)
    2. 将 --threshold-test 选项设置为学生 t 检验（t_test）。 请参阅 --threshold-test 文档 了解完整概述。 (例如：--threshold-test t_test)
    3. 将 --threshold-max-sample-size 选项设置为最大样本大小 64。 请参阅 --threshold-max-sample-size 文档 了解更多详情。 (例如：--threshold-max-sample-size 64)
    4. 将 --threshold-upper-boundary 选项设置为上界 0.99。 请参阅 --threshold-upper-boundary 文档 了解更多详情。 (例如：--threshold-upper-boundary 0.99)
    5. 设置 --thresholds-reset 标志，使得只有指定的阈值是活跃的。 请参阅 --thresholds-reset 文档 了解完整概述。 (例如：--thresholds-reset)
14. 设置 --error-on-alert 标志，如果生成警报，则使命令失败。 请参阅 --error-on-alert 文档 了解完整概述。 (例如：--error-on-alert)
15. 将 --adapter 选项设置为 Bencher Metric Format JSON (json)，该格式由 bencher mock 生成。 请参阅 基准配置适配器 了解完整概述。 (例如：--adapter json)
16. 设置 --github-actions 选项为 GitHub API 身份验证令牌，以使用 GitHub Actions GITHUB_TOKEN 环境变量 作为 GitHub Checks 评论发布结果。 请参阅 --github-actions 文档 了解更多详情。 (例如：--github-actions '${{ secrets.GITHUB_TOKEN }}')
17. 指定基准测试命令参数。 请参阅 基准测试命令 了解完整概述。 (例如：bencher mock)

Pull Requests

为了在拉取请求中捕获性能回归，您需要在 PR 上运行基准测试。 如果您只期望从同一个仓库的分支中获得拉取请求，那么您可以简单地创建另一个工作流来在同一仓库的 pull_request 事件上运行。

⚠️ 此解决方案仅适用于所有 PR 来自同一个仓库的情况！ 请参见下面的来自 Fork 的拉取请求。

on:
  pull_request:
    types: [opened, reopened, edited, synchronize]

jobs:
  benchmark_pr_branch:
    name: Continuous Benchmarking PRs with Bencher
    # DO NOT REMOVE: For handling Fork PRs see Pull Requests from Forks
    if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
    permissions:
      checks: write
      pull-requests: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: bencherdev/bencher@main
      - name: Track PR Benchmarks with Bencher
        run: |
          bencher run \
          --project project-abc4567-wxyz123456789 \
          --key '${{ secrets.BENCHER_API_KEY }}' \
          --branch "$GITHUB_HEAD_REF" \
          --start-point "$GITHUB_BASE_REF" \
          --start-point-hash '${{ github.event.pull_request.base.sha }}' \
          --start-point-clone-thresholds \
          --start-point-reset \
          --testbed ubuntu-latest \
          --error-on-alert \
          --adapter json \
          --github-actions '${{ secrets.GITHUB_TOKEN }}' \
          bencher mock

1. 创建一个 GitHub Actions workflow 文件。 （例如：.github/workflows/pr_benchmarks.yml）

2. 在 pull_request 事件上运行：

   • opened - 创建了一个拉取请求。
   • reopened - 重新打开了一个先前关闭的拉取请求。
   • edited - 编辑了拉取请求的标题或正文，或更改了拉取请求的基分支。
   • synchronize - 更新了拉取请求的头分支。 例如，头分支是从基分支更新的，或新的提交被推送到头分支。

   查看 GitHub Actions on 文档 和 GitHub Actions pull_request 文档 以获取完整概览。 （例如：on: pull_request: types: [opened, reopened, edited, synchronize]）

3. 创建一个 GitHub Actions job。 （例如：jobs: benchmark_pr_branch）

4. 如果且仅当拉取请求来自同一仓库时，在 pull_request 事件上运行。 ⚠️ 不要删除此行！ 处理 Fork PR 请参见下面的来自 Fork 的拉取请求。 （例如：if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository）

5. 将 GITHUB_TOKEN 的权限 设置为 write 以用于 checks 和 pull-requests。 依赖于您的 GitHub 设置，这可能不是必需的。 但对于 2023 年 2 月 2 日之后创建的所有组织和个人仓库，这是默认行为。 查看 GitHub 文档 以获取完整概览。 （例如：permissions: checks: write pull-requests: write）

6. 设置运行作业的机器类型。 查看 GitHub Actions runs-on 文档 以获取完整概览。 （例如：runs-on: ubuntu-latest）

7. 检出 PR 分支的源代码。 （例如：uses: actions/checkout@v6）

8. 使用 GitHub Action 安装 Bencher CLI。 （例如：uses: bencherdev/bencher@main）

9. 使用 bencher run CLI 子命令运行您的拉取请求分支基准测试。 查看 bencher run CLI 子命令 以获取完整概览。 （例如：bencher run）

10. 将 --project 选项设置为项目 slug。 查看 --project 文档 以获取详细信息。 （例如：--project project-abc4567-wxyz123456789）

11. 将 --key 选项设置为 BENCHER_API_KEY 仓库密钥。 查看 --key 文档 以获取详细信息。 （例如：--key '${{ secrets.BENCHER_API_KEY }}'）

12. 使用 GitHub Actions GITHUB_HEAD_REF 默认环境变量 设置 --branch 选项为 PR 分支名称。 查看 --branch 文档 以获取完整概览。 （例如：--branch "$GITHUB_HEAD_REF"）

13. 设置 PR 分支的起点：

    1. 使用 GitHub Actions GITHUB_BASE_REF 默认环境变量 将 --start-point 选项设置为 PR 分支起点。 查看 --start-point 文档 以获取完整概览。 （例如：--start-point "$GITHUB_BASE_REF"）
    2. 使用 GitHub Actions pull_request 事件 将 --start-point-hash 选项设置为 PR 分支起点的 git hash。 查看 --start-point-hash 文档 以获取完整概览。 （例如：--start-point-hash '${{ github.event.pull_request.base.sha }}'）
    3. 设置 --start-point-clone-thresholds 标志以从起点克隆阈值。 查看 --start-point-clone-thresholds 文档 以获取完整概览。 （例如：--start-point-clone-thresholds）
    4. 设置 --start-point-reset 标志以始终重置 PR 分支到起点。这将防止基准测试数据漂移。 查看 --start-point-reset 文档 以获取完整概览。 （例如：--start-point-reset）

14. 将 --testbed 选项设置为 Testbed 名称。此名称应与 runs-on 中选择的机器匹配。 查看 --tested 文档 以获取更多详细信息。 （例如：--testbed ubuntu-latest）

15. 设置 --error-on-alert 标志以在生成警报时使命令失败。 查看 --error-on-alert 文档 以获取完整概览。 （例如：--error-on-alert）

16. 将 --adapter 选项设置为 由 bencher mock 生成的 Bencher Metric Format JSON (json)。 查看 基准测试适配器 以获取完整概览。 （例如：--adapter json）

17. 使用 GitHub Actions GITHUB_TOKEN 环境变量 将 --github-actions 选项设置为 GitHub API 身份验证令牌，以便将结果作为 GitHub 检查和评论发布在拉取请求上。 查看 --github-actions 文档 以获取更多详细信息。 （例如：--github-actions '${{ secrets.GITHUB_TOKEN }}'）

18. 指定基准测试命令参数。 查看 基准测试命令 以获取完整概览。 （例如：bencher mock）

为了在 PR 关闭后清理 PR 分支， 您可以创建一个独立的工作流，在 pull_request 事件中运行 on，其类型为 closed。 这个工作流将使用 bencher archive 命令来归档 PR 分支。

on:
  pull_request:
    types: [closed]

jobs:
  archive_pr_branch:
    name: Archive closed PR branch with Bencher
    # DO NOT REMOVE: For handling Fork PRs see Pull Requests from Forks
    if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: bencherdev/bencher@main
      - name: Archive closed PR branch with Bencher
        run: |
          bencher archive \
          --project project-abc4567-wxyz123456789 \
          --key '${{ secrets.BENCHER_API_KEY }}' \
          --branch "$GITHUB_HEAD_REF"

1. 创建一个 GitHub Actions workflow 文件。 (例如：.github/workflows/pr_benchmarks_closed.yml)

2. 运行于 pull_request 事件：

   • closed - 一个拉取请求已关闭。

   查看 GitHub Actions on 文档 和 GitHub Actions pull_request 文档 以获取完整概述。 (例如：on: pull_request: types: [closed])

3. 创建一个 GitHub Actions job。 (例如：jobs: archive_pr_branch)

4. 仅当且仅当拉取请求来自同一存储库时才在 pull_request 事件上运行。 ⚠️ 切勿移除此行！ 处理 Fork PR 请参见下面的 来自 Fork 的自动请求。 (例如：if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository)

5. 设置作业运行所需的机器类型。 参见 GitHub Actions runs-on 文档 以获取完整概述。 (例如：runs-on: ubuntu-latest)

6. 签出 PR 分支源代码。 (例如：uses: actions/checkout@v6)

7. 使用 GitHub Action 安装 Bencher CLI。 (例如：uses: bencherdev/bencher@main)

8. 使用 bencher archive CLI 子命令归档 PR 分支。 (例如：bencher archive)

9. 设置 --project 选项为项目的 slug。 查看 --project 文档 以获取更多详细信息。 (例如：--project project-abc4567-wxyz123456789)

10. 将 --key 选项设置为 BENCHER_API_KEY 存储库密钥。 查看 --key 文档 以获取更多详细信息。 (例如：--key '${{ secrets.BENCHER_API_KEY }}')

11. 使用 GitHub Actions GITHUB_HEAD_REF 默认环境变量 将 --branch 选项设置为 PR 分支名称。 (例如：--branch "$GITHUB_HEAD_REF")

从 Fork 中的拉取请求

如果您计划接受来自 fork 的拉取请求，这通常在公共开源项目中发生，那么您需要稍微不同地处理事情。出于安全原因，像 BENCHER_API_KEY 和 GITHUB_TOKEN 这样的秘密在针对 fork 提交的 GitHub Actions 中不可用。也就是说，如果外部贡献者从 fork 中打开拉取请求，上述示例将 不 能工作。请参阅这个 GitHub Security Lab 的文章 和 这篇博客文章，以了解完整概述如何防止恶意请求。

这是为 fork 的拉取请求添加持续基准测试的安全和建议方法。它需要两个独立的工作流。第一个工作流在 pull_request 上下文中运行并缓存基准结果。在这里，像 BENCHER_API_KEY 和 GITHUB_TOKEN 这样的秘密不可用。然后，第二个工作流在 workflow_run 上下文中下载缓存的基准结果并将它们上传到 Bencher。这有效是因为 workflow_run 在仓库默认分支的上下文中运行，在那里，像 BENCHER_API_KEY 和 GITHUB_TOKEN 这样的秘密是可用的。在初始 pull_request 工作流中使用的拉取请求编号、head 分支和 base 分支也必须显式传递到 workflow_run 工作流中，因为它们在那里不可用。这些工作流仅在它们存在于_默认_分支时才会运行。有关完整概述，请参阅使用触发工作流的数据。

name: Run Benchmarks

on:
  pull_request:
    types: [opened, reopened, edited, synchronize]

jobs:
  benchmark_fork_pr_branch:
    name: Run Fork PR Benchmarks
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Mock Benchmarking
        run: |
          /bin/echo '{ "bencher::mock_0": { "latency": { "value": 1.0 } } }' > benchmark_results.json
      - name: Upload Benchmark Results
        uses: actions/upload-artifact@v4
        with:
          name: benchmark_results.json
          path: ./benchmark_results.json
      - name: Upload GitHub Pull Request Event
        uses: actions/upload-artifact@v4
        with:
          name: event.json
          path: ${{ github.event_path }}

1. 创建第一个 GitHub Actions workflow 文件。 （例如：.github/workflows/fork_pr_benchmarks_run.yml）

2. 为此工作流程命名，以便可以被第二个工作流程引用。 （例如：name: Run Benchmarks）

3. 在 pull_request 事件上运行：

   • opened - 创建了一个拉取请求。
   • reopened - 重新打开了一个先前关闭的拉取请求。
   • edited - 拉取请求的标题或正文被编辑，或拉取请求的基分支被更改。
   • synchronize - 拉取请求的头分支被更新。 例如，头分支从基分支更新或者有新的提交被推送到头分支。

   查看 GitHub Actions on 文档 和 GitHub Actions pull_request 文档，了解完整概况。 （例如：on: pull_request: types: [opened, reopened, edited, synchronize]）

4. 创建一个 GitHub Actions job。 （例如：jobs: benchmark_fork_pr_branch）

5. 设置作业将在哪种类型的机器上运行。 查看 GitHub Actions runs-on 文档 了解完整概况。 （例如：runs-on: ubuntu-latest）

6. 检出fork PR分支的源代码。 （例如：uses: actions/checkout@v6）

7. 运行基准测试并将结果保存到文件。 （例如：/bin/echo '{ ... }' > benchmark_results.json）

8. 将基准测试结果文件作为工件上传。 （例如：uses: actions/upload-artifact@v4）

9. 将 pull_request 事件对象作为工件上传。 （例如：uses: actions/upload-artifact@v4）

name: Track Benchmarks with Bencher

on:
  workflow_run:
    workflows: [Run Benchmarks]
    types: [completed]

jobs:
  track_fork_pr_branch:
    if: github.event.workflow_run.conclusion == 'success'
    permissions:
      checks: write
      pull-requests: write
    runs-on: ubuntu-latest
    env:
      BENCHMARK_RESULTS: benchmark_results.json
      PR_EVENT: event.json
    steps:
      - name: Download Benchmark Results
        uses: dawidd6/action-download-artifact@v6
        with:
          name: ${{ env.BENCHMARK_RESULTS }}
          run_id: ${{ github.event.workflow_run.id }}
      - name: Download PR Event
        uses: dawidd6/action-download-artifact@v6
        with:
          name: ${{ env.PR_EVENT }}
          run_id: ${{ github.event.workflow_run.id }}
      - name: Export PR Event Data
        uses: actions/github-script@v6
        with:
          script: |
            let fs = require('fs');
            let prEvent = JSON.parse(fs.readFileSync(process.env.PR_EVENT, {encoding: 'utf8'}));
            core.exportVariable("PR_HEAD", prEvent.pull_request.head.ref);
            core.exportVariable("PR_HEAD_SHA", prEvent.pull_request.head.sha);
            core.exportVariable("PR_BASE", prEvent.pull_request.base.ref);
            core.exportVariable("PR_BASE_SHA", prEvent.pull_request.base.sha);
            core.exportVariable("PR_NUMBER", prEvent.number);
      - uses: bencherdev/bencher@main
      - name: Track Benchmarks with Bencher
        run: |
          bencher run \
          --project project-abc4567-wxyz123456789 \
          --key '${{ secrets.BENCHER_API_KEY }}' \
          --branch "$PR_HEAD" \
          --hash "$PR_HEAD_SHA" \
          --start-point "$PR_BASE" \
          --start-point-hash "$PR_BASE_SHA" \
          --start-point-clone-thresholds \
          --start-point-reset \
          --testbed ubuntu-latest \
          --error-on-alert \
          --adapter json \
          --github-actions '${{ secrets.GITHUB_TOKEN }}' \
          --ci-number "$PR_NUMBER" \
          --file "$BENCHMARK_RESULTS"

1. 创建第一个 GitHub Actions workflow 文件。 （例如：.github/workflows/fork_pr_benchmarks_track.yml）
2. 将该工作流命名为第二个工作流。 （例如：name: Track Benchmarks with Bencher）
3. 使用 workflow_run 事件 链接两个工作流。 （例如：on: workflow_run: ...）
4. 创建一个 GitHub Actions job。 （例如：jobs: track_fork_pr_branch）
5. 当上一个工作流的结论为成功时，仅运行此作业，使用GitHub Actions workflow_run 事件。 （例如：if: github.event.workflow_run.conclusion == 'success'）
6. 将GITHUB_TOKEN 的权限 设置为 checks 和 pull-requests 的 write。 根据您的 GitHub 设置，这可能不是必需的。 但对于所有在 2023 年 2 月 2 日之后创建的组织和个人仓库默认行为。 有关完整概述，请参见GitHub 文档。 （例如：permissions: checks: write pull-requests: write）
7. 设置作业运行的机器类型。 有关完整概述，请参见GitHub Actions runs-on 文档。 （例如：runs-on: ubuntu-latest）
8. 将基准测试结果和 pull_request 事件对象文件名称设置为环境变量。 （例如：env: ...）
9. 使用 action-download-artifact GitHub Action 下载缓存的基准测试结果和 pull_request 事件。 （例如：uses: dawidd6/action-download-artifact@v6）
10. 将 pull_request 事件中的必要数据导出为中间环境变量。 （例如：core.exportVariable(...)）
11. 使用GitHub Action 安装 Bencher CLI。 （例如：uses: bencherdev/bencher@main）
12. 使用bencher run CLI 子命令追踪您的 fork pull 分支基准测试。 有关完整概述，请参见bencher run CLI 子命令。 （例如：bencher run）
13. 将 --project 选项设置为项目标识符。 有关更多细节，请参见--project 文档。 （例如：--project project-abc4567-wxyz123456789）
14. 将 --key 选项设置为 BENCHER_API_KEY 仓库密钥。 有关更多细节，请参见--key 文档。 （例如：--key '${{ secrets.BENCHER_API_KEY }}'）
15. 使用中间环境变量，将 --branch 选项设置为 fork PR 分支名称。 有关完整概述，请参见--branch 文档。 （例如：--branch "$PR_HEAD"）
16. 使用中间环境变量，将 --hash 选项设置为 fork PR 分支 git 哈希值。 有关完整概述，请参见--hash 文档。 （例如：--hash "$PR_HEAD_SHA"）
17. 设置 fork PR 分支的起始点：
    1. 使用中间环境变量，将 --start-point 选项设置为 fork PR 分支起始点。 有关完整概述，请参见--start-point 文档。 （例如：--start-point "$PR_BASE"）
    2. 使用中间环境变量，将 --start-point-hash 选项设置为 fork PR 分支起始点 git 哈希。 有关完整概述，请参见--start-point-hash 文档。 （例如：--start-point-hash "$PR_BASE_SHA"）
    3. 将 --start-point-clone-thresholds 标志设置为从起始点克隆阈值。 有关完整概述，请参见--start-point-clone-thresholds 文档。 （例如：--start-point-clone-thresholds）
    4. 将 --start-point-reset 标志设置为始终将 fork PR 分支重置到起始点。 这将防止基准测试数据漂移。 有关完整概述，请参见--start-point-reset 文档。 （例如：--start-point-reset）
18. 将 --testbed 选项设置为测试床名称。 这可能应与 runs-on 中选择的机器相匹配。 有关更多细节，请参见--tested 文档。 （例如：--testbed ubuntu-latest）
19. 设置 --error-on-alert 标志以在生成警报时命令失败。 有关完整概述，请参见--error-on-alert 文档。 （例如：--error-on-alert）
20. 将 --adapter 选项设置为由bencher mock生成的Bencher Metric Format JSON (json)。 有关完整概述，请参见基准测试硬件适配器。 （例如：--adapter json）
21. 将 --github-actions 选项设置为 GitHub API 认证令牌，以使用GitHub Actions GITHUB_TOKEN 环境变量 将结果作为 GitHub 检查和评论发布在 Pull Request 上。 有关更多细节，请参见--github-actions 文档。 （例如：--github-actions '${{ secrets.GITHUB_TOKEN }}'）
22. 使用中间环境变量，将 --ci-number 选项设置为请求编号。 有关更多细节，请参见--ci-number 文档。 （例如：--ci-number "$PR_NUMBER"）
23. 将 --file 选项设置为基准测试结果文件路径。 有关完整概述，请参见基准测试命令。 （例如：--file "$BENCHMARK_RESULTS"）

要在 PR 关闭后清理 fork PR 分支，您可以创建一个单独的工作流来在 pull_request_target 事件中使用 closed 类型运行。该工作流将使用 bencher archive 命令归档 fork PR 分支。

on:
  pull_request_target:
    types: [closed]

jobs:
  archive_fork_pr_branch:
    name: Archive closed fork PR branch with Bencher
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: bencherdev/bencher@main
      - name: Archive closed fork PR branch with Bencher
        run: |
          bencher archive \
          --project project-abc4567-wxyz123456789 \
          --key '${{ secrets.BENCHER_API_KEY }}' \
          --branch "$GITHUB_HEAD_REF"

1. 创建一个 GitHub Actions workflow 文件。 （例如：.github/workflows/fork_pr_benchmarks_closed.yml）

2. 运行在 pull_request_target 事件上：

   • closed - 一个拉取请求被关闭。

   查看 GitHub Actions on 文档 和 GitHub Actions pull_request_target 文档 以获取完整概览。 （例如：on: pull_request_target: types: [closed]）

3. 创建一个 GitHub Actions job。 （例如：jobs: archive_pr_branch）

4. 设置作业运行的机器类型。 查看 GitHub Actions runs-on 文档 以获取完整概览。 （例如：runs-on: ubuntu-latest）

5. 检出 PR 分支源代码。 （例如：uses: actions/checkout@v6）

6. 使用GitHub Action 安装 Bencher CLI。 （例如：uses: bencherdev/bencher@main）

7. 使用 bencher archive CLI 子命令归档 PR 分支。 （例如：bencher archive）

8. 设置 --project 选项为项目简码。 查看--project 文档 以获取更多详情。 （例如：--project project-abc4567-wxyz123456789）

9. 设置 --key 选项为 BENCHER_API_KEY Repository 密钥。 查看--key 文档 以获取更多详情。 （例如：--key '${{ secrets.BENCHER_API_KEY }}'）

10. 设置 --branch 选项为 PR 分支名称，使用GitHub Actions GITHUB_HEAD_REF 默认环境变量。 （例如：--branch "$GITHUB_HEAD_REF"）

裸机上的 Pull Requests

GitHub Actions 提供自托管运行器， 但它们要求您使用其噪声较大的 GitHub Actions Runner 二进制文件。 Bencher Bare Metal 使用专门打造的低噪声基准测试运行器， 在专用的裸机硬件集群上运行基准测试。 此外，Bencher Bare Metal 支持来自 Fork 的 PR， 而 GitHub Actions Runner 不支持。

一旦您切换到 Bencher Bare Metal， 您就不会希望在等待 Bencher 时还有一个 GitHub Actions 作业在运行。 为了解决这个问题，Bencher 使用拆分的工作流， 使 GitHub Actions 能够异步等待 Bencher Bare Metal 的 Job。

以下示例适用于同一仓库内的分支。 将此模式与上面的来自 Fork 的拉取请求工作流结合使用， 即可为 Fork PR 提供裸机基准测试。

on:
  pull_request:
    types: [opened, reopened, edited, synchronize]

jobs:
  submit_pr_benchmarks:
    name: Submit PR Benchmarks to Bencher Bare Metal
    # DO NOT REMOVE: For handling Fork PRs see Pull Requests from Forks
    if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
    permissions:
      checks: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: bencherdev/bencher@main
      - name: Submit PR Benchmarks with Bencher
        run: |
          bencher run \
          --project project-abc4567-wxyz123456789 \
          --key '${{ secrets.BENCHER_API_KEY }}' \
          --branch "$GITHUB_HEAD_REF" \
          --start-point "$GITHUB_BASE_REF" \
          --start-point-hash '${{ github.event.pull_request.base.sha }}' \
          --start-point-clone-thresholds \
          --start-point-reset \
          --adapter json \
          --image project-abc4567-wxyz123456789:latest \
          --detach \
          --github-actions '${{ secrets.GITHUB_TOKEN }}' \
          --ci-callback-token '${{ secrets.BENCHER_CALLBACK_TOKEN }}' \
          bencher mock

1. 创建第一个 GitHub Actions workflow 文件。 （例如：.github/workflows/pr_bare_metal_benchmarks.yml）
2. 像上面的拉取请求一样，在 pull_request 事件上运行。 （例如：on: pull_request: types: [opened, reopened, edited, synchronize]）
3. 创建一个 GitHub Actions job。 （例如：jobs: submit_pr_benchmarks）
4. 如果且仅当拉取请求来自同一仓库时，在 pull_request 事件上运行。 ⚠️ 不要删除此行！ 处理 Fork PR 请参见上面的来自 Fork 的拉取请求。 （例如：if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository）
5. 将 GITHUB_TOKEN 的权限 设置为 write 以用于 checks。 第一个工作流会启动 GitHub 检查，但不会发布评论。 （例如：permissions: checks: write）
6. 设置运行作业的机器类型。 它只提交 Job，因此一台小型机器就足够了。 （例如：runs-on: ubuntu-latest）
7. 检出 PR 分支的源代码。 （例如：uses: actions/checkout@v6）
8. 使用 GitHub Action 安装 Bencher CLI。 （例如：uses: bencherdev/bencher@main）
9. 使用 bencher run CLI 子命令提交您的拉取请求分支基准测试。 查看 bencher run CLI 子命令 以获取完整概览。 （例如：bencher run）
10. 将 --project 选项设置为项目 slug。 查看 --project 文档 以获取详细信息。 （例如：--project project-abc4567-wxyz123456789）
11. 将 --key 选项设置为 BENCHER_API_KEY 仓库密钥。 查看 --key 文档 以获取详细信息。 （例如：--key '${{ secrets.BENCHER_API_KEY }}'）
12. 使用 GitHub Actions GITHUB_HEAD_REF 默认环境变量 设置 --branch 选项为 PR 分支名称。 查看 --branch 文档 以获取完整概览。 （例如：--branch "$GITHUB_HEAD_REF"）
13. 像上面的拉取请求一样，设置 PR 分支的起点。 查看 --start-point 文档 以获取完整概览。 （例如：--start-point "$GITHUB_BASE_REF"）
14. 将 --adapter 选项设置为由 bencher mock 生成的 Bencher Metric Format JSON (json)。 查看 基准测试工具适配器 以获取完整概览。 （例如：--adapter json）
15. 将 --image 选项设置为您的裸机镜像。 查看 --image 文档 以获取完整概览。 （例如：--image project-abc4567-wxyz123456789:latest）
16. 设置 --detach 标志，以便在 Job 提交后立即退出。 查看 --detach 文档 以获取详细信息。 （例如：--detach）
17. 使用 GitHub Actions GITHUB_TOKEN 环境变量 将 --github-actions 选项设置为 GitHub API 身份验证令牌，以启动 GitHub 检查。 查看 --github-actions 文档 以获取详细信息。 （例如：--github-actions '${{ secrets.GITHUB_TOKEN }}'）
18. 将 --ci-callback-token 选项设置为 BENCHER_CALLBACK_TOKEN 仓库密钥， 以便 Bencher 能在 Job 完成时发送 repository_dispatch 事件。 查看 --ci-callback-token 文档 以获取详细信息。 （例如：--ci-callback-token '${{ secrets.BENCHER_CALLBACK_TOKEN }}'）
19. 指定在镜像中运行的基准测试命令。 如果镜像有入口点，该命令会传给该入口点（参见 --entrypoint 选项）。 查看 基准测试命令 以获取完整概览。 （例如：bencher mock）

on:
  repository_dispatch:
    types: [bencher_run]

jobs:
  attach_pr_benchmarks:
    name: Post PR Benchmark Results from Bencher Bare Metal
    permissions:
      checks: write
      pull-requests: write
    runs-on: ubuntu-latest
    steps:
      - uses: bencherdev/bencher@main
      - name: Post PR Benchmark Results with Bencher
        env:
          JOB_UUID: ${{ github.event.client_payload.bencher.job }}
        run: |
          bencher run \
          --project project-abc4567-wxyz123456789 \
          --key '${{ secrets.BENCHER_API_KEY }}' \
          --job "$JOB_UUID" \
          --error-on-alert \
          --github-actions '${{ secrets.GITHUB_TOKEN }}'

1. 在默认分支上创建第二个 GitHub Actions workflow 文件。 GitHub 只会从默认分支运行 repository_dispatch 工作流， 因此在该文件出现在默认分支之前，第一个工作流启动的 GitHub 检查会一直保持进行中。 （例如：.github/workflows/pr_bare_metal_benchmarks_attach.yml）
2. 在类型为 bencher_run 的 repository_dispatch 事件上运行。 查看 GitHub Actions on 文档 和 GitHub Actions repository_dispatch 文档 以获取完整概览。 （例如：on: repository_dispatch: types: [bencher_run]）
3. 创建一个 GitHub Actions job。 （例如：jobs: attach_pr_benchmarks）
4. 将 GITHUB_TOKEN 的权限 设置为 write 以用于 checks 和 pull-requests。 （例如：permissions: checks: write pull-requests: write）
5. 设置运行作业的机器类型。 Job 已经完成，因此该作业只发布结果。 （例如：runs-on: ubuntu-latest）
6. 使用 GitHub Action 安装 Bencher CLI。 不需要检出代码。 （例如：uses: bencherdev/bencher@main）
7. 按照 GitHub 关于脚本注入的指导，通过中间环境变量传递事件中的 Job UUID，切勿直接写在 run: 中。 （例如：env: JOB_UUID: ${{ github.event.client_payload.bencher.job }}）
8. 使用 bencher run CLI 子命令连接到该 Job。 查看 bencher run CLI 子命令 以获取完整概览。 （例如：bencher run）
9. 将 --project 选项设置为项目 slug。 如果仓库有多个项目，请以同样的方式通过环境变量传递 github.event.client_payload.bencher.project，并用引号括起来（例如：--project "$PROJECT_SLUG"）。 查看 --project 文档 以获取详细信息。 （例如：--project project-abc4567-wxyz123456789）
10. 将 --key 选项设置为 BENCHER_API_KEY 仓库密钥。 查看 --key 文档 以获取详细信息。 （例如：--key '${{ secrets.BENCHER_API_KEY }}'）
11. 将 --job 选项设置为加上引号的 Job UUID。 查看 --job 文档 以获取完整概览。 （例如：--job "$JOB_UUID"）
12. 设置 --error-on-alert 标志，以便在生成警报时使命令失败。 事件只携带数据，因此决定结果如何发布的选项，例如 --ci-only-on-alert 和 --ci-public-links，也放在这里，即第二个工作流中。 查看 --error-on-alert 文档 以获取完整概览。 （例如：--error-on-alert）
13. 使用 GitHub Actions GITHUB_TOKEN 环境变量 将 --github-actions 选项设置为 GitHub API 身份验证令牌，以将结果发布为 GitHub 检查和拉取请求评论。 在这里显式指定的 --ci-number 或 --ci-id 优先于事件。 查看 --github-actions 文档 以获取详细信息。 （例如：--github-actions '${{ secrets.GITHUB_TOKEN }}'）

🐰 恭喜你！你已经学会了如何在 GitHub Actions 中使用 Bencher！🎉

继续了解：基准测试概述 ➡