HN 日本語サマリー

← 一覧へ戻る
プログラミング

FailTrace – URLからローカルで失敗したGitHub Actions実行を再現

FailTrace – Reproduce a failed GitHub Actions run locally from its URL (github.com)

23 pointsby ri4dh5 コメント

要約

FailTraceは、失敗したGitHub Actions実行のURLから、ローカル環境でその失敗を再現するためのツールです。失敗したジョブやステップを特定し、ワークフローファイルとログを解析して、ローカルでの再現に必要な情報を提供します。これにより、CIの失敗原因の特定とデバッグが容易になります。

全文翻訳

FailTrace

[画像: CI] [画像: Latest release] [画像: License: MIT]

CIが失敗した理由を推測するのをやめましょう。ローカルで再現しましょう。

[画像: FailTraceがDockerでstretchr/testifyのCI実行失敗を再現している様子]

失敗したGitHub Actions実行のURLを貼り付けるだけです。FailTraceは、失敗したジョブとステップを見つけ、その正確なコミットのワークフローファイルと照合し、ログから失敗箇所を抽出し、ローカルマシンで再現するのを妨げているものを教えてくれます。

failtrace inspect https://github.com/owner/repo/actions/runs/123456789   # なぜ失敗したのか?
failtrace plan    https://github.com/owner/repo/actions/runs/123456789   # どのように再現されるか?
failtrace repro   https://github.com/owner/repo/actions/runs/123456789   # Dockerで再現する

ステータス: 初期開発段階。 3つのコマンドすべてが動作します。reproは、失敗したステップがrun:スクリプトであるLinuxジョブに対応しています。ロードマップと制限事項を参照してください。

なぜactではないのか?

actはワークフローをローカルで実行し、その点では優れています。FailTraceは異なる質問に答えます。「この特定の実行がなぜ失敗したのか、そしてここで同じように失敗させることができるか?」

  • 失敗した実行から開始するのではなく、ワークフローファイルから開始します。 正確なコミット、試行、ジョブ、マトリックスの組み合わせ、失敗したステップを取得できます。設定は不要です。
  • 失敗に焦点を当てます。 目標は、ワークフロー全体ではなく、失敗したステップに必要なものだけを再生することです。
  • 診断結果を提供します。 今すぐ診断結果が得られます。後には、再現された/再現されていない/不安定、およびCIとローカルマシンとの違いも表示されます。

例

失敗したprometheus/prometheus実行の実際の出力(トリミング済み):

✗ CI · prometheus/prometheus
  "remote/otlp: remove delta-to-cumulative conversion"
  pull_request · on codex/remove-otlp-deltatocumulative · @ cf7d324 · attempt 1 · failure

────────────────────────────────────────────────────────────
✗ Job: Go tests  (failure)
  Runner     ubuntu-latest → ubuntu-26.04 (20261116.202.1) · runner 2.338.2
  Workflow   .github/workflows/ci.yml → jobs.test_go

  Steps
    ✓  5  Run make GO_ONLY=1 SKIP_GOLANGCI_LINT=1
    ✓  6  Run go test ./tsdb/ -test.tsdb-isolation=false
    ✗  7  Run make -C documentation/examples/remote_storage  ← ここで失敗
    ○  8  Run make -C documentation/examples (skipped)

  Failed step  #7 Run make -C documentation/examples/remote_storage
    shell: sh -e {0}
    $ make -C documentation/examples/remote_storage

  Diagnosis  files out of date (a check produced a git diff) · exit code 2

  Log excerpt (Log excerpt (10 lines around the first error in "Run make -C documentation/examples/remote_storage"))
    │ >> running check for unused/missing packages in go.mod
    │ go mod tidy
    │ go: downloading github.com/oapi-codegen/nullable v1.1.0
    │ diff --git a/documentation/examples/remote_storage/go.mod b/documentation/examples/remote_storage/go.mod
    │ --- a/documentation/examples/remote_storage/go.mod
    │ +++ b/documentation/examples/remote_storage/go.mod

  Reproduction notes
    ! job runs inside container quay.io/prometheus/golang-builder:1.27-base

ログは数百行にわたるgo.sumの差分で終わります。FailTraceは、その後のノイズではなく、原因であるgo mod tidyがgo.modを変更していることを示す最初のエラー行を中心にログ抜粋を中央揃えします。

インストール

macOSおよびLinuxでは、インストールスクリプトを使用します。これは、お使いのプラットフォーム用の最新リリースをダウンロードし、そのSHA-256チェックサムを検証します。

