ジョブアーティファクト

ジョブはファイルやディレクトリのアーカイブを出力できます。この出力はジョブアーティファクトと呼ばれます。アーティファクトには、ビルドの出力ファイルやレポートファイルを含めることができます。デフォルトでは、以降のジョブは、以前のステージングのジョブのすべてのアーティファクトのコピーをフェッチします。

たとえば、初期のジョブでプロジェクトをビルドし、出力をアーティファクトとして保存できます。その後、以降のジョブがアーティファクトをフェッチし、保存されたビルドの出力に対してテストを実行します。

artifactsキーワードでサポートされている設定の完全なリストについては、GitLab CI/CD YAML構文referenceを参照してください。

関連トピック:

• ジョブアーティファクトAPI
• ジョブアーティファクトの管理

ジョブアーティファクトを作成する

ジョブアーティファクトを作成するには、.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キーワードは、artifacts:pathsで定義されたアーティファクトをGitLabが保持する期間を指定します。次に例を示します:

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

expire_inが定義されていない場合は、インスタンス設定のデフォルトのアーティファクトの有効期限が使用されます。

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

デフォルトでは、各refにおける直近の成功したパイプラインのアーティファクトは常に保持されます。

明示的に定義したアーティファクト名を使用する

artifacts:name設定を使用して、アーティファクト名を明示的にカスタマイズできます:

job:
  artifacts:
    name: "job1-artifacts-file"
    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を使用すると、artifacts:pathsで定義したパスに加えて、Gitで追跡していないファイルをすべてアーティファクトとして追加できます。追跡していないファイルとは、リポジトリに追加されていないが、リポジトリのチェックアウトには存在するファイルのことです。

たとえば、Gitで追跡していないファイルとbinaries内のファイルをすべて保存する場合、次のようにします:

artifacts:
  untracked: true
  paths:
    - binaries/

たとえば、追跡していないファイルをすべて保存するが、*.txtファイルは除外する場合、次のようにします:

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

変数展開を使用する

変数の展開は、artifacts:name、artifacts:paths、artifacts:excludeでサポートされています。

GitLab Runnerは、shellを使用せず、内部変数展開メカニズムを使用します。このコンテキストでは、CI/CD変数のみがサポートされています。

たとえば、現在のブランチまたはタグ名を使用してアーカイブを作成し、現在のプロジェクト名のディレクトリからのファイルのみを含めるには、次のようにします:

job:
  artifacts:
    name: "$CI_COMMIT_REF_NAME"
    paths:
      - binaries/${CI_PROJECT_NAME}/

ブランチ名にスラッシュが含まれている場合（例: feature/my-feature）は、適切なアーティファクト名が付けられるように、$CI_COMMIT_REF_NAMEではなく$CI_COMMIT_REF_SLUGを使用します。

変数はglobより先に展開されます。

アーティファクトをフェッチする

デフォルトでは、ジョブは前のステージで定義されたジョブからすべてのアーティファクトをフェッチします。これらのアーティファクトは、ジョブの作業ディレクトリにダウンロードされます。

dependenciesまたはneeds:artifactsキーワードを使用して、ダウンロードするアーティファクトを制御できます。

これらのキーワードを使用すると、デフォルトの動作が変更され、指定したジョブからのみアーティファクトがフェッチされます。

ジョブがアーティファクトをフェッチしないようにする

ジョブがアーティファクトをダウンロードしないようにするには、dependenciesを空の配列（[]）に設定します:

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

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

ビルド > アーティファクトページから、プロジェクトに保存されているすべてのアーティファクトを表示できます。このリストには、すべてのジョブとそれに関連するアーティファクトが表示されます。エントリを展開して、ジョブに関連するすべてのアーティファクトにアクセスできます。これには以下が含まれます:

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

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

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

ジョブアーティファクトは、GitLab UIまたはAPIを使用してダウンロードできます。

GitLab UIから、次の場所からジョブのアーティファクトをダウンロードできます:

• パイプライン一覧。パイプラインの右側で、アーティファクトをダウンロード（ ）を選択します。
• ジョブ一覧。ジョブの右側で、アーティファクトをダウンロード（ ）を選択します。
• ジョブの詳細ページ。ページの右側で、ダウンロードを選択します。
• マージリクエスト概要ページ。最新のパイプラインの右側で、アーティファクト（ ）を選択します。
• アーティファクトページ。ジョブの右側で、ダウンロード（ ）を選択します。
• アーティファクトブラウザ。ページの上部で、アーティファクトのアーカイブをダウンロード（ ）を選択します。

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

