如何在 GitHub Actions 中使用 Bencher

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

确保您已创建项目 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 中的性能回归。

.github/workflows/base_benchmarks.yml
name: Base Branch Benchmarks with Bencher


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. 为此工作流程命名。 (例如：name: Base Branch Benchmarks with Bencher)
  3. 在 main 分支的 push 事件上运行。 请参阅 GitHub Actions on 文档 和 GitHub Actions push 文档 以获得完整概述。 (例如：on: push: branches: main)
  4. 创建一个 GitHub Actions job。 (例如：jobs: benchmark_base_branch)
  5. 将GITHUB_TOKEN 的权限设置为对checks具有write权限。 （例如：permissions: checks: write）
  6. 设置运行该作业的机器类型。 请参阅 GitHub Actions runs-on 文档 以获取完整概述。 (例如：runs-on: ubuntu-latest)
  7. 检出您的基础分支源代码。 (例如：uses: actions/checkout@v6)
  8. 使用 GitHub Action 安装 Bencher CLI。 (例如：uses: bencherdev/bencher@main)
  9. 使用 bencher run CLI 子命令 来运行您的 main 分支基准测试。 请参阅 bencher run CLI 子命令 以获取完整概述。 (例如：bencher run)
  10. 将 --project 选项设置为项目标识符。 请参阅 --project 文档 了解更多详情。 (例如：--project project-abc4567-wxyz123456789)
  11. 将 --key 选项设置为 BENCHER_API_KEY 存储库密钥。 请参阅 --key 文档 了解更多详情。 (例如：--key '${{ secrets.BENCHER_API_KEY }}')
  12. 将 --branch 选项设置为基础分支名称。 请参阅 --branch 文档 了解完整概述。 (例如：--branch main)
  13. 将 --testbed 选项设置为测试平台名称。 这应与在 runs-on 中选择的机器相匹配。 请参阅 --tested 文档 了解更多详情。 (例如：--testbed ubuntu-latest)
  14. 为 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)
  15. 设置 --error-on-alert 标志，如果生成警报，则使命令失败。 请参阅 --error-on-alert 文档 了解完整概述。 (例如：--error-on-alert)
  16. 将 --adapter 选项设置为 Bencher Metric Format JSON (json)，该格式由 bencher mock 生成。 请参阅 基准配置适配器 了解完整概述。 (例如：--adapter json)
  17. 设置 --github-actions 选项为 GitHub API 身份验证令牌，以使用 GitHub Actions GITHUB_TOKEN 环境变量 作为 GitHub Checks 评论发布结果。 请参阅 --github-actions 文档 了解更多详情。 (例如：--github-actions '${{ secrets.GITHUB_TOKEN }}')
  18. 指定基准测试命令参数。 请参阅 基准测试命令 了解完整概述。 (例如：bencher mock)

Pull Requests

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

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

.github/workflows/pr_benchmarks.yml
name: PR Benchmarks with Bencher


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" \
          --hash '${{ github.event.pull_request.head.sha }}' \
          --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. 为此工作流程命名。 （例如：name: PR Benchmarks with Bencher）

  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_pr_branch）

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

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

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

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

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

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

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

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

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

  14. 使用 GitHub Actions pull_request 事件 将 --hash 选项设置为 PR 分支的 git hash。 在 pull_request 事件中，actions/checkout 检出的是合并提交，而不是 PR 的某个提交。 查看 --hash 文档 以获取完整概览。 （例如：--hash '${{ github.event.pull_request.head.sha }}'）

  15. 设置 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）

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

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

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

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

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

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

.github/workflows/pr_benchmarks_closed.yml
name: Archive Closed PR Branch with Bencher


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. 为此工作流程命名。 (例如：name: Archive Closed PR Branch with Bencher)

  3. 运行于 pull_request 事件：

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

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

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

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

  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 archive CLI 子命令归档 PR 分支。 (例如：bencher archive)

  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 "$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 工作流中，因为它们在那里不可用。这些工作流仅在它们存在于_默认_分支时才会运行。有关完整概述，请参阅使用触发工作流的数据。

.github/workflows/fork_pr_benchmarks_run.yml
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）

.github/workflows/fork_pr_benchmarks_track.yml
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@v9
        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 分支。

.github/workflows/fork_pr_benchmarks_closed.yml
name: Archive Closed Fork PR Branch with Bencher


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. 为此工作流程命名。 （例如：name: Archive Closed Fork PR Branch with Bencher）

  3. 运行在 pull_request_target 事件上：

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

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

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

  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 选项为项目简码。 查看--project 文档 以获取更多详情。 （例如：--project project-abc4567-wxyz123456789）

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

  11. 设置 --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 提供裸机基准测试。

首先，将仓库与项目关联一次：

  1. 在 Bencher 控制台中，打开项目的 Settings，然后打开 Connections。
  2. 在 GitHub 卡片上，点击 Link repository。 GitHub 会将您带回 Connections，卡片会列出您可以推送的每个仓库。
  3. 点击仓库旁边的 Link。 如果仓库不在列表中，请点击 Install on GitHub，并授予应用对该仓库的访问权限。 如果仓库显示 Approval required，请点击 Approve on GitHub 并批准应用的新权限，然后重新打开 Connections 并点击 Link repository。

关联仓库需要项目的 Maintainer 角色（组织的 Leader 和服务器管理员拥有该角色）以及对该仓库的推送权限。 由于 repository_dispatch 不接受更低的权限，Bencher 的 GitHub App 需要对仓库内容的读写权限。 Job 完成时，Bencher 会为关联的仓库创建一个令牌，并使用该令牌发送 repository_dispatch 事件。 如果 GitHub 卡片显示 Disconnected，请点击 Install on GitHub 并重新授予应用对该仓库的访问权限，或者解除应用安装的暂停，关联随即恢复。 对于 Bencher Self-Hosted，服务器需要自己的 GitHub App以及 v0.6.16 或更高版本。

.github/workflows/pr_bare_metal_benchmarks.yml
name: Bare Metal PR Benchmarks with Bencher


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

在 GitHub Enterprise Server 上，或者要继续使用您自己的令牌，请将 --ci-callback-token 选项设置为一个对仓库内容具有读写权限的细粒度个人访问令牌， 并将其存储为 BENCHER_CALLBACK_TOKEN 仓库密钥。 无论项目是否有关联的仓库，Bencher 都会使用该令牌发送 repository_dispatch 事件。 查看 --ci-callback-token 文档 以获取详细信息。 （例如：--ci-callback-token '${{ secrets.BENCHER_CALLBACK_TOKEN }}'）

.github/workflows/pr_bare_metal_benchmarks_attach.yml
name: Attach Bare Metal PR Benchmarks with Bencher


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


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


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

🤖 该文档由 AI 自动翻译。 它可能不准确并且可能包含错误。 如果您发现任何错误，请在 GitHub 上提出问题.

Published: Fri, October 27, 2023 at 8:40:00 AM UTC | Last Updated: Wed, October 28, 2026 at 5:53:42 AM UTC