curl -fsSL https://raw.githubusercontent.com/Ri4dH/failtrace/main/scripts/install.sh | sh

書き込み可能な場合は/usr/local/binに、そうでない場合は~/.local/binにインストールします。インストール先を選択するにはFAILTRACE_INSTALL_DIRを、リリースを固定するにはFAILTRACE_VERSION=v0.1.0を設定してください。

macOS、Linux、Windows(amd64およびarm64)用の事前ビルド済みバイナリは、リリースページにchecksums.txtとともにあります。

Go 1.24+ を使用する場合:

go install github.com/Ri4dH/failtrace/cmd/failtrace@latest

ソースからビルドする場合:

git clone https://github.com/Ri4dH/failtrace
cd failtrace
go build -o bin/failtrace ./cmd/failtrace

使用方法

# ランの最新試行におけるすべての失敗したジョブ
failtrace inspect https://github.com/owner/repo/actions/runs/123456789

# 単一のジョブ(Actions UIでジョブをクリックして取得するURL)
failtrace inspect https://github.com/owner/repo/actions/runs/123456789/job/987654321

# 再実行ワークフローの特定の試行
failtrace inspect https://github.com/owner/repo/actions/runs/123456789/attempts/2

# より多くのログコンテキストを表示するか、スクリプトや他のツール用にJSONを出力する
failtrace inspect -n 60 <run-url>
failtrace inspect --json <run-url> | jq '.failed_jobs[0].failure'
フラグデフォルト説明
--jsonoffレポートをJSON形式で出力する
-n, --lines25失敗したステップから表示するログ行数
--jobすべての失敗このジョブIDのみを検査する

カラー出力は、標準出力がターミナルでない場合、またはNO_COLORが設定されている場合に自動的にオフになります。

認証

FailTraceは、ログAPIがトークンを必要とするため、公開リポジトリでもGitHubトークンが必要です。以下の順序で検索します。

  1. GITHUB_TOKEN
  2. GH_TOKEN
  3. gh auth token(GitHub CLIを使用している場合、これは既に機能します)

プライベートリポジトリには、そのリポジトリのアクションを読み取る権限を持つトークンが必要です。GitHub Enterprise ServerのURLも機能します。APIのベースはhttps://<host>/api/v3になります。

inspectが報告するもの

  • 実行コンテキスト: ワークフロー、イベント、ブランチ、コミット、試行。

  • ジョブ → ワークフローのマッピング: test (ubuntu-latest, 1.22)やLint ${{ matrix.tool }}のような名前のジョブ、およびマトリックス値の復旧を含め、ジョブ定義を見つけます。

  • ランナー: 要求されたラベルと、ログからの実際のランナーイメージとバージョン。

  • 失敗したステップ: その定義(run、uses、with、env、シェル、作業ディレクトリ)。表示されるコマンドは、ログに表示されるコマンドで、式は既に展開されています。

  • 診断: 終了コード、エラーアノテーション、失敗したテスト名(Go、pytest、Jest、Vitest、Cargo、RSpec)、およびカテゴリ:

    カテゴリ例示信号
    test--- FAIL: TestX, FAILED tests/x.py::test_y
    builderror TS2304, undefined: foo, error[E0425]
    dependencynpm ERR! code ERESOLVE, missing go.sum entry
    lintgolangci-lint, eslint, ruff ステップ
    generated-diffdiff --git を出力したチェック(tidy、codegen、formatter)
    timeoutexceeded the maximum execution time
    out-of-memoryexit code 137, heap out of memory
  • 再現ノート: ローカルでの再現を困難にするもの。サービスコンテナ、ジョブコンテナ、ステップが使用するシークレット、再利用可能なワークフロー、macOSまたはWindowsランナーなど。

実行がジョブ開始前に失敗した場合、リポジトリにファイルがない動的ワークフロー、ログが期限切れになった場合などのエッジケースも、サイレントに失敗するのではなく説明します。

再現の計画

failtrace planは、ローカルで失敗したジョブを再現する方法を計算し、計画を出力します。まだ何も実行しません。

failtrace plan https://github.com/owner/repo/actions/runs/123456789
failtrace plan --job 987654321 <run-url>     # 複数のジョブが失敗した場合に選択
failtrace plan --json <run-url>              # すべての環境変数を含む完全な計画

失敗したpytest-dev/pytestジョブの実際の出力(トリミング済み):

