正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

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

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このAPIを使用して、ジョブアーティファクトをダウンロード、保持、削除します。

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

ジョブIDを使用して、ジョブのアーティファクトアーカイブをダウンロードします。

cURLを使用してGitLab.comからアーティファクトをダウンロードする場合は、リクエストがCDNを介してリダイレクトされる可能性があるため、--locationパラメータを使用します。

GET /projects/:id/jobs/:job_id/artifacts

サポートされている属性は以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
job_id整数はいジョブのID。
job_token文字列いいえマルチプロジェクトパイプライン用のCI/CDジョブトークン。PremiumおよびUltimateのみです。

成功した場合は、200を返し、アーティファクトファイルを提供します。

リクエスト例:

curl --request GET \
  --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts" \
  --output artifacts.zip

CI/CDジョブトークンを使用したリクエストの例:

# Uses the job_token parameter
artifact_download:
  stage: test
  script:
    - 'curl --request GET \
         --location \
         --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts?job_token=$CI_JOB_TOKEN" \
         --output artifacts.zip'

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

最新の正常なパイプラインから、参照名を使用してジョブのアーティファクトアーカイブをダウンロードします。search_recent_successful_pipelines=trueの場合、検索には指定された参照の最新の正常なパイプラインが最大100件含まれます。

最新の成功したパイプラインは、作成時刻に基づいて決定します。個々のジョブの開始時刻または終了時刻は、どのパイプラインが最新のパイプラインになるかに影響しません。

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

前提条件:

  • successステータスで完了したパイプラインが必要です。
  • パイプラインに手動ジョブが含まれている場合は、これらのジョブが次のいずれかである必要があります。
    • 正常に完了している。
    • allow_failure: trueが設定されている。

cURLを使用してGitLab.comからアーティファクトをダウンロードする場合は、リクエストがCDNを介してリダイレクトされる可能性があるため、--locationパラメータを使用します。

GET /projects/:id/jobs/artifacts/:ref_name/download?job=name

サポートされている属性は以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
job文字列はいジョブの名前。
ref_name文字列はいリポジトリ内のブランチ名またはタグ名。参照またはSHA参照はサポートされていません。マージリクエストパイプラインの場合は、ソースブランチ名の代わりにrefs/merge-requests/:iid/headを使用します。
job_token文字列いいえマルチプロジェクトパイプライン用のCI/CDジョブトークン。PremiumおよびUltimateのみです。
search_recent_successful_pipelinesブール値いいえ最新のパイプラインだけでなく、最近の正常なパイプライン全体を検索します。falseがデフォルトです。

成功した場合は、200を返し、アーティファクトファイルを提供します。

ジョブまたはアーティファクトが見つからない場合、404を返します。

リクエスト例:

curl --request GET \
  --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test"

CI/CDジョブトークンを使用したリクエストの例:

# Uses the job_token parameter
artifact_download:
  stage: test
  script:
    - 'curl --request GET \
         --location \
         --url "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN" \
         --output artifacts.zip'

最近のパイプライン検索を使用したリクエストの例:

curl --request GET \
  --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&search_recent_successful_pipelines=true"

ジョブIDで1つのアーティファクトファイルをダウンロードする

ジョブIDを使用して、ジョブのアーティファクトから単一ファイルをダウンロードします。ファイルはアーカイブから抽出され、クライアントにストリーミングされます。

cURLを使用してGitLab.comからアーティファクトをダウンロードする場合は、リクエストがCDNを介してリダイレクトされる可能性があるため、--locationパラメータを使用します。

