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 }}
は空の文字列になります。
ベースブランチ
統計的継続的ベンチマーキングの基礎は、ベースブランチの履歴ベースラインを持つことです。 この履歴ベースラインを使用して、プルリクエストにおけるパフォーマンスの退行を検出することができます。
- GitHub Actionsの
workflow
ファイルを作成します。 (例:.github/workflows/base_benchmarks.yml
) main
ブランチへのpush
イベントで実行します。 詳細については、GitHub Actionsのon
ドキュメントおよびGitHub Actionsのpush
ドキュメントを参照してください。 (例: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
で選択されたマシンと一致する必要があります。 詳細については、--testbed
ドキュメントを参照してください。 (例:--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
) bencher mock
によって生成されるBencher Metric Format JSON(json
)を--adapter
オプションに設定します。 詳細については、ベンチマークハーネスアダプタを参照してください。 (例:--adapter json
)- 結果をGitHub Checksコメントとして投稿するために、GitHub Actions
GITHUB_TOKEN
環境変数を使用して、--github-actions
オプションをGitHub API認証トークンに設定します。 詳細については、--github-actions
ドキュメントを参照してください。 (例:--github-actions '${{ secrets.GITHUB_TOKEN }}'
) - ベンチマークコマンド引数を指定します。
詳細については、ベンチマークコマンドを参照してください。
(例:
bencher mock
)
プルリクエスト
プルリクエストでパフォーマンスのリグレッションをキャッチするには、PRでベンチマークを実行する必要があります。
同じリポジトリ内のブランチからのみPRがある場合には、同じリポジトリからのpull_request
イベントを実行する別のワークフローを作成するだけで済みます。
⚠️ この解決策は、同じリポジトリからの全てのPRに対してのみ機能します! 下のフォークからのプルリクエストを参照してください。
-
GitHub Actionsの
workflow
ファイルを作成します。 (例:.github/workflows/pr_benchmarks.yml
) -
pull_request
イベントで実行します:opened
- プルリクエストが作成されました。reopened
- 以前にクローズされたプルリクエストが再オープンされました。edited
- プルリクエストのタイトルまたは本文が編集されたか、ベースブランチが変更されました。synchronize
- プルリクエストのヘッドブランチが更新されました。 例えば、ベースブランチからヘッドブランチが更新されたり、新しいコミットがヘッドブランチにプッシュされました。
詳細は、GitHub Actionsの
on
ドキュメントとGitHub Actionsのpull_request
ドキュメントを参照してください。 (例:on: pull_request: types: [opened, reopened, edited, synchronize]
) -
GitHub Actionsの
job
を作成します。 (例:jobs: benchmark_pr_branch
) -
プルリクエストが同じリポジトリからの場合にのみ、
pull_request
イベントを実行します。 ⚠️ この行を削除しないでください! フォークPRの取り扱いについては、下のフォークからのプルリクエストを参照してください。 (例:if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
) -
GITHUB_TOKEN
の権限を設定 して、pull-requests
に対してwrite
にします。 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
オプションをプロジェクトスラグに設定します。 詳細はこちらの--project
ドキュメントを参照してください。 (例:--project save-walter-white-1234abcd
) -
--token
オプションをBENCHER_API_TOKEN
リポジトリシークレットに設定します。 詳細はこちらの--token
ドキュメントを参照してください。 (例:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
--branch
オプションをPRブランチ名に設定し GitHub Actionsのgithub
コンテキストを使用します。 詳細はこちらの--branch
ドキュメントを参照してください。 (例:--branch '${{ github.head_ref }}'
) -
PRブランチの開始ポイントを設定します:
--start-point
オプションをPRブランチの開始ポイントに設定し GitHub Actionsのgithub
コンテキストを使用します。 詳細はこちらの--start-point
ドキュメントを参照してください。 (例:--start-point '${{ github.base_ref }}'
)--start-point-hash
オプションをPRブランチの開始ポイントgit
ハッシュに設定し GitHub Actionsのpull_request
イベントを使用します。 詳細はこちらの--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
)
-
--testbed
オプションをテストベッド名に設定します。 これはおそらくruns-on
で選択されたマシンと一致するはずです。 詳細はこちらの--tested
ドキュメントを参照してください。 (例:--testbed ubuntu-latest
) -
アラートが発生した場合にコマンドが失敗するよう、
--err
フラグを設定します。 詳細はこちらの--err
ドキュメントを参照してください。 (例:--err
) -
bencher mock
により生成されるBencher Metric Format JSON (json
)への--adapter
オプションを設定します。 詳細はベンチマークハーネスアダプターを参照してください。 (例:--adapter json
) -
GitHub API認証トークンを使用してプルリクエストにコメントとして結果を投稿するために、
--github-actions
オプションを GitHub ActionsのGITHUB_TOKEN
環境変数に設定します。 詳細はこちらの--github-actions
ドキュメントを参照してください。 (例:--github-actions '${{ secrets.GITHUB_TOKEN }}'
) -
ベンチマークコマンドの引数を指定します。 詳細はベンチマークコマンドを参照してください。 (例:
bencher mock
)
GitHubのPRがクローズされた後にPRブランチをクリーンアップするためには、on
pull_request
イベントの closed
タイプを使用して実行する別のワークフローを作成できます。このワークフローは、bencher archive
コマンドを使用してPRブランチをアーカイブします。
-
GitHub Actionsの
workflow
ファイルを作成します。 (例:.github/workflows/pr_benchmarks_closed.yml
) -
pull_request
イベントで実行します:closed
- プルリクエストがクローズされた。
詳細はGitHub Actionsの
on
ドキュメントおよびGitHub Actionsのpull_request
ドキュメントを参照してください。 (例:on: pull_request: types: [closed]
) -
GitHub Actionsの
job
を作成します。 (例:jobs: archive_pr_branch
) -
プルリクエストが同じリポジトリからの場合にのみ
pull_request
イベントを実行します。 ⚠️ この行を削除しないでください! フォークからのPRを処理する方法については、以下のフォークからのプルリクエストを参照してください。 (例: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
) -
Bencher CLIをGitHub Actionを使用してインストールします。 (例:
uses: bencherdev/bencher@main
) -
bencher archive
CLIサブコマンドを使用してPRブランチをアーカイブします。 (例:bencher archive
) -
プロジェクトスラッグに
--project
オプションを設定します。 詳細は--project
のドキュメントを参照してください。 (例:--project save-walter-white-1234abcd
) -
--token
オプションをBENCHER_API_TOKEN
リポジトリシークレットに設定します。 詳細は--token
のドキュメントを参照してください。 (例:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
GitHub Actionsの
github
コンテキストを使用して、PRブランチ名に--branch
オプションを設定します。 (例:--branch '${{ github.head_ref }}'
)
フォークからのプルリクエスト
公開のオープンソースプロジェクトでよくあるようにフォークからのプルリクエストを受け入れる予定の場合、少し異なる方法で処理する必要があります。
セキュリティ上の理由から、フォークのプルリクエストでは BENCHER_API_TOKEN
や GITHUB_TOKEN
などのシークレットは GitHub Actions で利用できません。
つまり、外部のコントリビューターがフォークから PR を作成すると、上記の例は 動作しません。
完全な概要については、この GitHub Security Lab の説明 と、
この ブログ記事 を参照してください。
これはフォークからのプルリクエストに 継続的ベンチマーク を追加するための安全で推奨される方法です。
これには2つの別々のワークフローが必要です。
最初のワークフローは pull_request
コンテキストでベンチマーク結果を実行し、キャッシュします。
そこでは BENCHER_API_TOKEN
や GITHUB_TOKEN
のようなシークレットは利用できません。
次に、2番目のワークフローが workflow_run
コンテキストでキャッシュされたベンチマーク結果をダウンロードし、それを Bencher にアップロードします。
これは、workflow_run
がシークレットである BENCHER_API_TOKEN
や GITHUB_TOKEN
が利用可能なリポジトリのデフォルトブランチのコンテキストで実行されるためです。
元の pull_request
ワークフローで使用されたプルリクエスト番号、ヘッドブランチ、ベースブランチも、workflow_run
ワークフローに明示的に渡される必要があります。
これらのワークフローは、デフォルト ブランチに存在する場合にのみ実行されます。
完全な概要については、トリガーワークフローのデータの使用 を参照してください。
-
最初のGitHub Actionsの
workflow
ファイルを作成します。 (例:.github/workflows/fork_pr_benchmarks_run.yml
) -
このワークフローに名前を付けて、2番目のワークフローから参照できるようにします。 (例:
name: Run Benchmarks
) -
pull_request
イベントで実行します:opened
- プルリクエストが作成されました。reopened
- 閉じられていたプルリクエストが再度開かれました。edited
- プルリクエストのタイトルや本文が編集されたり、ベースブランチが変更されました。synchronize
- プルリクエストのヘッドブランチが更新されました。 例えば、ベースブランチからヘッドブランチが更新されたり、新しいコミットがヘッドブランチにプッシュされました。
GitHub Actionsの
on
ドキュメンテーションと GitHub Actionsのpull_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
) -
フォークされた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
) - このワークフローに第2のワークフローとして名前を付けます。
(例:
name: Track Benchmarks with Bencher
) -
workflow_run
イベントを使用して2つのワークフローを連鎖させます。 (例: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: ...
) - キャッシュされたベンチマーク結果と
pull_request
イベントをダウンロードします。action-download-artifact
GitHub Actionを使用してください。 (例:uses: dawidd6/action-download-artifact@v6
) pull_request
イベントから必要なデータを環境変数としてエクスポートします。 (例:core.exportVariable(...)
)- Bencher CLIをインストールします。GitHub Actionを使用してください。
(例:
uses: bencherdev/bencher@main
) bencher run
CLIサブコマンドを使用して、フォークプルブランチのベンチマークを追跡します。 完全な概要については、bencher run
CLIサブコマンド を参照してください。 (例:bencher run
)--project
オプションをプロジェクトスラッグに設定します。 詳細については、--project
ドキュメントを参照してください。 (例:--project save-walter-white-1234abcd
)--token
オプションをBENCHER_API_TOKEN
リポジトリシークレットに設定します。 詳細については、--token
ドキュメントを参照してください。 (例:--token '${{ secrets.BENCHER_API_TOKEN }}'
)--branch
オプションをフォークPRブランチ名に設定します。[GitHub Actionsgithub
コンテキスト][github actions context]を使用してください。 完全な概要については、--branch
ドキュメント を参照してください。 (例:--branch '${{ env.PR_HEAD }}'
)- フォークPRブランチの開始ポイントを設定します:
--start-point
オプションをフォークPRブランチの開始ポイントに設定します。[GitHub Actionsgithub
コンテキスト][github actions context]を使用します。 完全な概要については、--start-point
ドキュメントを参照してください。 (例:--start-point '${{ env.PR_BASE }}'
)--start-point-hash
オプションをフォークPRブランチの開始ポイントgit
ハッシュに設定します。GitHub Actionspull_request
イベントを使用してください。 完全な概要については、--start-point-hash
ドキュメントを参照してください。 (例:--start-point-hash '${{ env.PR_BASE_SHA }}'
)--start-point-clone-thresholds
フラグを設定して、開始ポイントからしきい値をクローンします。 完全な概要については、--start-point-clone-thresholds
ドキュメントを参照してください。 (例:--start-point-clone-thresholds
)--start-point-reset
フラグを設定して、常にフォークPRブランチを開始ポイントにリセットします。 これにより、ベンチマークデータのドリフトを防ぎます。 完全な概要については、--start-point-reset
ドキュメントを参照してください。 (例:--start-point-reset
)
--testbed
オプションをテストベッドの名前に設定します。 これは、おそらくruns-on
で選択されたマシンと一致する必要があります。 詳細については、--tested
ドキュメントを参照してください。 (例:--testbed ubuntu-latest
)--err
フラグを設定し、アラートが生成された場合にコマンドを失敗させます。 完全な概要については、--err
ドキュメントを参照してください。 (例:--err
)--adapter
オプションを Bencher Metric Format JSON (json
) に設定します。これはbencher mock
によって生成されます。 完全な概要については、ベンチマークハーネスアダプター を参照してください。 (例:--adapter json
)--github-actions
オプションをGitHub API認証トークンに設定し、プルリクエストへのコメントとして結果を投稿します。GitHub ActionsGITHUB_TOKEN
環境変数を使用します。 詳細については、--github-actions
ドキュメントを参照してください。 (例:--github-actions '${{ secrets.GITHUB_TOKEN }}'
)--ci-number
オプションをプルリクエスト番号に設定します。 詳細については、--ci-number
ドキュメントを参照してください。 (例:--ci-number '${{ env.PR_NUMBER }}'
)--file
オプションをベンチマーク結果のファイルパスに設定します。 完全な概要については、ベンチマークコマンド を参照してください。 (例:--file "$BENCHMARK_RESULTS"
)
フォークPRの閉鎖後にそのブランチをクリーンアップするためには、on
pull_request
イベントを closed
タイプで実行する別のワークフローを作成することができます。このワークフローは、bencher archive
コマンドを使用して、フォークPRブランチをアーカイブします。
-
GitHub Actionsの
workflow
ファイルを作成します。 (例:.github/workflows/fork_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
) -
ジョブを実行するマシンの種類を設定します。 詳細はGitHub Actions
runs-on
ドキュメントを参照してください。 (例:runs-on: ubuntu-latest
) -
PRブランチのソースコードをチェックアウトします。 (例:
uses: actions/checkout@v4
) -
GitHub Actionを使用してBencher CLIをインストールします。 (例:
uses: bencherdev/bencher@main
) -
PRブランチをアーカイブするために、
bencher archive
CLIサブコマンドを使用します。 (例:bencher archive
) -
--project
オプションをプロジェクトスラッグに設定します。 詳細は--project
ドキュメントを参照してください。 (例:--project save-walter-white-1234abcd
) -
--token
オプションをBENCHER_API_TOKEN
リポジトリシークレットに設定します。 詳細は--token
ドキュメントを参照してください。 (例:--token '${{ secrets.BENCHER_API_TOKEN }}'
) -
GitHub Actions
github
コンテキストを使用してPRブランチ名を--branch
オプションに設定します。 (例:--branch '${{ github.head_ref }}'
)
🐰 おめでとうございます!GitHub ActionsでBencherを使用する方法を学びました!🎉