正式なドキュメントは英語版であり、この日本語訳は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 --location --output artifacts.zip \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts"

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

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

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

参照名を使用して、最新の成功したパイプラインでジョブのアーティファクトのアーカイブをダウンロードします。

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

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

前提要件:

  • 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のみです。

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

リクエスト例:

curl --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 --location --output artifacts.zip \
         --url "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/main/download?job=test&job_token=$CI_JOB_TOKEN"'

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

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

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 --location \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/5/artifacts/some/release/file.pdf"

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

参照名を使用して、最新の成功したパイプラインでジョブのアーティファクトから1つのファイルをダウンロードします。ファイルはアーカイブから抽出され、plain/textコンテンツタイプでクライアントにストリーミングされます。

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

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

前提要件:

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

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のみです。

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

リクエスト例:

curl --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"

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

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

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 --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に追加します。