GitHub Actionsのworkflow artifactが期限切れで取得できないときの確認

まずartifactとworkflow runを特定する

workflow artifactが一覧から見えない、downloadで失敗する、またはexpiredと表示される場合、まず対象repository、workflow run、artifact nameを特定します。Artifact名だけで探すと、同名artifactを別runから選ぶことがあります。run ID、workflow、branch、commit SHA、artifact作成日時を照合し、欲しい成果物が本当にそのrunで生成されたものか確認してください。

次にartifactのexpiredとexpires_atを確認します。GitHub REST APIのartifact objectには、artifact ID、expired、created_at、expires_atなどの情報があります。UIで期限が分からないときは、必要なread権限を持つ方法でrunのartifact一覧を取得し、状態を確かめます。取得できない原因をすぐに「期限切れ」と決めず、repository権限、run削除、artifact名、organizationやrepository retention設定も分けて確認します。

GitHub Docsはworkflow artifactを自動的に期限切れにし、既定の保持期間は90日と説明しています。ただしrepositoryの種類やrepository / organization / enterprise設定、upload-artifact actionに個別指定したretentionにより短くまたは異なる期間になる場合があります。したがって、90日を個別artifactの保証期間として扱わず、実際のexpires_atを優先してください。

一覧にないときの診断

1. runとartifact名を照合

Actionsから対象workflowのrun summaryを開き、Artifacts欄に該当名があるか確認します。run IDとartifact名が一致しているのに見えない場合は、artifactが削除されたか、保持期限を過ぎた可能性があります。別runに同じ名前がある場合は、branchやcommit、作成日時も比べます。

workflowの完了状態とartifactの存在も分けます。runが成功していても、artifact upload stepが条件でSkippedだった、対象pathが空だった、upload時に別名を設定したといった可能性があります。workflow logでupload actionの開始・完了、artifact name、対象ファイルを確認します。artifactが見当たらないときにrunを再実行すれば元のartifactが戻るとは限りません。新しいrunは新しいartifactを生成する操作です。

2. expiredとexpires_atを読む

REST APIでartifact情報を読むと、expiredがboolean、expires_atが予定削除日時として返ります。expired=falseで期限も未来なら、repository read access、正しいworkflow run、artifact ID、ダウンロード方法を確認します。GitHub Docsによれば、workflow artifactのdownloadにはrepository read accessが必要です。

expired=trueまたはexpires_atが過去なら、まず期限切れとして扱います。APIのDownload an artifact endpointは、downloadで302 redirectに加えて410 Goneを返すstatusを定義しています。410が返った場合、URLの再試行を繰り返すより、artifactのexpired状態、run削除、対象IDを確認し、別の保存コピーや再生成可能性へ進みます。

3. workflow runが削除されていないか確認

GitHub Docsはworkflow runを削除すると、そのrunに関連するartifactもstorageから削除されると説明しています。artifact retentionの日付より前でも、run自体が削除されたならartifactが残る前提にしないでください。Actionsのrun一覧、repository activity、権限のある監査情報を確認し、run deletionの有無を分けます。

4. 権限とrepositoryを確認

artifactをdownloadするにはrepositoryへのread accessが必要です。private repositoryをREST APIやCLIから扱う場合は、認証方式に応じたActions read permissionやrepo accessが必要となることがあります。正しいrepositoryに入っているのに一覧やdownloadが失敗する場合は、使用アカウントのpermission、token scope、workflow runへのaccessを確認します。

権限不足と期限切れは同じではありません。認証エラー、403、404、410など、実際のHTTP statusとAPI responseを記録します。権限を広げる場合は必要最小のread scopeに限定し、Artifactを取得するだけのためにwrite/delete permissionを付与しないでください。

retentionの実効値を確認する

保持期限は複数階層から影響を受けます。RepositoryのActions設定、organizationまたはenterpriseのretention policy、artifactをuploadしたworkflow actionの個別retention指定を確認します。policy上限がworkflowの個別値より短ければ、より長い値をartifactに指定しただけで延長できるとは限りません。該当repositoryとorgの実設定を管理画面で照合してください。

個別artifactの期限を決めるworkflowでは、actions/upload-artifactに指定したretention-days等の設定と、repository/organization側の許容値を両方確認します。workflowファイルだけを見て実際の保存期限を断定せず、APIのexpires_atまたはartifact画面で適用結果を確かめます。

保持期間を長くするのは、後からダウンロードできる保証を無期限に作ることではありません。organization policy、storage上限、repository typeやGitHubの現行仕様、run削除などの条件を踏まえ、どの成果物をどこまで保持する必要があるか決めます。

期限が残っているartifactをdownloadする

artifactが存在し、expired=falseで、利用者にrepository read accessがあるなら、対象run summaryのArtifacts欄から取得できます。GitHub CLIではrun IDとartifact nameを指定し、特定runのartifactを選べます。複数artifactを一括取得するときは、出力先がartifact名ごとに分かれる挙動にも注意します。

REST APIでarchive downloadを使う方法もあります。APIのdownload endpointはarchiveへのredirect URLを返し、そのURLには有効時間があります。redirect先を時間が経ってから再使用するのではなく、必要なときに新しく取得します。認証情報やsigned URLを公開issueや共有チャットへ貼らないでください。

