이 API를 사용하여 Job 아티팩트를 다운로드, 유지 및 삭제합니다.

Job ID로 Job 아티팩트 다운로드#

Job ID를 사용하여 Job의 아티팩트 아카이브를 다운로드합니다.

GitLab.com에서 cURL을 사용하여 아티팩트를 다운로드하는 경우, 요청이 CDN을 통해 리다이렉트될 수 있으므로 --location 파라미터를 사용하세요.

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

지원되는 속성:

성공 시 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 Job 토큰을 사용한 요청 예시:

# 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'

참조 이름으로 Job 아티팩트 다운로드#

히스토리

• search_recent_successful_pipelines 속성이 ci_search_recent_successful_pipelines라는 플래그와 함께 GitLab 18.7에서 도입되었습니다. 기본적으로 비활성화됩니다.
• GitLab 18.10에서 기능 플래그 ci_search_recent_successful_pipelines가 제거되었습니다.

참조 이름을 사용하여 최신 성공한 파이프라인에서 Job의 아티팩트 아카이브를 다운로드합니다. search_recent_successful_pipelines=true인 경우, 지정된 참조에 대해 최근 성공한 파이프라인 최대 100개를 검색합니다.

최신 성공한 파이프라인은 생성 시간을 기준으로 결정됩니다. 개별 Job의 시작 또는 종료 시간은 어떤 파이프라인이 최신인지에 영향을 주지 않습니다.

상위 및 하위 파이프라인의 경우, 아티팩트는 상위에서 하위로 계층 순서로 검색됩니다. 상위 파이프라인과 하위 파이프라인 모두 동일한 이름의 Job이 있는 경우 상위 파이프라인의 아티팩트가 반환됩니다.

사전 요구 사항:

• success 상태의 완료된 파이프라인이 있어야 합니다.
• 파이프라인에 수동 Job이 포함된 경우 다음 중 하나여야 합니다:
  • 성공적으로 완료됩니다.
  • allow_failure: true가 설정되어 있습니다.

GitLab.com에서 cURL을 사용하여 아티팩트를 다운로드하는 경우, 요청이 CDN을 통해 리다이렉트될 수 있으므로 --location 파라미터를 사용하세요.

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

지원되는 속성:

성공 시 200을 반환하고 아티팩트 파일을 제공합니다.

Job 또는 아티팩트를 찾을 수 없는 경우 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 Job 토큰을 사용한 요청 예시:

# 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 --location \
  --header "PRIVATE-TOKEN: " \
  --url "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test&search_recent_successful_pipelines=true"

Job ID로 단일 아티팩트 파일 다운로드#

Job ID를 사용하여 Job의 아티팩트에서 단일 파일을 다운로드합니다. 파일은 아카이브에서 추출되어 클라이언트로 스트리밍됩니다.

GitLab.com에서 cURL을 사용하여 아티팩트를 다운로드하는 경우, 요청이 CDN을 통해 리다이렉트될 수 있으므로 --location 파라미터를 사용하세요.

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

지원되는 속성:

성공 시 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"

아티팩트 아카이브의 모든 파일 나열#

히스토리

• GitLab 18.8에서 도입되었습니다.

지정된 Job의 아티팩트 아카이브에 있는 모든 파일과 디렉토리를 나열합니다. 이 작업은 전체 아카이브를 추출하지 않고 아티팩트 메타데이터를 읽어 대용량 아카이브 탐색에 효율적입니다.

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

지원되는 속성:

이 엔드포인트는 페이지네이션을 지원합니다.

성공 시 200과 다음 응답 속성을 반환합니다:

Job, 아티팩트, 아티팩트 메타데이터 또는 지정된 경로를 찾을 수 없는 경우 404를 반환합니다.

요청 예시:

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

재귀적 목록을 위한 요청 예시:

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

CI/CD Job 토큰을 사용한 요청 예시:

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

참조 이름으로 단일 아티팩트 파일 다운로드#

히스토리

• search_recent_successful_pipelines 속성이 ci_search_recent_successful_pipelines라는 플래그와 함께 GitLab 18.9에서 도입되었습니다. 기본적으로 비활성화됩니다.
• GitLab 18.10에서 기능 플래그 ci_search_recent_successful_pipelines가 제거되었습니다.

