-
.gitlab-ci.yml
でアーティファクトを定義する-
artifacts:reports
artifacts:reports:junit
artifacts:reports:dotenv
artifacts:reports:cobertura
artifacts:reports:terraform
artifacts:reports:codequality
artifacts:reports:sast
artifacts:reports:secret_detection
artifacts:reports:dependency_scanning
artifacts:reports:container_scanning
artifacts:reports:dast
artifacts:reports:license_management
artifacts:reports:license_scanning
artifacts:reports:performance
artifacts:reports:load_performance
artifacts:reports:metrics
artifacts:reports:requirements
-
- アーティファクトブラウザ
- アーティファクトをダウンロードする
- 最新のアーティファクトをダウンロードする
- アーティファクトの削除
- GitLab CIでプライベートプロジェクトのアーティファクトを取得する
ジョブアーティファクト
- GitLab 8.2とGitLab Runner 0.7.0で導入されました。
- GitLab 8.4およびGitLab Runner 1.0からアーティファクトのアーカイブ形式が
ZIP
に変更され、その内容を閲覧できるようになりファイルを個別にダウンロードする機能が追加されました。- GitLab 8.17ではビルドの名称がジョブに変更されました。
- アーティファクトブラウザはGitLab Runnerバージョン1.0以降を使用してGitLabに送信された新しいアーティファクトに対してのみ利用できるようになります。すでにGitLabにアップロードされている古いアーティファクトを閲覧することはできません。
ジョブアーティファクトとはジョブが終了した後に作成されるファイルやディレクトリの一覧のことです。 この機能はすべてのGitLabにてデフォルトで有効になっています。
GitLab Runnerで作成されたジョブアーティファクトはGitLabにアップロードされGitLab UIまたはGitLab APIを使用して、単一のアーカイブとしてダウンロードができます。
概要についてはGitLab CI Pipeline, Artifacts, and Environmentsのビデオをご覧ください。 またGitLab CI pipeline tutorial for beginnersもご覧ください。
.gitlab-ci.yml
でアーティファクトを定義する
次のように、.gitlab-ci.yml
でアーティファクトを簡単に定義できます。
pdf:
script: xelatex mycv.tex
artifacts:
paths:
- mycv.pdf
expire_in: 1 week
pdf
というジョブはxelatex
コマンドを呼び出してlatexのソースファイルmycv.tex
からPDFファイルを作成します。次にpaths
とartifacts
キーワードでアーティファクトのパスを定義します。指定するファイルとディレクトリのパスは、リポジトリのルートからの相対パスで記述してください。
デフォルトではジョブが成功したときにアップロードされますがartifacts:when
パラメータを使用する場合はジョブが失敗した時にアップロードするように設定することも常にアップロードするように設定出来ます。アップロードされたアーティファクトはexpire_in
で定義されているようにGitLabに1週間保存されます。web interfaceを使用して期限切れにならないようにできます。有効期限が定義されていない場合はデフォルトでinstance wide settingの値となります。
アーティファクトに関するより詳しい例は.gitlab-ci.yml
のartifactsリファレンスを参照してください。
artifacts:reports
- GitLab 11.2で導入されました。
- GitLab Runner 11.2以上が必要です。
artifacts:reports
キーワードはジョブからテストレポート、コード品質レポート、セキュリティレポートを収集するために使用します。
またこれらのレポートをGitLabのUI(マージリクエスト、パイプラインビュー、セキュリティダッシュボード) で公開します。
artifacts:expire_in
を使用して、そのアーティファクトの有効期限を設定できます。artifacts:paths
キーワードを含めてください。
artifacts:reports:junit
- GitLab 11.2で導入されました。
- GitLab Runner 11.2以上が必要です。
junit
レポートはJUnit XMLファイルをアーティファクトとして収集します。JUnitはもともとJavaで開発されたものですがJavaScript、Pyhon、Rubyなど他の言語への移植版が多数存在します。
詳細はJUnit test reportsを参照してください。 以下はRubyのRSpecテストツールからJUnitのXMLファイルを収集する例です。
rspec:
stage: test
script:
- bundle install
- rspec --format RspecJunitFormatter --out rspec.xml
artifacts:
reports:
junit: rspec.xml
収集されたJUnitレポートはアーティファクトとしてGitLabにアップロードされマージリクエストに自動的に表示されます。
junit: rspec-*.xml
)、ファイル名の配列(junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml]
)、またはそれらの組み合わせ(junit: [rspec.xml, test-results/TEST-*.xml]
)を使用してください。
artifacts:reports:dotenv
- GitLab 12.9で導入されました。
- GitLab Runner 11.5 以降が必要です。
dotenv
レポートを使用すると、環境変数をアーティファクトとして収集できます。
収集された変数はジョブ実行時の変数として登録され、ジョブ終了後に動的環境のURLを設定するのに役立ちます。
元々のdotenvのルールとは、次の相違があります。
- 変数キーに含めることができるのは、文字、数字、アンダースコア(
_
)のみです。 -
.env
ファイルの最大サイズは5KBです。 - 変数の数は最大で10です。
-
.env
ファイル内の変数の置換はサポートされていません。 -
.env
ファイルには空行やコメント(#
で始まる)を含めることはできません。 -
env
ファイル内のキーにはシングルクォーテーションやダブルクォーテーションを使用する場合を含め、スペースや改行文字(\n
)を使用できません。 - パース中のクウォートのエスケープ(
key = 'value'
->{key: "value"}
)はサポートされていません。
artifacts:reports:cobertura
- GitLab 12.9で導入されました。
- GitLab Runner 11.5以上が必要です。
cobertura
レポートはCobertura coverage XMLファイルを収集します。
収集されたCoberturaのカバレッジレポートはアーティファクトとしてGitLabにアップロードされ、マージリクエストに自動的に表示されます。
Coberturaは元々Java用に開発されたものですがJavaScript、Python、Rubyなど他の言語への移植版が多数存在します。
artifacts:reports:terraform
- GitLab 13.0から導入されました。
- GitLab Runner 11.5以上が必要です。
terraform
レポートを使用するとTerraformのtfplan.json
ファイルを収集できます。認証情報を除去するには、jqで処理する必要があります。
収集されたTerraformプランのレポートはアーティファクトとしてGitLabにアップロードされ、マージリクエストに自動的に表示されます。詳細についてはマージリクエストにterraformプラン
情報を出力するを参照してください。
artifacts:reports:codequality
- GitLab 11.5 で導入されました。
- GitLab Runner 11.5 以上が必要です。
codequality
レポートはコード品質の問題をアーティファクトとして収集します。
収集されたcodequalityレポートはアーティファクトとしてGitLabにアップロードされ、マージリクエストに表示されます。
artifacts:reports:sast
- GitLab 11.5 で導入されました。
- GitLab Runner 11.5 以上が必要です。
sast
レポートはSAST(静的アプリケーションセキュリティテスト)脆弱性をアーティファクトとして収集します。
収集されたSASTレポートはアーティファクトとしてGitLabにアップロードされ、マージリクエストやパイプラインに表示されます。また、セキュリティダッシュボードのデータとしても利用されます。
artifacts:reports:secret_detection
- GitLab 13.1 で導入されました。
- GitLab Runner 11.5 以上が必要です。
secret-detection
レポートは検出されたシークレットをアーティファクトとして収集します。
検出されたシークレットのレポートはアーティファクトとしてGitLabにアップロードされ、マージリクエストやパイプラインに表示されます。また、セキュリティダッシュボードのデータとしても利用されています。
artifacts:reports:dependency_scanning
- GitLab 11.5 で導入されました。
- GitLab Runner 11.5 以上が必要です。
dependency_scanning
レポートは依存関係の脆弱性をアーティファクトとして収集します。
依存関係の脆弱性レポートはアーティファクトとしてGitLabにアップロードされ、マージリクエストやパイプラインに表示されます。またセキュリティダッシュボードのデータとしても利用されます。
artifacts:reports:container_scanning
- GitLab 11.5 で導入されました。
- GitLab Runner 11.5 以上が必要です。
container_scanning
レポートはコンテナの脆弱性をアーティファクトとして収集しています。
コンテナの脆弱性レポートはアーティファクトとしてGitLabにアップロードされ、マージリクエストやパイプラインに表示されます。またセキュリティダッシュボードのデータとしても利用されます。
artifacts:reports:dast
- GitLab 11.5 で導入されました。
- GitLab Runner 11.5 以上が必要です。
dast
のートはDAST(動的アプリケーションセキュリティテスト)の脆弱性をアーティファクトとして収集します。
DASTの脆弱性レポートはアーティファクトとしてGitLabにアップロードされ、マージリクエストやパイプラインに表示されます。また、セキュリティダッシュボードのデータとしても利用されます。
artifacts:reports:license_management
- GitLab 11.5 で導入されました。
- GitLab Runner 11.5 以上が必要です。
license_management
レポートはライセンスをアーティファクトとして収集します。
ライセンスコンプライアンスレポートはアーティファクトとしてGitLabにアップロードされ、マージリクエストやパイプラインに表示されます。またセキュリティダッシュボードのデータとしても利用されます。
artifacts:reports:license_scanning
- GitLab 12.8 で導入されました。
- GitLab Runner 11.5 以上が必要です。
license_scanning
レポートはライセンスをアーティファクトして収集します。
ライセンスコンプライアンスレポートはアーティファクトとしてGitLabにアップロードされ、マージリクエストやパイプラインに自動的に表示され、セキュリティダッシュボードのデータとしても利用されます。
artifacts:reports:performance
- GitLab 11.5 で導入されました。
- GitLab Runner 11.5 以上が必要です。
performance
レポートはブラウザパフォーマンステストメトリクスをアーティファクトとして収集します。
ブラウザパフォーマンスレポートはアーティファクトとしてGitLabにアップロードされ、マージリクエストに自動的に表示されます。
artifacts:reports:load_performance
- GitLab Premium 13.2の GitLab 13.2 で導入されました。
- GitLab Runner 11.5 以上が必要です。
load_performance
レポートは負荷テストメトリクスをアーティファクトとして収集します。
レポートはアーティファクトとしてGitLabにアップロードされ自動的にマージリクエストに表示されます。
artifacts:reports:metrics
GitLab 11.10 で導入されました。
metrics
レポートはメトリクスをアーティファクトとして収集します。
メトリクスレポートはアーティファクトとしてGitLabにアップロードされ、マージリクエストに自動的に表示されます。
artifacts:reports:requirements
- GitLab 13.1で導入されました。
- GitLab Runner 11.5 以上が必要です。
requirements
レポートはrequirements.json
ファイルをアーティファクトとして収集します。
メトリクスレポートはアーティファクトとしてGitLabにアップロードされ既存の requirements はSatisfiedとマークされます。
アーティファクトブラウザ
- GitLab 9.2からはPDFや画像、動画などのフォーマットをダウンロードすることなくジョブアーティファクトブラウザで直接プレビューできるようになりました。
- GitLab 10.1で導入されたGitLab Pagesが有効な場合、パブリックプロジェクトのHTMLファイルをダウンロードすることなく新しいタブで直接プレビューすることができます。 テキスト形式の場合も同様です(現在サポートされている拡張子
.txt
、.json
、.log
)も同様)。- GitLab 12.4で導入されたGitLab Pagesアクセス制御が有効になっている場合、プライベートプロジェクトのアーティファクトをプレビューできるようになりました。
ジョブの終了後にそのジョブの詳細ページにアクセスすると3つのボタンが表示されます。 アーティファクトのアーカイブをダウンロードしたり、コンテンツを閲覧したり、Keepボタンでアーティファクトの有効期限を無期限にしたりできます。
アーカイブブラウザでは、アーカイブ内の各ファイルの名前と実際のファイルサイズを表示できます。アーティファクトにディレクトリが含まれている場合は、ディレクトリの中身を表示できます。
ブラウザでどのように見えるかを以下に示します。この例ではアーカイブ内には1つのディレクトリ、2つのファイル、1つのHTMLファイルがあります。GitLab Pagesが有効になっている場合は、オンラインでHTMLファイルを表示出来ます(新しいタブが開きます)。
アーティファクトをダウンロードする
アーティファクトやアーカイブをダウンロードは、GitLab UIの様々な場所からできます。
-
パイプラインページでは、各ジョブの右隅にアーティファクトとアーカイブのダウンロードアイコンが表示されます。
-
ジョブページでは、各ジョブの右隅にアーティファクトとアーカイブのダウンロードアイコンが表示されます。
-
ジョブの詳細ページでは、アーカイブを表示するボタンとダウンロードするボタンが表示されます。
-
そしてアーカイブを表示するページでは、右上にアーカイブのダウンロードするボタンが表示されます。
最新のアーティファクトをダウンロードする
ジョブの最新のアーティファクトをURLからダウンロードできるので、それをスクリプトの作成に利用できます。
他のパイプライン用のアーティファクトには、URLで直接アクセスできます。
以下が、アーティファクトのアーカイブ全体をダウンロードするためのURLになります。
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/download?job=<job_name>
アーティファクトから1つのファイルをダウンロードするには、以下のURLを使用してください。
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/raw/<path_to_file>?job=<job_name>
例えば、gitlab-org
ネームスペースに属するgitlab
プロジェクトのmaster
ブランチのcoverage
というジョブの最新のアーティファクトをダウンロードするURLは次のようになります。
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/download?job=coverage
同じアーティファクトからcoverage/index.html
ファイルをダウンロードするには、以下のURLを使用してください。
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/raw/coverage/index.html?job=coverage
また最新のジョブアーティファクトを表示するURLが次のようになります。
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/browse?job=<job_name>
使用例
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/browse?job=coverage
また、指定のHTMLファイルをGitLab Pagesで表示するためのURLもあります。
https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/file/<path>?job=<job_name>
例えばジョブcoverage
でアーティファクトhtmlcov/index.html
を作成した場合、以下のURLでアクセスできます。
https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/file/htmlcov/index.html?job=coverage
また複数のページで最新のビルドが公開されています。具体的には、以下ページでダウンロードボタンを探してください。
- プロジェクトのメインページ
- ブランチのページ
- タグのページ
最新のジョブでアーティファクトのアップロードに失敗した場合は、UIでその情報を確認できます。
アーティファクトの削除
UIで単一のジョブを削除でき、ジョブのアーティファクトやトレースも一緒に削除されます。削除操作が出来るのは次のユーザーです。
- ジョブの所有者。
- プロジェクトの管理者。
ジョブの削除手順。
- ジョブのページに移動します。
- ジョブのトレースの右上にあるゴミ箱アイコンをクリックします。
- 削除を確認します。
GitLab CIでプライベートプロジェクトのアーティファクトを取得する
別のプロジェクトのジョブアーティファクトを取得するには、認証してダウンロードするためにプライベートトークンが必要になる場合があります。