ジョブアーティファクト

  • 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

artifacts:reportsキーワードはジョブからテストレポート、コード品質レポート、セキュリティレポートを収集するために使用します。 またこれらのレポートをGitLabのUI(マージリクエスト、パイプラインビュー、セキュリティダッシュボード) で公開します。

Note: テストレポートは、ジョブの結果 (成功または失敗) に関係なく収集されます。artifacts:expire_inを使用して、そのアーティファクトの有効期限を設定できます。
Note: レポートとして出力したファイルを表示したい場合は、artifacts:pathsキーワードを含めてください。

artifacts:reports:junit

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にアップロードされマージリクエストに自動的に表示されます。

Note: 使用しているJUnitツールで複数のXMLファイルにエクスポートする場合、1つのジョブ内で複数のテストレポートのパスを指定すると自動的に1つのファイルに連結されます。 ファイル名のパターン(junit: rspec-*.xml)、ファイル名の配列(junit: [rspec-1.xml, rspec-2.xml, rspec-3.xml])、またはそれらの組み合わせ(junit: [rspec.xml, test-results/TEST-*.xml])を使用してください。

artifacts:reports:dotenv

dotenvレポートを使用すると、環境変数をアーティファクトとして収集できます。

収集された変数はジョブ実行時の変数として登録され、ジョブ終了後に動的環境のURLを設定するのに役立ちます。

元々のdotenvのルールとは、次の相違があります。

  • 変数キーに含めることができるのは、文字、数字、アンダースコア(_)のみです。
  • .envファイルの最大サイズは5KBです。
  • 変数の数は最大で10です。
  • .envファイル内の変数の置換はサポートされていません。
  • .envファイルには空行やコメント(#で始まる)を含めることはできません。
  • envファイル内のキーにはシングルクォーテーションやダブルクォーテーションを使用する場合を含め、スペースや改行文字(\n)を使用できません。
  • パース中のクウォートのエスケープ（key = 'value' -> {key: "value"}）はサポートされていません。

artifacts:reports:cobertura

coberturaレポートはCobertura coverage XMLファイルを収集します。 収集されたCoberturaのカバレッジレポートはアーティファクトとしてGitLabにアップロードされ、マージリクエストに自動的に表示されます。

Coberturaは元々Java用に開発されたものですがJavaScript、Python、Rubyなど他の言語への移植版が多数存在します。

artifacts:reports:terraform

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 以上が必要です。
Warning: このアーティファクトはまだ有効ですが非推奨です。代わりに、GitLab 12.8で導入されたartifacts:reports:license_scanningを使用してください。

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

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ボタンでアーティファクトの有効期限を無期限にしたりできます。

Job artifacts browser button

アーカイブブラウザでは、アーカイブ内の各ファイルの名前と実際のファイルサイズを表示できます。アーティファクトにディレクトリが含まれている場合は、ディレクトリの中身を表示できます。

ブラウザでどのように見えるかを以下に示します。この例ではアーカイブ内には1つのディレクトリ、2つのファイル、1つのHTMLファイルがあります。GitLab Pagesが有効になっている場合は、オンラインでHTMLファイルを表示出来ます（新しいタブが開きます）。

Job artifacts browser

アーティファクトをダウンロードする

アーティファクトやアーカイブをダウンロードは、GitLab UIの様々な場所からできます。

  1. パイプラインページでは、各ジョブの右隅にアーティファクトとアーカイブのダウンロードアイコンが表示されます。

    Job artifacts in Pipelines page

  2. ジョブページでは、各ジョブの右隅にアーティファクトとアーカイブのダウンロードアイコンが表示されます。

    Job artifacts in Builds page

  3. ジョブの詳細ページでは、アーカイブを表示するボタンとダウンロードするボタンが表示されます。

    Job artifacts browser button

  4. そしてアーカイブを表示するページでは、右上にアーカイブのダウンロードするボタンが表示されます。

    Job artifacts browser

最新のアーティファクトをダウンロードする

ジョブの最新のアーティファクトをURLからダウンロードできるので、それをスクリプトの作成に利用できます。

Note: 最新のアーティファクトは、特定のrefで直近に成功したパイプラインのジョブによって作成されます。同じrefに対して2種類のパイプラインを実行した場合、最新のアーティファクトはタイミングによって決定されます。 例えばマージリクエストを実施して作成されたブランチパイプラインが、スケジュールされたパイプラインと同時に実行された場合、最新のアーティファクトは一番最後に完了したパイプラインからのものになります。

他のパイプライン用のアーティファクトには、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でその情報を確認できます。

Latest artifacts button

アーティファクトの削除

Warning: データロストにつながる危険な操作です。注意して操作してください。

UIで単一のジョブを削除でき、ジョブのアーティファクトやトレースも一緒に削除されます。削除操作が出来るのは次のユーザーです。

  • ジョブの所有者。
  • プロジェクトの管理者。

ジョブの削除手順。

  1. ジョブのページに移動します。
  2. ジョブのトレースの右上にあるゴミ箱アイコンをクリックします。
  3. 削除を確認します。

GitLab CIでプライベートプロジェクトのアーティファクトを取得する

別のプロジェクトのジョブアーティファクトを取得するには、認証してダウンロードするためにプライベートトークンが必要になる場合があります。