今回は、GitHubActionsで利用するupload-artifactとdownload-artifactについてです。
どちらのアクションも便利で使い勝手もいいですが、少し注意が必要なこともあるので、備忘も兼ね記載しております。
■はじめに
Github公式のupload-artifactとdownload-artifactは以下です。
GitHub - actions/upload-artifact
GitHub - actions/download-artifact
■artiafct とは
まず、「artifactとは何ぞや?」ってところを説明致します。
カタカナ読みで「アーティファクト」です。直訳すると、"人工物"です。
いやー・・・「おー、なるほど。きっと、あーやって使うんだな」ってならないです。
artifactは、Github上では "生成物" や"成果物"と解釈したほうがまだしっくりきます。
・ジョブ内で作成したファイル
・ジョブ内で作成したテストデータ
・ジョブ内で作成した何かしらのビルド結果
などが、アーティファクトと言えます。
「ジョブ内で生成したもの」=「artifact」です。英語だと(私の場合は)イメージがわかないけど、日本語だと多少はしっくりきます。
※少し語弊がある解釈になりますが、最初はこの認識で困ることは無いかと。
※本記事の最後で少し訂正してます。
では、本題の「upload-artifact」「download-artifact」についてです。
■upload-artiafct について
「upload-artifact」というぐらいなので、artifactをアップロードすることができます。
アップロード先はGithubのストレージにアップロードされます。
Githubのストレージとは、以下のことです。
Git Large File Storage の使用状況の表示 - GitHub Docs
このストレージ容量(上図の「Storage for Actions and Packages」)を消費するのはGithubホストランナー(プライベートリポジトリ)を利用しているときのみとのことです。※違っていたら申し訳ないです。
セルフホストランナーを利用した場合、アップロードされたファイルはセルフホストランナー内に保存されるため料金はかかりません。
「upload-artifact」を利用すると、下図の通り、GitHubActionsのワークフローの処理結果画面にてアップロードしたアーティファクトがダウンロードできるようになります。
※あえてこのように記載した理由ですが、ブラウザを利用したダウンロードは、後述する「download-artifact」とは無関係のためです。「download-artifact」を利用しなくてもブラウザ上からダウンロードすることはできます。
尚、上図赤枠内の項目(testdir1-my-artifact , testdir2-my-artifact)をクリックするとブラウザ経由でダウンロードすることができます。
このように、ホストランナー上のデータをローカルに保存することができるため、いろんな使い方ができます。
1.GithubActionsのワークフロー内の一つのジョブ(Job-A)で出力した何かしらのデータ(=生成物/アーティファクト)を別のジョブ(Job-B)で利用/参照する。
2.ホストランナー上のログをアップロードしてローカルPC上にダウンロードする。
などです。(汎用性が高いのでいろんな使い方が想定できます。)
■upload-artiafct の構文について
書き方は冒頭の公式サイトにも記載されている為、簡単に紹介する程度にいたします。
・「path」で指定するのはアップロード対象のディレクトリやファイルです。
・「name」は、「download-artifact」を使う際、アップロードされたアーティファクトを特定するために使います。
■download-artiafct について
「download-artifact」というぐらいなので、artifactをダウンロードすることができます。
基本的に、「upload-artifact」とセットで使います。
※「upload-artifact」は「download-artifact」が必須ではないけど、「download-artifact」は「upload-artifact」が必須です。(何言っているかわかりづらいかもしれないので、後述でもう少し詳しく記載予定です。)
詳細な構文は冒頭の公式サイトを参照いただくとして、簡単な説明にはなりますが、「download-artifact」では「upload-artifact」で定義したname を利用して、アップロードされたアーティファクトを利用することができます。
「upload-artifact」が↓のようになっている場合は、
「download-artifact」は↓のように書きます。
※この場合は、"/var/tmpにtestdir1-upload/hello1.txt を格納する"という意味になります。
注意が必要なところは、
「path」 の記載内容は「name」で指定したアーティファクトの保存先ディレクトリです。
間違っても、アーティファクトが格納されているパスやアーティファクトの名前を記載してはいけません。
どのアーティファクトをダウンロードするかの指定は「name」で指定しています。(紛らわしい・・・)
■補足1:参照範囲について
「download-artifact」で「upload-artifact」のアーティファクトを利用したい場合、同一ワークフロー内での実行でのみ可能です。ジョブは異なっていても大丈夫です。
別々のワークフローの場合には、「download-artifact」で「upload-artifact」によるアーティファクトの受け渡しはできません。
■補足2:冒頭の一節を少し補足
冒頭で、
「ジョブ内で生成したもの」=「artifact」です。英語だと(私の場合は)イメージがわかないけど、日本語だと多少はしっくりきます。
と記載していますが、実は「ジョブ内で生成したもの」じゃなくても「upload-artifact」「download-artifact」でデータの受け渡しが可能です。
具体的には、ホストランナーの/var/log/messagesなども受け渡し可能です。(やってどうする?というところはここでは気にしません)
以上です。