잡은 파일 및 디렉토리의 아카이브를 출력할 수 있습니다. 이 출력을 잡 아티팩트라고 합니다. 아티팩트에는 빌드 출력 또는 보고서 파일이 포함될 수 있습니다. 기본적으로 이후 잡은 이전 스테이지의 모든 잡에서 아티팩트 사본을 가져옵니다.

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

artifacts 키워드에 대한 지원되는 전체 구성 목록은 GitLab CI/CD YAML 구문 참조를 참조하세요.

관련 항목:

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

잡 아티팩트 생성#

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

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

이 예시에서 pdf라는 잡이 xelatex 명령을 호출하여 LaTeX 소스 파일 mycv.tex에서 PDF 파일을 빌드합니다.

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

와일드카드 사용#

경로 및 디렉토리에 와일드카드를 사용할 수 있습니다. 예를 들어 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이 정의되지 않은 경우 Default artifacts expiration 인스턴스 설정이 사용됩니다.

아티팩트가 만료되지 않도록 하려면 잡 세부 정보 페이지에서 Keep을 선택할 수 있습니다. 아티팩트에 만료 기한이 설정되지 않은 경우에는 이 옵션을 사용할 수 없습니다.

기본적으로 아티팩트는 각 ref의 가장 최근 성공한 파이프라인에 대해 항상 보관됩니다.

명시적으로 정의된 아티팩트 이름 사용#

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를 사용하세요.

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

아티팩트 가져오기#

기본적으로 잡은 이전 스테이지에 정의된 잡의 모든 아티팩트를 가져옵니다. 이러한 아티팩트는 잡의 작업 디렉토리로 다운로드됩니다.

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

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

잡이 아티팩트를 가져오는 것 방지#

잡이 아티팩트를 다운로드하지 못하게 하려면 dependencies를 빈 배열([])로 설정합니다:

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

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

히스토리

• GitLab 16.0에서 일반 제공. 기능 플래그 artifacts_management_page 제거.

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

• artifacts: 키워드로 생성된 아티팩트.
• 보고서 아티팩트.
• 별도의 아티팩트로 내부적으로 저장되는 잡 로그 및 메타데이터.

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

잡 아티팩트 다운로드#

GitLab UI 또는 API를 사용하여 잡 아티팩트를 다운로드할 수 있습니다.

GitLab UI에서 다음 위치에서 잡 아티팩트를 다운로드할 수 있습니다:

• 모든 Pipelines 목록. 파이프라인 오른쪽에서 Download artifacts ([download])를 선택합니다.
• 모든 Jobs 목록. 잡 오른쪽에서 Download artifacts ([download])를 선택합니다.
• 잡의 세부 정보 페이지. 페이지 오른쪽에서 Download를 선택합니다.
• 머지 리퀘스트 Overview 페이지. 최신 파이프라인 오른쪽에서 Artifacts ([download])를 선택합니다.
• Artifacts 페이지. 잡 오른쪽에서 Download ([download])를 선택합니다.
• 아티팩트 브라우저. 페이지 상단에서 Download artifacts archive ([download])를 선택합니다.

보고서 아티팩트는 Pipelines 목록 또는 Artifacts 페이지에서만 다운로드할 수 있습니다.

URL에서#

공개적으로 접근 가능한 URL로 특정 잡의 아티팩트 아카이브를 다운로드할 수 있습니다.

예를 들어 GitLab.com의 프로젝트 main 브랜치의 build라는 잡의 최신 아티팩트를 다운로드하려면:

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

부모 및 자식 파이프라인의 아티팩트는 부모에서 자식으로 계층적 순서로 검색됩니다. 예를 들어 부모 및 자식 파이프라인 모두에 동일한 이름의 잡이 있는 경우 부모 파이프라인의 잡 아티팩트가 반환됩니다.

CI/CD 잡 토큰 사용#

CI/CD 잡 토큰을 사용하여 잡 아티팩트 API 엔드포인트에 인증하고 다른 파이프라인에서 아티팩트를 가져올 수 있습니다. 어떤 잡에서 아티팩트를 검색할지 지정해야 합니다. 예를 들어:

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

동일한 파이프라인의 잡에서 아티팩트를 가져오려면 needs:artifacts 키워드를 사용합니다.

아티팩트 다운로드 제어#

잡 아티팩트를 다운로드할 수 있는 사람을 제한하려면 .gitlab-ci.yml 파일에서 artifacts:access 키워드를 사용합니다. 예를 들어:

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

아티팩트 아카이브의 내용 탐색#

아티팩트를 로컬로 다운로드하지 않고도 UI에서 아티팩트의 내용을 탐색할 수 있습니다. 다음에서 가능합니다:

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

GitLab Pages가 전역적으로 활성화된 경우 프로젝트 설정에서 비활성화되어 있더라도, 일부 아티팩트 파일 확장자를 브라우저에서 직접 미리 볼 수 있습니다. 프로젝트가 내부 또는 비공개인 경우 미리 보기를 활성화하려면 GitLab Pages 접근 제어를 활성화해야 합니다.

지원되는 확장자:

URL에서#

공개적으로 접근 가능한 URL로 특정 잡의 최신 성공한 파이프라인의 잡 아티팩트를 탐색할 수 있습니다.

예를 들어 GitLab.com의 프로젝트 main 브랜치의 build라는 잡의 최신 아티팩트를 탐색하려면:

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

<full-project-path>를 유효한 프로젝트 경로로 교체합니다. 프로젝트 URL에서 찾을 수 있습니다.

잡 로그 및 아티팩트 삭제#

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

사전 조건:

• 잡의 소유자이거나 프로젝트에 대한 Maintainer 또는 Owner 역할의 사용자여야 합니다.

잡을 삭제하려면:

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

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

아티팩트 일괄 삭제#

히스토리

• GitLab 15.10에서 ci_job_artifact_bulk_destroy라는 플래그와 함께 도입. 기본적으로 비활성화됨.
• GitLab 16.1에서 일반 제공. 기능 플래그 ci_job_artifact_bulk_destroy 제거.

여러 아티팩트를 동시에 삭제할 수 있습니다:

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

머지 리퀘스트 UI에서 잡 아티팩트에 링크#

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 링크가 표시됩니다.

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

히스토리

• GitLab 16.7에서 차단된 또는 실패한 파이프라인의 아티팩트가 더 이상 무기한 보관되지 않도록 변경.

기본적으로 아티팩트는 각 ref의 가장 최근 성공한 파이프라인에 대해 항상 보관됩니다. 어떤 expire_in 구성도 가장 최근 아티팩트에 적용되지 않습니다.

동일한 ref에서 새 파이프라인이 성공적으로 완료되면 이전 파이프라인의 아티팩트는 expire_in 구성에 따라 삭제됩니다. 새 파이프라인의 아티팩트는 자동으로 보관됩니다.

파이프라인의 아티팩트는 동일한 ref에 대해 새 파이프라인이 실행되고 다음과 같은 경우에만 expire_in 구성에 따라 삭제됩니다:

• 성공.
• 수동 잡으로 인해 차단되어 중지.

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

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
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 인스턴스 설정을 사용합니다.

GitLab Self-Managed에서 모든 프로젝트에 대해 이 동작을 비활성화할 수 있습니다. 인스턴스의 CI/CD 설정에서 비활성화합니다.

관련 항목#

• dotenv 리포트 아티팩트를 사용하여 잡 간 환경 변수 전달