URLからダウンロードする

公開URLを使用して、特定のジョブアーティファクトアーカイブをダウンロードできます。

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

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

アーティファクトから特定のファイルをダウンロードする場合:

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

このエンドポイントによって返されるファイルは、常にplain/textコンテンツタイプになります。

どちらの例でも、<project-id>を有効なプロジェクトIDに置き換えます。プロジェクトIDは、プロジェクトの概要ページで確認できます。

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

CI/CDジョブトークンを使用する

CI/CDジョブトークンを使用してジョブアーティファクトAPIエンドポイントに対して認証し、別のパイプラインからアーティファクトをフェッチできます。アーティファクトの取得元となるジョブを指定する必要があります。次に例を示します:

build_submodule:
  stage: test
  script:
    - apt update && apt install -y unzip
    - curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN"
    - unzip artifacts.zip

同じパイプライン内のジョブからアーティファクトをフェッチするには、needs:artifactsキーワードを使用します。

アーティファクトをダウンロードできるユーザーの制御

ジョブのアーティファクトをダウンロードできるユーザーを制限するには、artifacts:accessファイルで.gitlab-ci.ymlキーワードを使用します。次に例を示します:

job:
  artifacts:
    access: maintainer
    paths:
      - build/

アーティファクトアーカイブの内容を閲覧する

UIからアーティファクトをローカルにダウンロードすることなく、次の場所からアーティファクトの内容を閲覧できます:

• ジョブ一覧。ジョブの右側で、閲覧（ ）を選択します。
• ジョブの詳細ページ。ページの右側で、閲覧を選択します。
• アーティファクトページ。ジョブの右側で、閲覧（ ）を選択します。

GitLab Pagesがグローバルに有効な場合、プロジェクト設定で無効になっていても、一部のアーティファクトファイル拡張子をブラウザで直接プレビューできます。プロジェクトが内部または非公開の場合、プレビューを有効にするには、GitLab Pagesへのアクセス制御を有効にする必要があります。

次の拡張子がサポートされています:

URLからダウンロードする

公開URLを使用して、特定のジョブを実行した直近の成功したパイプラインのジョブアーティファクトを閲覧できます。

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

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

<full-project-path>を有効なプロジェクトパスに置き換えます。プロジェクトパスはプロジェクトのURLで確認できます。

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

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

前提要件:

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

ジョブを削除するには、次のようにします:

1. ジョブの詳細ページに移動します。
2. ジョブのログの右上隅で、ジョブのログとアーティファクトを消去（ ）を選択します。

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

アーティファクトを一括削除する

複数のアーティファクトを同時に削除するには、次の手順に従います:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. ビルド > アーティファクトを選択します。
3. 削除するアーティファクトの横にあるチェックボックスを選択します。最大100個のアーティファクトを選択できます。
4. 一括削除を選択します。

マージリクエストUIでジョブアーティファクトへのリンクを表示する

artifacts:expose_asキーワードを使用して、マージリクエストUIからアーティファクトへの直接アクセスを提供します。

単一のファイルを含むアーティファクトの場合:

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

この設定では、公開されたアーティファクトを表示セクションに、file.txtというラベルの付いたartifact 1へのリンクが表示されます。

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

デフォルトでは、各refにおける直近の成功したパイプラインのアーティファクトは常に保持されます。expire_in設定は、直近のアーティファクトには適用されません。

同じrefに対する新しいパイプラインが正常に完了すると、expire_in設定に従って前のパイプラインのアーティファクトが削除されます。新しいパイプラインのアーティファクトは自動的に保持されます。

パイプラインのアーティファクトは、同じrefに対して新しいパイプラインが実行され、次の条件が満たされた場合にのみ、expire_in設定に従って削除されます:

• 成功する。
• 手動ジョブによってブロックされたために実行が停止する。

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

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにしている場合、このフィールドは上部のバーにあります。
2. 設定 > CI/CDを選択します。
3. アーティファクトを展開します。
4. 成功した最新のジョブのアーティファクトを保持するチェックボックスをオフにします。

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

GitLab Self-Managedのすべてのプロジェクトでこの動作を無効にするには、Keep artifacts from latest successful pipelines（成功した最新のパイプラインのアーティファクトを保持する）インスタンス設定を使用します。

GitLab Self-Managedでは、インスタンスのCI/CD設定でこの動作をすべてのプロジェクトに対して無効にできます。