Reproduction plan · pytest-dev/pytest
  Job        build (ubuntu-py311)  (jobs.build)
  Verdict    PARTIAL: can run, but the warnings below may make it differ from CI
  Image      ubuntu:26.04  linux/amd64
             matches the runner image ubuntu-26.04 20261111.196.1
  Commit     c484767

  Toolchains
    python   3.11.18    exact · asked for "3.11" · from actions/setup-python@6d4fd22
    uv       0.13.8     exact · from astral-sh/setup-uv@11f9893

  Steps
    1  checkout    Run actions/checkout@3d3c42e
                    pytest-dev/pytest @ c484767 (merge of 58b8dae into 50234b4)
    2  skip        Download Package
                    — downloads artifacts from another job
    3  toolchain   Set up Python 3.11
                    → install python 3.11.18
    4  composite   Run pytest-dev/pytest/.github/actions/setup-tox@c484767
                    — composite action; its steps follow
    5    toolchain   Run astral-sh/setup-uv@11f9893
                      → install uv 0.13.8
    6    run         $ if [ -n "$PYTHON_VERSION" ]; then  (+4 lines)
    7  run         Test with coverage  ← CIで失敗
                    $ tox run -e py311-coverage --installpkg `find dist/*.tar.gz`
                    shell: /usr/bin/bash --noprofile --norc -e -o pipefail {0}

  Issues
    ! [step 2] actions/download-artifact@9000827 downloads artifacts produced by another job or run; files it provides will be missing locally
    i [step 1] CI tested the merge of PR head 58b8dae into base 50234b4 (merge commit c484767), not the PR branch alone; the plan checks out that merge commit

計画の構築方法:

  • ログが実行されたことの真実の情報源です。 スクリプト、シェル、環境はGitHubが表示するステップヘッダーから取得されるため、${{ matrix.* }}などの式は既に展開されています。コンポジットアクションは内部ステップを表示します。
  • CIがテストした正確なコミット。 プルリクエストの場合、それはGitHubが作成したマージコミットであり、あなたのブランチヘッドではありません。これは、失敗が「ローカルで発生しない」一般的な理由です。
  • 正確なツールチェーンバージョン。 ワークフローの"3.11"は、ランナーのツールキャッシュパスから読み取られた3.11.18になります。ログにバージョンが表示されない場合、go.mod(toolchainを含む)、.nvmrc、.python-version、.tool-versions、package.jsonのpackageManagerなどのバージョンファイルを読み取ります。
  • 正しいベースイメージ。 container:ジョブはそのまま使用されます。それ以外の場合は、ジョブが実際に取得したランナーイメージと一致するUbuntuバージョンを選択します。
  • スキップするものとフラグを立てるもの。 キャッシュ、アップロード、カバレッジレポーターはスキップされます。ダウンロードされたアーティファクト、サービスコンテナ、シークレット、不明なアクション、セットアップステップなしで使用されたツール(ランナーにプリインストールされていたもの)は、問題として報告されます。

判定は、ready(既知の欠落なし)、partial(実行可能だが、一部が近似または欠落している)、またはblocked(失敗したステップがスクリプトではなくアクションであるため、まだ再生できない)です。

サポートされているセットアップアクション:actions/setup-go、setup-node、setup-python、setup-java、setup-dotnet、ruby/setup-ruby、dtolnay/rust-toolchain、actions-rust-lang/setup-rust-toolchain、pnpm/action-setup、pnpm/setup、astral-sh/setup-uv、oven-sh/setup-bun、denoland/setup-deno。

失敗の再現

failtrace reproは計画を構築し、Dockerで実行してから、結果をCIの失敗と比較します。

failtrace repro <run-url>
failtrace repro --keep <run-url>                     # 後で調査するためにコンテナを保持する
API_TOKEN=... failtrace repro --secret API_TOKEN <run-url>
failtrace repro --toolchain node=20.11.1 <run-url>   # ツールチェーンを補完または上書きする
failtrace repro --platform linux/arm64 <run-url>     # ネイティブで実行(Apple Silicon上)(高速、不正確)
failtrace repro --runs 10 <run-url>                  # 不安定か?
failtrace repro --shell <run-url>                    # 後でコンテナ内でデバッグする
failtrace repro --report repro.md <run-url>          # 問題やPR用のMarkdownレポート

Docker(Docker Desktop、colima、OrbStackなど)とgitが必要です。

失敗したstretchr/testify実行の実際の出力。Go oldstable下でgo vetが失敗しました。FailTraceはoldstableをCIが使用した正確なGo 1.26.9ビルドに解決し、CIがテストしたPRマージコミットをチェックアウトし、ステップを再生しました。

