ジョブのアーティファクト

ジョブはファイルやディレクトリのアーカイブを出力することができます。この出力はジョブアーティファクトとして知られています。

GitLab UI やAPI を使ってジョブアーティファクトをダウンロードすることができます。

ジョブアーティファクトの概要については、ビデオGitLab CIパイプライン、アーティファクト、環境をご覧ください。または、GitLab CIパイプラインチュートリアル(初心者向け)をご覧ください。

ジョブアーティファクトの保存に関する管理者の情報については、ジョブアーティファクトの管理をご覧ください。

ジョブアーティファクトの作成

ジョブのアーティファクトを作成するには、.gitlab-ci.yml ファイルでartifacts キーワードを使用します:

pdf:
  script: xelatex mycv.tex
  artifacts:
    paths:
      - mycv.pdf

この例では、pdf という名前のジョブが、xelatex コマンドを呼び出して、LaTeX ソースファイルmycv.tex から PDF ファイルを作成しています。

paths キーワードは、ジョブのアーティファクトに追加するファイルを決定します。ファイルとディレクトリへのすべてのパスは、ジョブが作成されたリポジトリからの相対パスです。

ワイルドカード

パスとディレクトリにワイルドカードを使用できます。たとえば、xyz で終わるディレクトリ内部のすべてのファイルを含むアーティファクトを作成するには :

job:
  script: echo "build xyz project"
  artifacts:
    paths:
      - path/*xyz/*

有効期限付き

expire_in キーワードは、GitLab がジョブのアーティファクトを保持する期間を決定します。例えば

pdf:
  script: xelatex mycv.tex
  artifacts:
    paths:
      - mycv.pdf
    expire_in: 1 week

expire_in が定義されていない場合、インスタンス全体の設定が使用されます。

アーティファクトが期限切れにならないようにするには、ジョブの詳細ページで [保持] を選択します。アーティファクトに有効期限が設定されていない場合、このオプションは使用できません。

動的に定義された名前で

CI/CD変数を使って、アーティファクトファイルの名前を動的に定義することができます。

例えば、現在のジョブの名前でアーカイブを作成する場合です:

job:
  artifacts:
    name: "$CI_JOB_NAME"
    paths:
      - binaries/

ブランチまたはタグの名前で、バイナリディレクトリのみを含むアーカイブを作成します。

job:
  artifacts:
    name: "$CI_COMMIT_REF_NAME"
    paths:
      - binaries/

ブランチ名にスラッシュが含まれている場合 (たとえばfeature/my-feature)、アーティファクトの適切な命名のために$CI_COMMIT_REF_NAME の代わりに$CI_COMMIT_REF_SLUG を使用してください。

WindowsランナーまたはShell Executorの場合

Windowsバッチを使用してシェルスクリプトを実行する場合は、$% に置き換える必要があります:

job:
  artifacts:
    name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
    paths:
      - binaries/

Windows PowerShell を使用してシェルスクリプトを実行する場合は、$$env: に置き換える必要があります:

job:
  artifacts:
    name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
    paths:
      - binaries/

除外ファイルなし

アーティファクト アーカイブにファイルが追加されないようにするには、artifacts:exclude を使用します。

た と えば、binaries/ 内のすべての フ ァ イ ルを格納 し 、binaries/ のサブデ ィ レ ク ト リ 内の*.o フ ァ イ ルは格納 し ない よ う に し ます。

artifacts:
  paths:
    - binaries/
  exclude:
    - binaries/**/*.o

artifacts:paths と異なり、exclude のパスは再帰的ではありません。ディレクトリのすべての内容を除外するには、ディレクトリ自体をマッチさせるのではなく、明示的にマッチさせます。

たとえば、binaries/ にあるすべてのファイルを保存し、temp/ サブディレクトリには何も保存しない場合:

artifacts:
  paths:
    - binaries/
  exclude:
    - binaries/temp/**/*

追跡されていないファイル

