job은 파일과 디렉터리의 아카이브를 출력할 수 있습니다. 이 출력을 job 아티팩트라고 합니다. 아티팩트에는 빌드 출력이나 리포트 파일이 포함될 수 있습니다. 기본적으로 이후 job은 이전 Stage에 있는 job의 모든 아티팩트 사본을 가져옵니다.

예를 들어 초반 job이 프로젝트를 빌드하고 그 출력을 아티팩트로 저장할 수 있습니다. 이후 job은 그 아티팩트를 가져와 저장된 빌드 출력에 대해 테스트를 실행합니다.

artifacts 키워드에서 지원하는 설정의 전체 목록은 GitLab CI/CD YAML 구문 참조를 확인합니다.

관련 주제:

• Job 아티팩트 API
• Job 아티팩트 관리

Job 아티팩트와 패키지 레지스트리 선택#

Job 아티팩트와 패키지 레지스트리는 모두 파이프라인이 생성한 파일을 저장할 수 있습니다. 파일이 유지되는 기간과 사용할 수 있는 대상이 다릅니다.

하나의 파이프라인에 속하는 출력에는 job 아티팩트를 사용합니다. 파이프라인이 끝난 뒤에 사람이나 다른 프로젝트가 사용하는 출력에는 패키지 레지스트리를 사용합니다.

선택하려면 출력을 다음 경우 중 하나에 맞춥니다.

패키지 레지스트리는 패키지 버전, 중복 처리, 파이프라인과 무관하게 동작하는 정리 정책도 제공합니다.

큰 아티팩트 처리#

한 파이프라인의 job 사이에서 전달하는 출력은 크더라도 보통 job 아티팩트에 속합니다.

크기 제한은 파일 단위가 아니라 아티팩트 아카이브 단위로 적용됩니다.

• GitLab.com에서는 압축 기준 1GB가 제한입니다. 자세한 내용은 GitLab.com 설정을 참고합니다.
• GitLab Self-Managed와 GitLab Dedicated에서는 관리자가 인스턴스, 그룹 또는 프로젝트에 대한 제한을 설정할 수 있습니다. 자세한 내용은 최대 아티팩트 크기 설정을 참고합니다.

일부 리포트 아티팩트 유형은 더 낮은 제한이 있습니다. 자세한 내용은 아티팩트 유형별 최대 파일 크기를 참고합니다.

출력이 너무 크면 다음 옵션 중 하나를 사용합니다.

• 아카이브를 줄입니다. 이후 job에 필요한 경로만 artifacts:paths에 나열하거나 artifacts:exclude로 파일을 제외합니다.
• 출력을 여러 job에 나눕니다. 각 job의 아카이브에는 자체 제한이 있으므로 여러 job이 출력의 일부를 각각 업로드할 수 있습니다. 이 방식은 스토리지 사용량과 파이프라인 복잡도를 높이므로 아카이브를 줄일 수 없을 때만 사용합니다.
• 일반 패키지 레지스트리로 파일을 전달합니다. 출력을 줄이거나 나눌 수 없을 때만 이 옵션을 사용합니다. GitLab.com에서 일반 패키지 파일은 최대 5GB까지 가능합니다. 패키지는 자동으로 만료되지 않습니다. Maintainer 또는 Owner 권한을 가진 사용자가 삭제할 때까지 레지스트리에 남아 있습니다. 예시는 일반 패키지 레지스트리로 큰 파일 전달을 참고합니다.

artifacts:reports로 만드는 것과 같은 리포트 아티팩트는 GitLab이 파이프라인에서 읽으므로 패키지 레지스트리로 옮길 수 없습니다. 리포트 아티팩트를 제한 안에 맞추려면 아카이브를 줄입니다.

일반 패키지 레지스트리로 큰 파일 전달#

job 사이에서 큰 파일을 전달하려면 한 job에서 일반 패키지 레지스트리에 업로드하고 이후 job에서 다운로드합니다. 파이프라인이 끝나면 패키지를 삭제합니다. 각 파이프라인이 자체 패키지를 갖도록 파이프라인 ID를 패키지 버전으로 사용합니다.

variables:
  PACKAGE_URL: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/pipeline-handoff/${CI_PIPELINE_ID}"

build:
  stage: build
  # The build and test jobs need an image that includes curl. They use the runner's default image.
  script:
    - make image  # Creates image.tar.gz
    - 'curl --fail --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --upload-file image.tar.gz "${PACKAGE_URL}/image.tar.gz"'

