ワークフローの成果物について
成果物を使えば、ジョブの完了後にデータを永続化でき、そのデータを同じワークフロー中の他のジョブと共有できます。 成果物とは、ワークフロー実行中に生成されるファイル、またはファイルのコレクションです。 たとえば、ワークフローの実行が終了した後、成果物を使ってビルドとテストの出力を保存しておけます。 実行内で呼び出されるすべてのアクションとワークフローは、その実行の成果物への書き込みアクセス権を持っています。
既定では、GitHub にはビルド ログと成果物が 90 日間保存され、この保持期間はカスタマイズできます。 詳しくは、「使用制限、支払い、管理」を参照してください。 pull request の保持期間は、ユーザーが新しいコミットを pull request にプッシュするたびに再開されます。
以下は、アップロードできる一般的な成果物の一部です。
- ログファイルとコアダンプ
- テスト結果、エラー、スクリーンショット
- バイナリあるいは圧縮されたファイル
- ストレステストのパフォーマンス出力およびコードカバレッジの結果
成果物の保存には、GitHub上のストレージ領域が使われます。 GitHub Actions の使用は、パブリック リポジトリの標準の GitHub ホステッド ランナーとセルフホステッド ランナーの場合は無料です。 プライベート リポジトリの場合、アカウントのプランに応じて、GitHub ホステッド ランナーでの使用を対象として、一定量の無料の使用時間 (分) とストレージが各 GitHub アカウントに付与されます。 含まれる量を超える使用は、使用制限によって制御されます。詳しくは、「Managing billing for GitHub Actions」をご覧ください。
成果物はワークフローの実行中にアップロードされ、成果物の名前とサイズはUIで見ることができます。 GitHubのUIを使って成果物がダウンロードされる場合、成果物の一部として個別にアップロードされたすべてのファイルはzipして1つのファイルにまとめられます。 これはすなわち、支払いはこのzipファイルのサイズではなく、アップロードされた成果物のサイズを元に計算されるということです。
GitHubには、ビルドの成果物のアップロードとダウンロードに使用できるアクションが2つあります。 詳細については、upload-artifact と download-artifact のアクションを参照してください。
ジョブ間でデータを共有するには:
- ファイルのアップロード: アップロードされたファイルに名前を付けて、ジョブが終了する前にデータをアップロードします。
- ファイルのダウンロード: アップロードされたアーティファクトをダウンロードできるのは、同じワークフローの実行中だけです。 ファイルをダウンロードする際には、名前で参照できます。
ジョブのステップは、ランナーマシン上で同じ環境を共有しますが、それぞれが個別のプロセス内で実行されます。 ジョブのステップ間のデータを受け渡すには、入力と出力を使用できます。 入力と出力について詳しくは、「GitHub Actions のメタデータ構文」をご覧ください。
成果物の比較と依存関係のキャッシング
成果物とキャッシングは、GitHubにファイルを保存できるようにするので似ていますが、それぞれの機能のユースケースは異なっており、入れ替えて使うことはできません。
- パッケージ管理システムからのビルドの依存関係など、ジョブまたはワークフローの実行の間で頻繁に変更されないファイルを再利用する場合は、キャッシュを使用します。
- ビルドされたバイナリやビルド ログなど、ワークフローの実行が終了した後に表示するためにジョブによって生成されたファイルを保存する場合は、成果物を使用します。
依存関係のキャッシュについて詳しくは、「依存関係をキャッシュしてワークフローのスピードを上げる」をご覧ください。
ビルドおよびテストの成果物をアップロードする
継続的インテグレーション(CI)ワークフローを作成して、コードのビルドやテストを行えます。 GitHub Actions を使って CI を実行する方法について詳しくは、「About continuous integration with GitHub Actions」をご覧ください。
コードのビルドおよびテストからの出力によって、多くの場合、エラーのデバッグに使用できるファイルと、デプロイできる本番コードが生成されます。 リポジトリにプッシュされるコードをビルドしてテストし、成功または失敗のステータスをレポートするワークフローを構成することができます。 デプロイメントに使用するビルドおよびテスト出力をアップロードし、失敗したテストまたはクラッシュをデバッグしてテストスイートのカバレッジを確認できます。
成果物をアップロードするには、upload-artifact
アクションを使用できます。 成果物をアップロードする場合は、単一のファイルまたはディレクトリ、あるいは複数のファイルまたはディレクトリを指定できます。 また、特定のファイルやディレクトリを除外したり、ワイルドカードパターンを使用したりすることもできます。 成果物の名前を指定することをお勧めしますが、名前を指定しない場合は、artifact
が既定の名前として使用されます。 構文の詳細については、actions/upload-artifact アクションを参照してください。
例
たとえば、リポジトリあるいはWebアプリケーションにはCSSやJavaScriptに変換しなければならないSASSやTypeScriptが含まれているかもしれません。 ビルド構成で dist
ディレクトリにコンパイル後のファイルを出力すると仮定すると、テストがすべて正常に完了した場合、dist
ディレクトリにあるファイルが Web アプリケーション サーバーにデプロイされます。
|-- hello-world (repository)
| └── dist
| └── tests
| └── src
| └── sass/app.scss
| └── app.ts
| └── output
| └── test
|
この例で示しているのは、src
ディレクトリにコードをビルドして、tests
ディクトリでテストを実行する Node.js プロジェクトのワークフローを作成する方法です。 実行中の npm test
によって、code-coverage.html
という名前で、output/test/
ディレクトリに保存されるコード カバレッジ レポートが生成されると想定できます。
このワークフローでは、dist
ディレクトリに運用環境の成果物をアップロードしますが、Markdown ファイルはその対象外です。 また、code-coverage.html
レポートも別の成果物としてアップロードされます。
name: Node CI on: [push] jobs: build_and_test: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: npm install, build, and test run: | npm install npm run build --if-present npm test - name: Archive production artifacts uses: actions/upload-artifact@v4 with: name: dist-without-markdown path: | dist !dist/**/*.md - name: Archive code coverage results uses: actions/upload-artifact@v4 with: name: code-coverage-report path: output/test/code-coverage.html
name: Node CI
on: [push]
jobs:
build_and_test:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: npm install, build, and test
run: |
npm install
npm run build --if-present
npm test
- name: Archive production artifacts
uses: actions/upload-artifact@v4
with:
name: dist-without-markdown
path: |
dist
!dist/**/*.md
- name: Archive code coverage results
uses: actions/upload-artifact@v4
with:
name: code-coverage-report
path: output/test/code-coverage.html
ビルドのアーティファクト構成証明の生成
構成証明を使用することで、ビルドするソフトウェアに対して検証不可能な証明と整合性の保証を作成できます。 さらに、ソフトウェアを使用するユーザーは、ソフトウェアがビルドされた場所と方法の確認ができます。
ソフトウェアで成果物の構成証明を生成する場合は、ビルドの実績を確立し、次の情報など暗号署名付き要求を作成します。
- アーティファクトに関連付けられているワークフローへのリンク。
- リポジトリ、組織、環境、コミット SHA、およびアーティファクトのトリガー イベント。
- 証明の確立に使用する OIDC トークンからのその他の情報。 詳しくは、「OpenID Connect を使ったセキュリティ強化について」を参照してください。
関連するソフトウェア部品表 (SBOM) を含む構成証明を生成することもできます。 ビルドを、その中で使用されるオープンソースの依存関係の一覧に関連付けることで、透明性は提供され、コンシューマーがデータ保護標準に準拠できるようになります。
ビルドの実行後、ビルドによって生成されたアーティファクトの一覧の下にある構成証明にアクセスできます。
詳しくは、「アーティファクトの構成証明を使用して構築の実績を確立する」を参照してください。
カスタムの成果物の保持期間を設定する
ワークフローによって作成された個々の成果物のカスタム保存期間を定義できます。 ワークフローを使用して新しい成果物を作成する場合、upload-artifact
アクションで retention-days
を使用できます。 この例は、my-artifact
という名前の成果物に 5 日間のカスタム保存期間を設定する方法を示しています。
- name: 'Upload Artifact' uses: actions/upload-artifact@v4 with: name: my-artifact path: my_file.txt retention-days: 5
- name: 'Upload Artifact'
uses: actions/upload-artifact@v4
with:
name: my-artifact
path: my_file.txt
retention-days: 5
retention-days
の値は、リポジトリ、Organization、または Enterprise によって設定された保持制限を超えることはできません。
成果物のダウンロードあるいは削除
ワークフローの実行中に、download-artifact
アクションを使用すると、同じワークフロー実行で以前にアップロードされた成果物をダウンロードできます。
ワークフローの実行が完了したら、GitHub または REST API を使用して成果物をダウンロードまたは削除できます。 詳しくは、「ワークフローの成果物をダウンロードする」、「ワークフローの成果物を削除する」、「GitHub Actions アーティファクトの REST API エンドポイント」をご覧ください。
ワークフロー実行中の成果物のダウンロード
actions/download-artifact
アクションを使用して、ワークフロー実行中に以前にアップロードされた成果物をダウンロードできます。
注: ダウンロードできるのは、同じワークフロー実行中にアップロードされたワークフロー内の成果物のみです。
個々の成果物をダウンロードするには、成果物の名前を指定します。 名前を指定せずに成果物をアップロードした場合、既定の名前は artifact
です。
- name: Download a single artifact
uses: actions/download-artifact@v4
with:
name: my-artifact
また、名前を指定しないことで、ワークフロー実行のすべての成果物をダウンロードすることもできます。 これは、多数の成果物を扱っている場合に便利です。
- name: Download all workflow run artifacts
uses: actions/download-artifact@v4
ワークフロー実行のすべての成果物をダウンロードすると、各成果物のディレクトリがその名前を使用して作成されます。
構文の詳細については、actions/download-artifact アクションを参照してください。
ワークフロー内のジョブ間でのデータの受け渡し
upload-artifact
アクションと download-artifact
アクションを使用すると、ワークフローのジョブ間でデータを共有できます。 以下のワークフローの例では、同じワークフローのジョブ間でデータを受け渡す方法を説明しています。 詳細については、actions/upload-artifact と download-artifact のアクションを参照してください。
前のジョブの成果物に依存するジョブは、前のジョブが正常に完了するまで待つ必要があります。 このワークフローでは、needs
キーワードを使用して、job_1
、job_2
、job_3
を順次実行できます。 たとえば、job_2
では needs: job_1
構文を使用することにより job_1
が必要となっています。
ジョブ1は、以下のステップを実行します。
- 数式の計算を実行し、その結果を
math-homework.txt
というテキスト ファイルに保存します。 - アクションを
upload-artifact
使用して、成果物名homework_pre
を持つファイルをアップロードmath-homework.txt
します。
ジョブ2は、前のジョブの結果を利用して、次の処理を実行します。
- 前のジョブでアップロードされた
homework_pre
成果物をダウンロードします。 既定では、download-artifact
アクションで、ステップが実行されているワークスペース ディレクトリに成果物をダウンロードします。path
入力パラメータを使用すると、別のダウンロード ディレクトリを指定できます。 math-homework.txt
ファイル内の値を読み取り、数式の計算を実行して、結果をmath-homework.txt
に再度保存し、その内容を上書きします。math-homework.txt
ファイルをアップロードします。 成果物は不変v4
と見なされるため、成果物は別の入力homework_final
(名前として) 渡されます。% else %}このアップロードは、同じ名前を共有しているため、以前にアップロードされた成果物を上書きします。
ジョブ3は、前のジョブでアップロードされた結果を表示して、次の処理を実行します。
homework_final
成果物をジョブ 2 からダウンロードします。- 数式の結果をログに出力します。
このワークフロー例で実行される完全な数式は、(3 + 7) x 9 = 90
です。
name: Share data between jobs on: [push] jobs: job_1: name: Add 3 and 7 runs-on: ubuntu-latest steps: - shell: bash run: | expr 3 + 7 > math-homework.txt - name: Upload math result for job 1 uses: actions/upload-artifact@v4 with: name: homework_pre path: math-homework.txt job_2: name: Multiply by 9 needs: job_1 runs-on: windows-latest steps: - name: Download math result for job 1 uses: actions/download-artifact@v4 with: name: homework_pre - shell: bash run: | value=`cat math-homework.txt` expr $value \* 9 > math-homework.txt - name: Upload math result for job 2 uses: actions/upload-artifact@v4 with: name: homework_final path: math-homework.txt job_3: name: Display results needs: job_2 runs-on: macOS-latest steps: - name: Download math result for job 2 uses: actions/download-artifact@v4 with: name: homework_final - name: Print the final result shell: bash run: | value=`cat math-homework.txt` echo The result is $value
name: Share data between jobs
on: [push]
jobs:
job_1:
name: Add 3 and 7
runs-on: ubuntu-latest
steps:
- shell: bash
run: |
expr 3 + 7 > math-homework.txt
- name: Upload math result for job 1
uses: actions/upload-artifact@v4
with:
name: homework_pre
path: math-homework.txt
job_2:
name: Multiply by 9
needs: job_1
runs-on: windows-latest
steps:
- name: Download math result for job 1
uses: actions/download-artifact@v4
with:
name: homework_pre
- shell: bash
run: |
value=`cat math-homework.txt`
expr $value \* 9 > math-homework.txt
- name: Upload math result for job 2
uses: actions/upload-artifact@v4
with:
name: homework_final
path: math-homework.txt
job_3:
name: Display results
needs: job_2
runs-on: macOS-latest
steps:
- name: Download math result for job 2
uses: actions/download-artifact@v4
with:
name: homework_final
- name: Print the final result
shell: bash
run: |
value=`cat math-homework.txt`
echo The result is $value
ワークフローの実行により、生成された成果物がアーカイブされます。 アーカイブされた成果物のダウンロードについて詳しくは、「ワークフローの成果物をダウンロードする」をご覧ください。