artifacts:untracked を使うと、Git の追跡されていないファイルをすべてアーティファクトとして追加できます (artifacts:pathsで定義したパスも追加されます)。未追跡のファイルとは、リポジトリには追加されていないがリポジトリのチェックアウトには存在するファイルのことです。

たとえば、すべての Git 未追跡ファイルとbinaries にあるファイルを保存するには、次のようにします:

artifacts:
  untracked: true
  paths:
    - binaries/

たとえば、追跡されていないすべてのファイルを保存し、*.txt のファイルは除外します:

artifacts:
  untracked: true
  exclude:
    - "*.txt"

ジョブがアーティファクトを取得しないようにします。

ジョブはデフォルトで、前のステージで完了したジョブからすべてのアーティファクトをダウンロードします。ジョブがアーティファクトをダウンロードしないようにするには、dependencies に空の配列 ([]) を設定します:

job:
  stage: test
  script: make build
  dependencies: []

プロジェクト内のすべてのジョブのアーティファクトの表示

Build > Artifactsページから、プロジェクトに保存されている全てのアーティファクトを見ることができます。このリストには、すべてのジョブと関連するアーティファクトが表示されます。エントリを展開すると、ジョブに関連付けられているすべてのアーティファクトにアクセスできます:

  • artifacts: キーワードで作成されたアーティファクト。
  • アーティファクトを報告してください。
  • 別のアーティファクトとして内部に保存されるジョブログとメタデータ。

このリストから個々のアーティファクトをダウンロードまたは削除できます。

アーティファクトのダウンロード

ジョブのアーティファクトは以下からダウンロードできます:

  • 任意のパイプラインリスト。パイプラインの右側で、アーティファクトのダウンロード({download}) を選択します。
  • 任意のジョブリスト。ジョブの右側にあるDownload artifacts({download}) を選択します。
  • ジョブの詳細ページ。ページの右側で、ダウンロードを選択します。
  • マージリクエストの概要ページ。最新のパイプラインの右側で、アーティファクト({download}) を選択します。
  • その アーティファクトページを開きます。ジョブの右側でDownload({download}) を選択します。
  • アーティファクトブラウザ。ページの上部で、アーティファクトアーカイブのダウンロード({download}) を選択します。

レポート アーティファクトはパイプラインリストまたはアーティファクトページからのみダウンロードできます。

ジョブ成果物API を使用すると、最新の成功したパイプラインからジョブ成果物をダウンロードできます。レポートがartifacts:paths で通常のアーティファクトとして追加されていない限り、ジョブアーティファクト API を使用してアーティファクトレポートをダウンロードすることはできません。

URL から

ジョブ成果物APIの公開URLから、特定のジョブのアーティファクトアーカイブをダウンロードできます。

例えば、GitLab.com のプロジェクトのmain ブランチにあるbuild という名前のジョブの最新のアーティファクトをダウンロードする場合:

https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/download?job=build

例えば、GitLab.com のプロジェクトのmain ブランチにあるbuild という最新のジョブのファイルreview/index.html をダウンロードするには:

https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/raw/review/index.html?job=build

どちらのページでも、<project-id> をプロジェクトの詳細ページの一番上にある有効なプロジェクト ID に置き換えてください。

親パイプラインと子パイプラインのアーティファクトは、親から子へと階層順に検索されます。例えば、親パイプラインと子パイプラインの両方に同じ名前のジョブがある場合、親パイプラインのジョブのアーティファクトが返されます。

アーティファクト アーカイブの内容を参照します。

アーティファクトをローカルにダウンロードしなくても、UIからアーティファクトの内容を参照できます:

  • 任意のジョブリスト。ジョブの右側にあるBrowse({folder-open}) を選択します。
  • ジョブの詳細ページ。ページの右側にある「参照」を選択します。
  • アーティファクトページ。ジョブの右側で、Browse({folder-open}) を選択します。