test:
  stage: test
  script:
    - 'curl --fail --header "JOB-TOKEN: ${CI_JOB_TOKEN}" --output image.tar.gz "${PACKAGE_URL}/image.tar.gz"'
    - ./run-tests.sh image.tar.gz

cleanup:
  stage: .post
  when: always
  allow_failure: true
  image: alpine:latest
  before_script:
    - apk add --no-cache curl jq
  script:
    - 'PACKAGE_ID=$(curl --fail --header "JOB-TOKEN: ${CI_JOB_TOKEN}" "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages?package_type=generic&package_name=pipeline-handoff&package_version=${CI_PIPELINE_ID}" | jq ".[0].id")'
    - 'curl --fail --request DELETE --header "JOB-TOKEN: ${CI_JOB_TOKEN}" "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/${PACKAGE_ID}"'

cleanup job은 CI_JOB_TOKEN을 사용해 패키지를 삭제합니다. 패키지를 삭제하려면 Maintainer 또는 Owner 권한이 필요합니다. Developer 권한을 가진 사용자가 파이프라인을 실행하면 cleanup job이 실패하고 패키지는 레지스트리에 남습니다. allow_failure: true는 이 실패로 파이프라인이 실패하지 않도록 합니다.

패키지 스토리지는 네임스페이스 스토리지에 포함됩니다.

Job 아티팩트 생성#

job 아티팩트를 생성하려면 .gitlab-ci.yml 파일에서 artifacts 키워드를 사용합니다.

pdf:
  script: xelatex mycv.tex
  artifacts:
    paths:
      - mycv.pdf

이 예시에서는 pdf라는 이름의 job이 xelatex 명령을 호출하여 LaTeX 소스 파일인 mycv.tex로부터 PDF 파일을 빌드합니다.

paths 키워드는 job 아티팩트에 추가할 파일을 결정합니다. 파일과 디렉터리의 모든 경로는 job이 생성된 리포지터리를 기준으로 한 상대 경로입니다.

와일드카드 사용#

경로와 디렉터리에 와일드카드를 사용할 수 있습니다. 예를 들어 xyz로 끝나는 디렉터리 안의 모든 파일을 포함하는 아티팩트를 생성하려면 다음과 같이 작성합니다.