GET /projects/:id/jobs/:job_id/artifacts/*artifact_path

サポートされている属性は以下のとおりです:

属性型必須説明
artifact_path文字列はいアーティファクトアーカイブ内のファイルのパス。
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
job_id整数はい一意のジョブ識別子。
job_token文字列いいえマルチプロジェクトパイプライン用のCI/CDジョブトークン。PremiumおよびUltimateのみです。

成功した場合は、200を返し、単一のアーティファクトファイルを送信します。

リクエスト例:

curl --request GET \
  --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/5/artifacts/some/release/file.pdf"

アーティファクトアーカイブ内のすべてのファイルをリスト表示します

指定したジョブのアーティファクトアーカイブ内のすべてのファイルとディレクトリをリスト表示します。この操作では、アーカイブ全体を抽出せずにアーティファクトメタデータを読み取るため、大規模なアーカイブの閲覧に効率的です。

GET /projects/:id/jobs/:job_id/artifacts/tree

サポートされている属性は以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
job_id整数はいジョブのID。
path文字列いいえアーティファクトアーカイブ内で参照するパス。ルートディレクトリにデフォルト設定されます。
recursiveブール値いいえtrueの場合、すべてのエントリを再帰的に返します。デフォルトはfalseです。
job_token文字列いいえ複数プロジェクトのパイプラインをトリガーするために使用されるCI/CDジョブトークン。PremiumおよびUltimateのみです。

このエンドポイントはページネーションをサポートしています。

成功した場合、200と次のレスポンス属性を返します:

属性型説明
name文字列ファイル名またはディレクトリ名。
path文字列アーティファクトアーカイブ内の完全なパス。ディレクトリには末尾にスラッシュが含まれます。
type文字列エントリのタイプ。指定可能な値: file、directory。
size整数ファイルのバイトサイズ。ファイルの場合にのみ表示されます。
mode文字列Unixファイルの8進形式モード。例えば、ファイルの場合は100644、ディレクトリの場合は040755です。

ジョブ、アーティファクト、アーティファクトメタデータ、または指定されたパスが見つからない場合、404を返します。

リクエスト例:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts/tree"

レスポンス例:

[
  {
    "name": "ci_build_artifacts.zip",
    "path": "ci_build_artifacts.zip",
    "type": "file",
    "size": 1024,
    "mode": "100644"
  },
  {
    "name": "other_artifacts_0.1.2",
    "path": "other_artifacts_0.1.2/",
    "type": "directory",
    "mode": "040755"
  }
]

サブディレクトリを閲覧するためのリクエスト例:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts/tree?path=coverage/reports"

再帰的リスト表示のためのリクエスト例:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts/tree?recursive=true"

CI/CDジョブトークンを使用したリクエストの例:

# Uses the job_token parameter
list_artifacts:
  stage: test
  script:
    - 'curl --request GET \
         --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts/tree?job_token=$CI_JOB_TOKEN"'

参照名で単一のアーティファクトファイルをダウンロードする

参照名を使用して、最新の成功したパイプラインでジョブのアーティファクトから1つのファイルをダウンロードします。ファイルはアーカイブから抽出され、plain/textコンテンツタイプでクライアントにストリーミングされます。search_recent_successful_pipelines=trueの場合、検索には指定された参照の最新の正常なパイプラインが最大100件含まれます。

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

アーティファクトファイルは、CSVエクスポートの場合よりも詳細な情報を提供します。

前提条件:

  • successステータスで完了したパイプラインが必要です。
  • パイプラインに手動ジョブが含まれている場合は、これらのジョブが次のいずれかである必要があります。
    • 正常に完了している。
    • allow_failure: trueが設定されている。
  • 最近の正常なパイプライン全体を検索するには、ci_search_recent_successful_pipelines機能フラグをプロジェクトで有効にする必要があります。

cURLを使用してGitLab.comからアーティファクトをダウンロードする場合は、リクエストがCDNを介してリダイレクトされる可能性があるため、--locationパラメータを使用します。

GET /projects/:id/jobs/artifacts/:ref_name/raw/*artifact_path?job=name

サポートされている属性は以下のとおりです:

属性型必須説明
artifact_path文字列はいアーティファクトアーカイブ内のファイルのパス。
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
job文字列はいジョブの名前。
ref_name文字列はいリポジトリ内のブランチ名またはタグ名。HEAD参照とSHA参照はサポートされていません。マージリクエストパイプラインの場合は、ソースブランチ名の代わりにrefs/merge-requests/:iid/headを使用します。
job_token文字列いいえマルチプロジェクトパイプライン用のCI/CDジョブトークン。PremiumおよびUltimateのみです。
search_recent_successful_pipelinesブール値いいえ最新のパイプラインだけでなく、最近の正常なパイプライン全体を検索します。falseがデフォルトです。

成功した場合は、200を返し、単一のアーティファクトファイルを送信します。

ジョブまたはアーティファクトファイルが見つからない場合、404を返します。

リクエスト例:

curl --request GET \
  --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/raw/some/release/file.pdf?job=pdf"

最近のパイプライン検索を使用したリクエストの例:

curl --request GET \
  --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/raw/some/release/file.pdf?job=pdf&search_recent_successful_pipelines=true"

ジョブのアーティファクトを保持する

ジョブのアーティファクトが有効期限に達したときに自動的に削除されないようにします。

POST /projects/:id/jobs/:job_id/artifacts/keep

サポートされている属性は以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
job_id整数はいジョブのID。

成功した場合は、200とジョブの詳細を返します。

リクエスト例:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts/keep"

レスポンス例:

{
  "commit": {
    "author_email": "admin@example.com",
    "author_name": "Administrator",
    "created_at": "2015-12-24T16:51:14.000+01:00",
    "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
    "message": "Test the CI integration.",
    "short_id": "0ff3ae19",
    "title": "Test the CI integration."
  },
  "coverage": null,
  "allow_failure": false,
  "download_url": null,
  "id": 42,
  "name": "rubocop",
  "ref": "main",
  "artifacts": [],
  "runner": null,
  "stage": "test",
  "created_at": "2016-01-11T10:13:33.506Z",
  "started_at": "2016-01-11T10:13:33.506Z",
  "finished_at": "2016-01-11T10:15:10.506Z",
  "duration": 97.0,
  "status": "failed",
  "failure_reason": "script_failure",
  "tag": false,
  "web_url": "https://example.com/foo/bar/-/jobs/42",
  "user": null
}

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

特定ジョブに関連付けられているすべてのアーティファクトを削除します。アーティファクトは削除されると復元できません。

前提条件:

  • プロジェクトのメンテナーまたはオーナーロールが必要です。
DELETE /projects/:id/jobs/:job_id/artifacts

サポートされている属性は以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
job_id整数はいジョブのID。

成功した場合、204 No Contentを返します。

リクエスト例:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/1/artifacts"

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

プロジェクト内で削除可能なすべてのジョブアーティファクトを削除します。アーティファクトは削除されると復元できません。

デフォルトでは、各refの最新の成功したパイプラインのアーティファクトは削除されません。

このエンドポイントへのリクエストは、削除できるすべてのジョブアーティファクトの有効期限を現在時刻に設定します。その後、有効期限切れのジョブアーティファクトの標準クリーンアップの一環として、ファイルがシステムから削除されます。ジョブログが削除されることはありません。

標準クリーンアップはスケジュールに従って非同期的に行われるため、アーティファクトが削除されるまでに少し時間がかかることがあります。

前提条件:

  • プロジェクトのメンテナーまたはオーナーロールが必要です。
DELETE /projects/:id/artifacts

サポートされている属性は以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。

成功した場合、202 Acceptedを返します。

リクエスト例:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/artifacts"

トラブルシューティング

マージリクエストパイプラインでブランチ名を使用する

ref_nameとしてブランチ名を使用してjob artifactsをダウンロードしようとすると、404 Not Foundエラーが発生する可能性があります。

この問題は、マージリクエストパイプラインが、ブランチパイプラインとは異なる参照形式を使用するために発生します。マージリクエストパイプラインは、ソースブランチに直接ではなく、refs/merge-requests/:iid/head上で実行されます。

マージリクエストパイプラインのジョブアーティファクトをダウンロードするには、ブランチ名の代わりにref_nameとしてrefs/merge-requests/:iid/headを使用します。:iidはマージリクエストIDです。マージリクエストのパイプラインでは、IDは変数$CI_MERGE_REQUEST_IIDから、完全なref_nameは変数$CI_MERGE_REQUEST_REF_PATHから利用できます。

たとえば、マージリクエスト!123の場合は以下のようになります。

curl --request GET \
  --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/refs/merge-requests/123/head/raw/file.txt?job=test"

artifacts:reportsファイルのダウンロード

ジョブアーティファクトAPIを使用してレポートをダウンロードしようとすると、404 Not Foundエラーが発生する場合があります。

この問題は、デフォルトではレポートをダウンロードできないために発生します。

レポートをダウンロードできるようにするには、そのファイル名またはgl-*-report.jsonをartifacts:pathsに追加します。