이 API로 job 아티팩트를 다운로드하고 보존하고 삭제합니다.

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

히스토리

• GitLab 19.4에 file_type 속성이 도입됐습니다.

job ID로 job의 아티팩트 아카이브를 다운로드합니다. 특정 리포트 파일(예: JUnit 테스트 결과)을 다운로드하려면 file_type 속성을 사용합니다.

cURL로 GitLab.com에서 아티팩트를 다운로드할 때는 요청이 CDN을 거쳐 리디렉션될 수 있으므로 --location 파라미터를 사용합니다.

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

지원하는 속성:

성공하면 200을 반환하고 아티팩트 파일을 전송합니다. file_type 이 지원하지 않는 값이면 400을 반환합니다.

요청 예시:

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

JUnit 테스트 리포트 요청 예시:

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

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 아티팩트 다운로드#

히스토리

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

참조 이름으로 최신 성공 파이프라인에서 job의 아티팩트 아카이브를 다운로드합니다. search_recent_successful_pipelines=true 이면 지정한 참조의 최근 성공 파이프라인을 최대 100 개까지 검색합니다.

최신 성공 파이프라인은 생성 시각을 기준으로 결정합니다. 개별 job의 시작 시각이나 종료 시각은 어떤 파이프라인이 최신인지에 영향을 주지 않습니다.

부모·자식 파이프라인에서는 부모에서 자식 순의 계층 순서로 아티팩트를 검색합니다. 부모와 자식 파이프라인에 이름이 같은 job 이 있으면 부모 파이프라인의 아티팩트를 반환합니다.

필수 조건:

• success 상태로 완료된 파이프라인이 있어야 합니다.
• 파이프라인에 수동 job 이 포함돼 있으면 다음 중 하나를 충족해야 합니다.
  • 성공적으로 완료됩니다.
  • allow_failure: true가 설정돼 있습니다.

cURL로 GitLab.com에서 아티팩트를 다운로드할 때는 요청이 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 --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"

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

job ID로 job 아티팩트에서 파일 하나를 다운로드합니다. 해당 파일은 아카이브에서 추출돼 클라이언트로 스트리밍됩니다.

cURL로 GitLab.com에서 아티팩트를 다운로드할 때는 요청이 CDN을 거쳐 리디렉션될 수 있으므로 --location 파라미터를 사용합니다.

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

지원하는 속성:

성공하면 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"

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

히스토리

• GitLab 18.8에 도입됐습니다.

지정한 job의 아티팩트 아카이브에 있는 모든 파일과 디렉터리를 나열합니다. 이 작업은 전체 아카이브를 추출하지 않고 아티팩트 메타데이터만 읽으므로 큰 아카이브를 탐색할 때 효율적입니다.

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

지원하는 속성:

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

성공하면 200과 다음 응답 속성을 반환합니다.

job, 아티팩트, 아티팩트 메타데이터, 지정한 경로를 찾을 수 없으면 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 job 토큰을 사용하는 요청 예시:

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

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

히스토리

• GitLab 18.9에 search_recent_successful_pipelines 속성이 ci_search_recent_successful_pipelines 기능 플래그와 함께 도입됐습니다. 기본적으로 비활성화돼 있습니다.
• 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 기능 플래그를 활성화해야 합니다.

cURL로 GitLab.com에서 아티팩트를 다운로드할 때는 요청이 CDN을 거쳐 리디렉션될 수 있으므로 --location 파라미터를 사용합니다.

GET /projects/:id/jobs/artifacts/:ref_name/raw/*artifact_path?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/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"

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의 아티팩트를 삭제합니다. 아카이브된 파일, 메타데이터, JUnit 리포트 같은 리포트 아티팩트가 삭제 대상입니다. 이 엔드포인트는 job 로그를 삭제하지 않습니다. 삭제한 아티팩트는 복구할 수 없습니다.

job 로그까지 함께 삭제하려면 job 지우기 API 엔드포인트를 사용합니다.

필수 조건:

• 프로젝트의 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 아티팩트를 삭제합니다. 삭제한 아티팩트는 복구할 수 없습니다.

기본적으로 GitLab은 만료 여부와 관계없이 각 참조에서 가장 최근에 완료된 파이프라인과 가장 최근에 성공한 파이프라인의 아티팩트를 보관합니다. 자세한 내용은 가장 최근에 성공한 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 --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 파일 다운로드#

job 아티팩트 API로 리포트를 다운로드하면 404 Not Found 오류가 발생할 수 있습니다.

리포트가 기본적으로 아티팩트 아카이브에 포함되지 않기 때문입니다.

이 문제를 해결하려면 job ID로 job 아티팩트 다운로드를 사용하고 file_type을 원하는 리포트 유형으로 설정합니다.

대안으로, 리포트 파일 이름이나 gl-*-report.json을 artifacts:paths에 추가해 리포트를 아티팩트 아카이브 자체에 포함할 수도 있습니다.