job:
  script: echo "build xyz project"
  artifacts:
    paths:
      - path/*xyz/*

만료 기간 설정#

expire_in 키워드는 GitLab이 artifacts:paths에 정의된 아티팩트를 보관하는 기간을 결정합니다. 예를 들면 다음과 같습니다.

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

expire_in이 정의되지 않은 경우 기본 아티팩트 만료 인스턴스 설정이 사용됩니다.

아티팩트가 만료되지 않게 하려면 job 세부 정보 페이지에서 Keep을 선택할 수 있습니다. 아티팩트에 만료 기간이 설정되어 있지 않으면 이 옵션을 사용할 수 없습니다.

기본적으로 각 ref에서 가장 최근에 완료된 파이프라인과 가장 최근에 성공한 파이프라인의 아티팩트는 expire_in과 관계없이 보관됩니다.

아티팩트 이름 명시적으로 지정하기#

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는 자체 내부 변수 확장 메커니즘을 사용합니다. 이 컨텍스트에서는 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를 사용합니다.

변수는 글롭보다 먼저 확장됩니다.

업로드 조건 설정#

기본적으로 아티팩트는 job이 성공했을 때만(on_success) 업로드됩니다. job이 실패했을 때만 업로드하려면 artifacts:when: on_failure를, job 상태와 관계없이 업로드하려면 artifacts:when: always를 사용합니다.

예를 들어 빌드가 실패했을 때만 빌드 로그를 저장하려면 다음과 같이 작성합니다.

build:
  script: make build > build.log 2>&1
  artifacts:
    when: on_failure
    paths:
      - build.log

아티팩트 가져오기#

기본적으로 job은 이전 Stage에 정의된 job의 모든 아티팩트를 가져옵니다. 이 아티팩트는 job의 작업 디렉터리로 다운로드됩니다.

dependencies 또는 needs:artifacts 키워드를 사용하면 다운로드할 아티팩트를 제어할 수 있습니다.

이 키워드를 사용하면 기본 동작이 변경되어 지정한 job에서만 아티팩트를 가져옵니다.

job이 아티팩트를 가져오지 않게 하기#

job이 어떤 아티팩트도 다운로드하지 않게 하려면 dependencies를 빈 배열([])로 설정합니다.

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

프로젝트의 모든 job 아티팩트 보기#

Build > Artifacts 페이지에서 프로젝트에 저장된 모든 아티팩트를 볼 수 있습니다. 이 목록에는 모든 job과 관련 아티팩트가 표시됩니다. 항목을 펼치면 다음을 포함하여 job과 관련된 모든 아티팩트에 접근할 수 있습니다.

• artifacts: 키워드로 생성된 아티팩트
• 리포트 아티팩트
• job 로그 및 메타데이터(내부적으로 별도 아티팩트로 저장됨)

이 목록에서 개별 아티팩트를 다운로드하거나 삭제할 수 있습니다.

job 아티팩트 다운로드#

GitLab UI 또는 API를 통해 job 아티팩트를 다운로드할 수 있습니다. API를 사용하려면 공개적으로 접근 가능한 URL을 사용하며, 최신 아티팩트를 가져오려면 job 이름과 브랜치를, 특정 리포트를 지정하려면 job ID를 사용합니다.

GitLab UI에서:

job 아티팩트를 다운로드할 수 있는 사용자를 제한하려면 .gitlab-ci.yml 파일에서 artifacts:access 키워드를 사용합니다. 예를 들면 다음과 같습니다.

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

job 이름과 브랜치로 다운로드하기#

job ID를 먼저 조회할 필요 없이 job의 이름과 브랜치를 사용하여 최신 아티팩트 아카이브를 다운로드할 수 있습니다.

예를 들어 GitLab.com의 한 프로젝트에서 main 브랜치에 있는 build라는 이름의 job의 최신 아티팩트를 다운로드하려면 다음과 같이 작성합니다.

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는 프로젝트 개요 페이지에서 확인할 수 있습니다.

부모 파이프라인과 자식 파이프라인의 아티팩트는 부모에서 자식 순으로 계층적으로 검색됩니다. 예를 들어 부모 파이프라인과 자식 파이프라인 모두에 같은 이름의 job이 있으면 부모 파이프라인의 job 아티팩트가 반환됩니다.

job ID로 다운로드하기#

리포트 아티팩트(예: JUnit 테스트 결과)는 job 이름과 브랜치로 다운로드하는 아티팩트 아카이브에 포함되지 않습니다. 리포트 파일을 다운로드하려면 job ID를 사용하고 URL에 file_type을 추가합니다.

https://gitlab.com/api/v4/projects/<project-id>/jobs/<job-id>/artifacts?file_type=junit

GitLab은 러너가 업로드한 형식 그대로 리포트를 제공하며, 이 형식은 리포트 종류에 따라 다릅니다.

CI/CD job 토큰 사용하기#

CI/CD job 토큰을 사용하여 job 아티팩트 API 엔드포인트에 인증하고 다른 파이프라인에서 아티팩트를 가져올 수 있습니다. 어느 job에서 아티팩트를 가져올지 지정해야 합니다. 예를 들면 다음과 같습니다.

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

같은 파이프라인 내의 job에서 아티팩트를 가져오려면 needs:artifacts 키워드를 사용합니다.

아티팩트 아카이브의 콘텐츠 탐색#

로컬에 아티팩트를 다운로드하지 않고도 UI에서 아티팩트의 콘텐츠를 다음 위치에서 탐색할 수 있습니다.

• 아무 Jobs 목록. job 오른쪽에서 Browse([folder-open])를 선택합니다.
• job의 세부 정보 페이지. 페이지 오른쪽에서 Browse를 선택합니다.
• Artifacts 페이지. job 오른쪽에서 Browse([folder-open])를 선택합니다.

GitLab Pages가 전역적으로 활성화되어 있으면 프로젝트 설정에서 비활성화되어 있더라도 일부 아티팩트 파일 확장자를 브라우저에서 바로 미리 볼 수 있습니다. 프로젝트가 내부용이거나 비공개인 경우 관리자가 인스턴스에 대해 GitLab Pages 접근 제어도 켜야 합니다.

다음 확장자를 지원합니다.

URL로 아티팩트 탐색하기#

공개적으로 접근 가능한 URL을 사용하여 특정 job의 가장 최근에 성공한 파이프라인의 job 아티팩트를 탐색할 수 있습니다.

예를 들어 GitLab.com의 한 프로젝트에서 main 브랜치에 있는 build라는 이름의 job의 최신 아티팩트를 탐색하려면 다음과 같이 작성합니다.

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

<full-project-path>를 유효한 프로젝트 경로로 바꾸세요. 이는 프로젝트 URL에서 확인할 수 있습니다.

최대 아티팩트 크기 설정#

저장 공간 사용량을 제어하려면 job 아티팩트의 크기 제한을 설정합니다. job의 각 아티팩트 파일은 기본적으로 최대 100MB까지 허용됩니다.

다음 대상에 대해 아티팩트 크기 제한을 구성할 수 있습니다.

• 인스턴스: 모든 프로젝트와 그룹에 적용되는 기본 설정입니다.
• 그룹: 그룹 내 모든 프로젝트에 대해 인스턴스 설정을 재정의합니다.
• 프로젝트: 특정 프로젝트에 대해 인스턴스 설정과 그룹 설정을 모두 재정의합니다.

그룹 또는 프로젝트의 최대 아티팩트 크기를 변경하려면 다음과 같이 합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. General pipelines를 확장합니다.
4. Maximum artifacts size 값(MB 단위)을 변경합니다.
5. Save changes를 선택합니다.

job 로그와 아티팩트 삭제#

job의 아티팩트와 로그를 삭제할 수 있습니다.

사전 요구 사항:

• job의 소유자이거나 프로젝트에 대해 Maintainer 또는 Owner 권한을 가진 사용자여야 합니다.

job을 삭제하려면 다음과 같이 합니다.

1. job의 세부 정보 페이지로 이동합니다.
2. job 로그의 오른쪽 상단에서 Erase job log and artifacts([remove])를 선택합니다.

Artifacts 페이지에서 개별 아티팩트를 삭제할 수도 있습니다.

아티팩트 일괄 삭제#

여러 아티팩트를 한 번에 삭제할 수 있습니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Build > Artifacts를 선택합니다.
3. 삭제할 아티팩트 옆의 체크박스를 선택합니다. 최대 100개의 아티팩트를 선택할 수 있습니다.
4. Delete selected를 선택합니다.

머지 리퀘스트 UI에서 job 아티팩트에 링크하기#

artifacts:expose_as 키워드를 사용하면 머지 리퀘스트 UI에서 아티팩트에 직접 접근할 수 있습니다.

예를 들어 파일 하나로 구성된 아티팩트의 경우 다음과 같이 작성합니다.

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

이 설정을 사용하면 View exposed artifact 섹션에 artifact 1이라는 레이블이 붙은 file.txt 링크가 표시됩니다.

가장 최근에 성공한 job의 아티팩트 보관#

기본적으로 각 Git ref(브랜치 또는 태그)에 대해 GitLab은 다음의 아티팩트를 보관합니다.

• ref의 최신 파이프라인. 실패했거나 수동 job에 의해 차단된 경우도 포함합니다.
• 최신 파이프라인과 다르다면 가장 최근에 성공한 파이프라인.

expire_in 설정은 이러한 아티팩트에 적용되지 않습니다.

같은 ref에서 더 오래된 다른 파이프라인의 아티팩트는 해당 ref의 더 새로운 파이프라인이 다음 중 하나에 해당할 때 만료되기 시작합니다.

• 성공한 경우.
• 실패한 경우.
• 취소된 경우.
• 건너뛴 경우.
• 수동 job에 의해 차단된 경우.

예를 들어 브랜치의 최신 파이프라인이 실패하면 GitLab은 마지막으로 성공한 파이프라인의 아티팩트와 함께 그 파이프라인의 아티팩트도 보관합니다.

최신 아티팩트를 보관하면 job이 많거나 아티팩트가 큰 프로젝트에서 저장 공간을 많이 사용할 수 있습니다. 프로젝트에서 최신 아티팩트가 필요하지 않다면 이 동작을 비활성화하여 공간을 절약할 수 있습니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Artifacts를 확장합니다.
4. Keep artifacts from most recent successful jobs 체크박스를 해제합니다.

이 설정을 비활성화하면 모든 새 아티팩트는 expire_in 설정에 따라 만료됩니다. 이전 파이프라인의 아티팩트는 같은 ref에 대해 새 파이프라인이 실행될 때까지 계속 보관됩니다. 그 이후에는 해당 ref의 이전 파이프라인 아티팩트도 만료될 수 있습니다.

GitLab Self-Managed에서는 Keep artifacts from latest successful pipelines 인스턴스 설정으로 모든 프로젝트에 대해 이 동작을 비활성화할 수 있습니다.

관련 주제#

• dotenv 리포트 아티팩트로 job 간에 환경 변수 전달하기