取得後はfile list、size、SHA-256やrelease manifestなどを、期待するbuild/run情報と照合します。artifactをダウンロードできたことは、中身が正しいことやreleaseに使えることの証明ではありません。artifactの目的に合わせて内部のファイル構成とbuild IDを確認します。

期限切れのartifactを取り戻せるか

期限切れや削除済みartifactを、Actions UIやartifact APIから復元できるとは前提にしないでください。GitHub Docsはartifactを自動expireする仕組みと、削除したartifactは復元できないことを説明しています。まずrepository内の別workflow run、別名artifact、release asset、package、外部archive、CI保管領域などに同じ成果物が保存されていないか探します。

該当するcopyがなければ、同じcommit、同じworkflow definition、同じinputsで再生成できるかを評価します。依存パッケージが変わった、外部データが変化した、署名やtimestampが必要など、完全に同一の再生成が保証できない条件もあります。再buildしたartifactを元のrunの成果物と同一視せず、新しいrun ID・build ID・生成時点を記録します。

再生成できない重要データなら、GitHub Actions artifactは一時的な共有・保管手段として位置付け、正式なarchiveやrelease storageなど要件に合う場所へ別途保存する必要があります。どの保存先を選ぶかはデータ分類、アクセス権、保持期間、費用、復旧要件によります。新たな外部保存先への変更は、セキュリティ・費用・運用への影響を確認して実施してください。

判定表

表は横にスクロールできます

観測	次に確かめること	結論の方向
expired=false、expires_atが未来、APIで見つかる	repository read access、artifact ID、download URL	権限・選択・download経路の問題を調査
expired=true、expires_atが過去	別run、release asset、外部archive	現行artifact APIからの取得は期待せず、別copyまたは再生成を評価
REST APIが410 Goneを返す	artifact IDとexpired状態、run削除	同じURLの再試行を止め、別保存/再生成へ進む
artifactがrun summaryにない	upload stepのlog、name、条件、run削除	upload未生成・別名・削除・期限切れを切り分け
artifactの期限前なのに権限エラー	account access、Actions read権限、private repo token	最小read permissionの問題として解決
expires_atが想定より早い	repo/org/enterprise policyと個別retention	実効設定の最も短い制限と適用値を確認

この判定表では、表示やstatusを根拠に次の調査先を決めます。organization設定やartifactの実データを見ずに、特定の設定が原因だと決めつけないでください。

次回の失効を防ぐ設計

まず、artifactの用途を分類します。pull requestのテスト結果のように短期間の確認用なら、その必要期間に合うretentionを設定します。release候補、規制上保持する成果物、再生成が難しいデータなら、Actions artifactだけに保存を依存せず、正式なrelease/archive先にも残します。

Artifact名やworkflow summaryにcommit SHA、version、対象environment、生成日時を含めると、同名artifactの取り違えを避けやすくなります。artifactとrunの対応が分かるmanifestを残し、releaseに使う場合はhash、file count、size、build metadataを保存します。これは期限を延ばす操作とは別の、照合性を高める運用です。

Workflow側では期限を越える前に必要な成果物を取得・保管する仕組みを検討します。保存先へコピーする場合は、公開範囲・アクセス制御・暗号化・保持期間・削除責任を確認してください。自動化は誤ったartifactや秘密情報を長期保存する危険もあるため、どのpathとfile typeを保管するか明示します。

さらに、実際のexpires_atを定期的に確認し、期限前にrelease責任者へ通知する方法を設けます。期限だけを監視するのではなく、artifactが必要な期間を超えて適切なarchiveへコピーされたか、copyのhashやrestore手順が検証されたかまで確認します。

実行チェックリスト

1. Repository、workflow、run ID、branch、commit SHA、artifact nameを照合した。

2. artifactのexpiredとexpires_atをAPIまたはUIで確認した。

3. upload stepが実行され、同じartifactがrunに生成されたかlogで確認した。

4. run削除、repository read access、Actions permission、private repo tokenを切り分けた。

5. Repository / organization / enterprise retentionとworkflow個別設定を確認した。

6. Artifactが取得できた場合はsize、file list、hash、build metadataを確認した。

7. 失効済みなら別copy、release asset、外部archive、再生成可能性を評価した。

8. 今後の重要成果物について、必要retentionと正式archive先、hash検証、復旧担当を決めた。

公式情報と確認範囲

次のGitHub公式資料を2026-10-15に確認しました。Downloadsページは期限前のdownloadとread accessを説明し、Remove artifactsページは保持期間の設定場所、個別retention、run削除に伴うartifact削除、削除後の復元不可を説明します。REST APIはartifactのexpired / expires_atとdownload endpointのstatusを示します。個別repositoryの実設定やartifact状態は未確認です。

・Downloading workflow artifacts：https://docs.github.com/en/actions/how-tos/manage-workflow-runs/download-workflow-artifacts（新しいタブで開く）

・Removing workflow artifacts：https://docs.github.com/en/actions/how-tos/manage-workflow-runs/remove-workflow-artifacts（新しいタブで開く）

・REST API endpoints for GitHub Actions artifacts：https://docs.github.com/en/rest/actions/artifacts（新しいタブで開く）