$ failtrace repro --platform linux/arm64 https://github.com/stretchr/testify/actions/runs/39247781971
Reproducing stretchr/testify · build (oldstable) · plan ready
▶ Image       failtrace-env:08414601e6c4aef4 (cached)
▶ Workspace   stretchr/testify @ 9272105
▶ [3/5]       Run ./.ci.gogenerate.sh
  ✓ exit code 0 (17.7s)
▶ [4/5]       Run ./.ci.gofmt.sh
  ✓ exit code 0 (7.4s)
▶ [5/5]       Run ./.ci.govet.sh  ← CIで失敗
    │ assert/assertion_compare_test.go:85:13: non-constant format string in call to (*testing.common).Errorf
    │ assert/assertion_compare_test.go:94:13: non-constant format string in call to (*testing.common).Errorf
  ✗ exit code 1 (10.7s)

✓ reproduced: the step fails locally the same way it failed in CI
  • the same error: assert/assertion_compare_test.go:<n>:<n>: non-constant format string in call to (*testing..common).Errorf

                 CI                           Local
  Exit code      1                            1
  Failure        lint / format check          lint / format check

  Steps      4 passed · 1 failed (39s total)
  Image      failtrace-env:08414601e6c4aef4 linux/arm64

  Differences from CI
    - the image is plain ubuntu:24.04 with common runner packages; GitHub's runner image has far more preinstalled
    - steps run as root; on GitHub's runners they run as the `runner` user with passwordless sudo
    - running linux/arm64, but CI ran linux/amd64

--platformなしの場合、ジョブはCIと同様にlinux/amd64として実行されます。Apple Silicon Mac上ではエミュレーションを意味します。同じ再現に約9分かかりましたが、40秒で完了し、判定は同じでした。

何が起こるか:

  1. 環境イメージ。 計画のベースイメージに、すべてのGitHub Ubuntuランナーが持つパッケージ(git、curl、ビルドツール、python3、jq、sudoなど)、およびツールチェーンが追加されます。Go、Node、Pythonは、setup-go、setup-node、setup-pythonがダウンロードするのと同じビルドで、CIが保持する/opt/hostedtoolcacheの下にインストールされます。uv、pnpm、Rustはリリースからインストールされます。イメージは内容のハッシュでタグ付けされるため、環境ごとに一度だけビルドされます。

  2. ワークスペース。 CIがテストした正確なコミットがローカルマシンにactions/checkoutと同じ方法でフェッチされ、同じフェッチ深度で、ランナー上のパス(/home/runner/work/<repo>/<repo>、またはコンテナジョブの場合は/__w/...)にマウントされます。GitHubがプルリクエストのマージコミットを置き換えた場合、マージはローカルで再作成されます。

  3. サービス。 サービスコンテナはジョブコンテナのネットワーク名前空間で起動するため、localhost:5432とpostgres:5432の両方が機能し、FailTraceはそれらのヘルスチェックを待ちます。

  4. ステップ。 runステップは、CIが使用したシェル、環境、作業ディレクトリで順次再生されます。$GITHUB_ENVと$GITHUB_PATHはステップ間で引き継がれます。失敗したステップの出力ストリームは保持されます。

  5. 判定。

    • reproduced: 同じテストが失敗したか、同じエラーまたは終了コードが発生しました。
    • different-failure
    • not-reproduced: ステップはローカルでパスしました。
    • diverged: より前のステップがローカルで失敗したため、失敗したステップは実行されませんでした。
    • flaky: --runsを使用すると、ステップは一部の実行では失敗しましたが、すべてではありませんでした。

    既知のCIとの違いのリストが各判定とともに提供されます。

不安定な失敗: --runs N

セットアップステップは一度実行され、その後失敗したステップが同じコンテナ内でN回実行されるため、繰り返しは安価です。時々失敗する場合、判定はflaky(「ステップは10回の実行のうち3回失敗しました」)になります。Goのテストキャッシュはこれらの実行ではバイパスされます(GOFLAGS=-count=1)。そうでなければ、go testはキャッシュされたパスを再生して不安定さを隠してしまうでしょう。

コンテナ内でのデバッグ: --shell

実行が終了すると、--shellは失敗したステップが実行されたシェルを開きます。同じディレクトリ、環境、ツールチェーン、サービスです。ステップを再実行するコマンドが表示されます。

▶ Shell       inside the container at step 5 (Run ./.ci.govet.sh); type exit to finish
              re-run the step with: bash -e /home/runner/work/_temp/failtrace/step-5.sh