참조 이름을 사용하여 최신 성공한 파이프라인의 Job 아티팩트에서 단일 파일을 다운로드합니다. 파일은 아카이브에서 추출되어 plain/text 콘텐츠 유형으로 클라이언트에게 스트리밍됩니다. search_recent_successful_pipelines=true인 경우, 지정된 참조에 대해 최근 성공한 파이프라인 최대 100개를 검색합니다.

상위 및 하위 파이프라인의 경우, 아티팩트는 상위에서 하위로 계층 순서로 검색됩니다. 상위 파이프라인과 하위 파이프라인 모두 동일한 이름의 Job이 있는 경우 상위 파이프라인의 아티팩트가 반환됩니다.

아티팩트 파일은 CSV 내보내기에서 사용할 수 있는 것보다 더 자세한 세부 정보를 제공합니다.

사전 요구 사항:

• success 상태의 완료된 파이프라인이 있어야 합니다.
• 파이프라인에 수동 Job이 포함된 경우 다음 중 하나여야 합니다:
  • 성공적으로 완료됩니다.
  • allow_failure: true가 설정되어 있습니다.
• 최근 성공한 파이프라인에서 검색하려면 프로젝트에 대해 ci_search_recent_successful_pipelines 기능 플래그가 활성화되어 있어야 합니다.

GitLab.com에서 cURL을 사용하여 아티팩트를 다운로드하는 경우, 요청이 CDN을 통해 리다이렉트될 수 있으므로 --location 파라미터를 사용하세요.

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

지원되는 속성:

성공 시 200을 반환하고 단일 아티팩트 파일을 전송합니다.

Job 또는 아티팩트 파일을 찾을 수 없는 경우 404를 반환합니다.

요청 예시:

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"

최근 파이프라인 검색을 사용한 요청 예시:

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&search_recent_successful_pipelines=true"

Job 아티팩트 유지#

Job 아티팩트가 만료 날짜에 자동으로 삭제되는 것을 방지합니다.

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

지원되는 속성:

성공 시 200과 Job 세부 정보를 반환합니다.

요청 예시:

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
}

Job 아티팩트 삭제#

특정 Job과 관련된 모든 아티팩트를 삭제합니다. 아티팩트는 삭제 후 복구할 수 없습니다.

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

DELETE /projects/:id/jobs/:job_id/artifacts

지원되는 속성:

성공 시 204 No Content를 반환합니다.

요청 예시:

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

프로젝트의 모든 Job 아티팩트 삭제#

프로젝트에서 삭제 가능한 모든 Job 아티팩트를 삭제합니다. 아티팩트는 삭제 후 복구할 수 없습니다.

기본적으로 각 참조의 가장 최근 성공한 파이프라인의 아티팩트는 삭제되지 않습니다.

이 엔드포인트에 대한 요청은 삭제 가능한 모든 Job 아티팩트의 만료 시간을 현재 시간으로 설정합니다. 그런 다음 만료된 Job 아티팩트의 정기적인 정리의 일부로 파일이 시스템에서 삭제됩니다. Job 로그는 삭제되지 않습니다.

정기적인 정리는 일정에 따라 비동기적으로 발생하므로 아티팩트가 삭제되기 전에 짧은 지연이 있을 수 있습니다.

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

DELETE /projects/:id/artifacts

지원되는 속성:

성공 시 202 Accepted를 반환합니다.

요청 예시:

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

문제 해결#

머지 리퀘스트 파이프라인과 함께 브랜치 이름 사용#

브랜치 이름을 ref_name으로 사용하여 Job 아티팩트를 다운로드하려고 할 때 404 Not Found 오류가 발생할 수 있습니다.

이 이슈는 머지 리퀘스트 파이프라인이 브랜치 파이프라인과 다른 참조 형식을 사용하기 때문에 발생합니다. 머지 리퀘스트 파이프라인은 소스 브랜치에 직접 실행되는 것이 아니라 refs/merge-requests/:iid/head에서 실행됩니다.

머지 리퀘스트 파이프라인의 Job 아티팩트를 다운로드하려면 브랜치 이름 대신 refs/merge-requests/:iid/head를 ref_name으로 사용하세요. 여기서 :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 파일 다운로드#

Job 아티팩트 API를 사용하여 보고서를 다운로드하려고 할 때 404 Not Found 오류가 발생할 수 있습니다.

이 이슈는 보고서가 기본적으로 다운로드 가능하지 않기 때문에 발생합니다.

보고서를 다운로드 가능하게 하려면 파일 이름 또는 gl-*-report.json을 artifacts:paths에 추가하세요.