GitLab Pagesがプロジェクトで有効になっている場合、アーティファクト内のHTMLファイルをブラウザで直接プレビューすることができます。プロジェクトが内部または非公開の場合、HTMLファイルをプレビューするにはGitLab Pagesのアクセスコントロールを有効にする必要があります。

URL から

公開されたURLから、特定のジョブの最新のパイプラインのアーティファクトを参照できます。

例えば、GitLab.com のプロジェクトのmain ブランチにあるbuild というジョブの最新の成果物をブラウズする場合:

https://gitlab.com/<full-project-path>/-/jobs/artifacts/main/browse?job=build

<full-project-path> を有効なプロジェクトのパスに置き換えてください。プロジェクトの URL で見つけることができます。

ジョブログとアーティファクトの削除

caution
ジョブログとアーティファクトの削除は、元に戻せない破壊的なアクションです。注意して使用してください。レポートアーティファクト、ジョブログ、メタデータファイルを含む特定のファイルを削除すると、これらのファイルをデータソースとして使用するGitLab機能に影響を与えます。

ジョブのアーティファクトとログを削除できます。

前提条件:

  • ジョブのオーナー、またはプロジェクトのメンテナー以上のロールを持つユーザーである必要があります。

ジョブを削除するには

  1. ジョブの詳細ページに移動します。
  2. ジョブのログの右上隅で、Erase job log and artifacts({remove}) を選択します。

アーティファクトページから個々のアーティファクトを削除することもできます。

アーティファクトの一括削除

複数のアーティファクトを同時に削除することができます:

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. ビルド > アーティファクトを選択します。
  3. 削除するアーティファクトの横にあるチェックボックスを選択します。最大 50 のアーティファクトを選択できます。
  4. 選択したランナーを削除を選択します。

マージリクエストUI にジョブ成果物へのリンクを表示するには、artifacts:expose_as キーワードを使用します。

例えば、単一のファイルを持つアーティファクトの場合:

test:
  script: ["echo 'test' > file.txt"]
  artifacts:
    expose_as: 'artifact 1'
    paths: ['file.txt']

この設定で、GitLab はアーティファクト 1 を file.txt へのリンクとして関連マージリクエストのView exposed artifactセクションに追加します。

最近成功したジョブのアーティファクトを保持

デフォルトでは、成功したパイプラインのアーティファクトは常に各refの最新のコミットに対して保持されます。これは、expire_in の設定に従って、最新のアーティファクトがすぐに期限切れにならないことを意味します。

同じrefの新しいコミットのパイプラインが成功した場合、expire_in の設定に従って、前のパイプラインのアーティファクトは削除されます。新しいパイプラインのアーティファクトは自動的に保持されます。Refの最新のコミットに対して複数のパイプラインが実行された場合、すべてのアーティファクトが保持されます。

多くのジョブや大きなアーティファクトを持つプロジェクトでは、最新のアーティファクトを保持すると、大量のストレージを使用する可能性があります。プロジェクトで最新のアーティファクトが必要ない場合は、この動作を無効にして容量を節約できます:

  1. 左のサイドバーで「検索」または「移動」を選択してあなたのプロジェクトを検索します。
  2. Settings > CI/CDを選択します。
  3. アーティファクトを展開します。
  4. 最近成功したジョブからアーティファクトを保持する]チェックボックスをオフにします。

この設定を無効にすると、すべての新しいアーティファクトはexpire_in の設定に従って期限切れになります。古いパイプラインのアーティファクトは、同じ参照に対して新しいパイプラインが実行されるまで保持され続けます。その後、その参照に対する以前のパイプラインのアーティファクトも期限切れになります。

インスタンスのCI/CD設定で、セルフマネージドインスタンス上のすべてのプロジェクトに対してこの動作を無効にできます。

Keep artifacts from most recent successful jobsを有効にすると、ブロックされたパイプラインのアーティファクトは常に保持されます。これらのアーティファクトは、ブロックされたジョブがトリガーされ、パイプラインが完了した後にのみ失効します。イシュー 387087では、この動作の変更を提案しています。