より前のステップが分岐した場合、代わりにそのステップでシェルが開きます。コンテナは、--keepを渡さない限り、終了時に削除されます。

結果の共有: --report FILE

--report repro.mdは、問題やプルリクエストに貼り付けるためのMarkdownレポートを書き出します。判定、CI対ローカルのテーブル、環境、違い、各ステップの結果、および両側の失敗したステップの出力が含まれます。--report -は、ターミナルサマリーの代わりにそれを表示します。上記のstretchr/testify実行から--runs 3を使用して生成されたdocs/example-report.mdを参照してください。

安全性。 reproは、ローカルマシン上のコンテナ内で、プルリクエストからのコードを含むリポジトリのコードを実行します。コンテナはワークスペースのみを参照し、ホームディレクトリやDockerソケットにアクセスできず、--secret NAMEで渡さない限りシークレットを受け取りません。値は環境から読み取られるため、シェル履歴やプロセスリストに表示されることはありません。実行するコードが安全だと確信できる実行のみを再現してください。

制限事項。 これらはサイレントに無視されるのではなく、報告されます。

  • スクリプトではなくアクションである失敗したステップは再生できません(判定blocked)。
  • WindowsおよびmacOSジョブはLinuxでは近似的にしか実行されません。
  • ランナーはrootとして実行されますが、CIではrunnerユーザーが使用されます。
  • ランナーイメージの多くのプリインストールツールはすべて存在しません。
  • linux/amd64ジョブはARMマシン上でエミュレートされます。
  • 他のジョブからのアーティファクトは利用できません。

ロードマップ

  • inspect: URLから失敗した実行を診断する
  • plan: 失敗したジョブをローカル再現計画に変換する:ベースイメージ、正確なコミット、ツールチェーンバージョン、環境、再生するステップ
  • repro: Dockerで計画を実行し、結果をCIと比較する
  • レポート: --reportは、判定とCIからの違いを含むMarkdownレポートを書き出す
  • 不安定検出: --runs Nは失敗したステップを繰り返し、flakyを報告する
  • --shell: 失敗したステップのコンテナに入る
  • リリース: macOS、Linux、Windows用の事前ビルド済みバイナリ、およびチェックサム検証付きインストールスクリプト
  • Homebrewおよびgh拡張機能: brew installおよびgh failtrace <run-url>
  • 一般的なアクションの再生: golangci-lint-actionのようなアクションを、それらが実行するコマンドに変換し、それらでの失敗を再現できるようにする

開発

go test ./...                                     # 単体テスト(ネットワークやDockerは不要)
go test -race ./...
go vet ./...
go test -tags integration ./internal/repro/       # 実際のコンテナを実行します。Dockerが必要です
goreleaser release --snapshot --clean             # リリースアーカイブをローカルでビルドし、何も公開しません

CIはこれらすべてを各プルリクエストで実行します。リリースを公開するには、バージョンタグをプッシュします(git tag v0.1.0 && git push origin v0.1.0)。release.ymlがバイナリをビルドしてアップロードします。

プロジェクトレイアウト:

cmd/failtrace/      CLIエントリポイント
internal/cli/       コマンドとフラグ
internal/runurl/    実行URLの解析と検証
internal/github/    最小限のGitHub RESTクライアントとトークン検索
internal/joblog/    ジョブログの解析、失敗の抽出と分類
internal/workflow/  ワークフローYAMLの解析、ジョブ/ステップ/マトリックスのマッチング
internal/inspect/   すべてをまとめてレポートにまとめる
internal/plan/      再現計画(イメージ、コミット、ツールチェーン、環境、ステップ)を構築する
internal/toolchain/ セットアップ-*アクションが使用するツールチェーンをビルドに解決する
internal/docker/    docker CLI経由でコンテナを実行する
internal/repro/     計画を実行し、結果をCIと比較する
internal/report/    ターミナルレンダリング

貢献

問題とプルリクエストを歓迎します。現時点で最も役立つ貢献は次のとおりです。

  • FailTraceが間違った失敗した実行。 ランURLと期待した結果を添えてイシューを開いてください。
  • 新しい失敗シグネチャ: まだ検出されていないテストランナー、パッケージマネージャー、コンパイラ。これらはinternal/joblog/analyze.goにあり、テストケースが必要です。
  • より多くの既知のアクション: セットアップアクション(internal/plan/toolchains.go)およびローカルで安全にスキップできるアクション(internal/plan/actions.go)。それぞれは単一のテーブルエントリです。

ライセンス

MIT