작업 아티팩트

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

작업은 파일과 디렉토리의 아카이브를 출력할 수 있습니다. 이 출력물을 작업 아티팩트라고 합니다.

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

작업 아티팩트 개요는 GitLab CI 파이프라인, 아티팩트 및 환경 동영상을 시청하세요. 또는 초보자를 위한 GitLab CI 파이프라인 튜토리얼을 시청하세요.

작업 아티팩트 저장에 대한 관리자 정보는 작업 아티팩트 관리를 참조하십시오.

작업 아티팩트 생성

작업 아티팩트를 생성하려면 .gitlab-ci.yml 파일에서 artifacts 키워드를 사용하십시오: 

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

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

paths 키워드는 작업 아티팩트에 추가할 파일을 결정합니다. 모든 파일과 디렉토리의 경로는 작업이 생성된 저장소를 기준으로 상대적입니다.

와일드카드 사용

경로와 디렉토리에 와일드카드를 사용할 수 있습니다. 예를 들어 xyz로 끝나는 디렉토리 내의 모든 파일로 아티팩트를 생성하려면: 

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

만료일 지정

expire_in 키워드는 GitLab이 작업 아티팩트를 유지하는 기간을 결정합니다. 예를 들어: 

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

expire_in이 정의되지 않은 경우 인스턴스 전체 설정이 사용됩니다.

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

기본적으로 최신 아티팩트는 항상 유지됩니다.

동적으로 정의된 이름으로

CI/CD 변수를 사용하여 아티팩트 파일의 이름을 동적으로 정의할 수 있습니다.

예를 들어, 현재 작업의 이름으로 아카이브를 생성하려면: 

job:
  artifacts:
    name: "$CI_JOB_NAME"
    paths:
      - binaries/

현재 브랜치나 태그의 이름으로 바이너리 디렉토리만 포함한 아카이브를 생성하려면: 

job:
  artifacts:
    name: "$CI_COMMIT_REF_NAME"
    paths:
      - binaries/

브랜치 이름에 슬래시가 포함된 경우(예: feature/my-feature) 아티팩트의 이름을 올바르게 정의하려면 $CI_COMMIT_REF_NAME 대신 $CI_COMMIT_REF_SLUG를 사용하십시오.

Windows 러너 또는 쉘 실행기로

Windows Batch로 쉘 스크립트를 실행하는 경우 $를 %로 대체해야 합니다: 

job:
  artifacts:
    name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%"
    paths:
      - binaries/

Windows PowerShell로 쉘 스크립트를 실행하는 경우 $를 $env:로 대체해야 합니다: 

job:
  artifacts:
    name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME"
    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을 사용하여 Git에 추적되지 않은 모든 파일을 (그리고 artifacts:paths에 정의된 경로와 함께) 아티팩트로 추가할 수 있습니다. 추적되지 않은 파일이란 저장소에 추가되지 않았지만 저장소 체크아웃에 있는 파일을 의미합니다.

예를 들어, 모든 Git 추적되지 않은 파일과 binaries 파일을 저장하려면: 

artifacts:
  untracked: true
  paths:
    - binaries/

예를 들어, 모든 추적되지 않은 파일을 저장하지만 *.txt 파일은 제외하려면: 

artifacts:
  untracked: true
  exclude:
    - "*.txt"

작업에서 아티팩트 가져오지 않도록 하기

기본적으로 작업은 이전 단계에서 완료된 작업에서 모든 아티팩트를 다운로드합니다. 어떠한 아티팩트도 다운로드하지 않도록 하려면 dependencies를 빈 배열([])로 설정하세요: 

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

프로젝트에서 모든 작업 아티팩트 보기

프로젝트에 저장된 모든 아티팩트를 빌드 > 아티팩트 페이지에서 볼 수 있습니다. 이 목록에는 모든 작업과 해당하는 아티팩트가 표시됩니다. 항목을 확장하여 작업과 관련된 모든 아티팩트에 접근할 수 있습니다. 이 아티팩트에는 artifacts: 키워드로 생성된 아티팩트, 보고서 아티팩트, 작업 로그 및 메타데이터가 포함됩니다.

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

작업 아티팩트 다운로드

다음에서 작업 아티팩트를 다운로드할 수 있습니다:

  • 아무 파이프라인 목록에서. 파이프라인 오른쪽에서 아티팩트 다운로드 ()를 선택하세요.
  • 아무 작업 목록에서. 작업 오른쪽에서 아티팩트 다운로드 ()를 선택하세요.
  • 작업 세부 페이지에서. 페이지 오른쪽에서 다운로드를 선택하세요.
  • 병합 요청 개요 페이지에서. 최신 파이프라인 오른쪽에서 아티팩트 ()를 선택하세요.
  • 아티팩트 페이지에서. 작업 오른쪽에서 다운로드 ()를 선택하세요.
  • 아티팩트 브라우저에서. 페이지 상단에서 아티팩트 아카이브 다운로드 ()를 선택하세요.

보고서 아티팩트는 파이프라인 목록이나 아티팩트 페이지에서만 다운로드할 수 있습니다.

최신 성공한 파이프라인에서 작업 아티팩트 API를 사용하여 작업 아티팩트를 다운로드할 수 있습니다. 아티팩트 보고서는 artifacts:paths로 보고서를 항상 아티팩트로 추가하지 않는 이상 작업 아티팩트 API로 다운로드할 수 없습니다.

URL을 통해

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

예를들어:

  • GitLab.com의 프로젝트의 main 브랜치에서 build라는 이름의 작업의 최신 아티팩트를 다운로드하려면: 

    https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/download?job=build

  • GitLab.com의 프로젝트의 main 브랜치에서 가장 최근에 있는 build라는 이름의 작업에서 review/index.html 파일을 다운로드하려면: 

    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 작업 토큰을 사용하여

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab 전용

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

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

아티팩트 아카이브 내용 검색

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

  • 모든 작업 목록에서. 작업 옆에 오른쪽에서 찾아보기 ()를 선택합니다.
  • 작업의 상세 페이지. 페이지 오른쪽에서 찾아보기를 선택합니다.
  • 아티팩트 페이지. 작업 오른쪽에서 찾아보기 ()를 선택합니다.

프로젝트에서 GitLab Pages가 활성화되어 있다면, 브라우저에서 일부 아티팩트 파일 확장자를 직접 미리볼 수 있습니다. 프로젝트가 내부 또는 비공개인 경우 GitLab Pages 액세스 제어를 활성화하여 미리볼 수 있도록 설정해야 합니다.

다음 확장자가 지원됩니다:

파일 확장자 GitLab.com 내장된 NGINX가 포함된 Linux 패키지
.html Yes Yes
.json Yes Yes
.xml Yes Yes
.txt No Yes
.log No Yes

URL에서

URL을 통해 특정 작업의 최신 성공한 파이프라인의 작업 아티팩트를 검색할 수 있습니다.

예를 들어, GitLab.com의 프로젝트에서 main 브랜치의 build라는 작업의 최신 아티팩트를 검색하려면: 

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

<full-project-path>를 유효한 프로젝트 경로로 대체하면 됩니다. 프로젝트의 URL로 찾을 수 있습니다.

작업 로그와 아티팩트 삭제

경고: 작업 로그와 아티팩트를 삭제하는 것은 되돌릴 수 없는 파괴적인 작업입니다. 신중하게 사용하십시오. 보고 아티팩트, 작업 로그 및 메타데이터 파일을 포함한 특정 파일을 삭제하는 것은 이러한 파일을 데이터 소스로 사용하는 GitLab 기능에 영향을 미칩니다.

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

전제 조건:

  • 작업의 소유자이거나 프로젝트에 대한 Maintainer 역할 이상의 사용자여야 합니다.

작업 삭제:

  1. 작업 상세 페이지로 이동합니다.
  2. 작업 로그의 오른쪽 상단에 작업 로그와 아티팩트 지우기를 선택합니다().

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

다중 아티팩트 일괄 삭제

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

  1. 왼쪽 사이드바에서 검색 또는 이동하여 찾기를 선택하여 프로젝트를 찾습니다.
  2. 빌드 > 아티팩트를 선택합니다.
  3. 삭제하려는 아티팩트 옆의 확인란을 선택합니다. 최대 50개까지 선택할 수 있습니다.
  4. 선택한 항목 삭제를 선택합니다.

병합 요청 UI에서 작업 아티팩트로 연결

artifacts:expose_as 키워드를 사용하여 병합 요청 UI에서 작업 아티팩트에 연결을 표시합니다.

예를 들어, 하나의 파일을 가진 아티팩트를 위해: 

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

이 구성으로 인해 GitLab에서는 관련된 병합 요청의 공개된 아티팩트 보기 섹션에 file.txt에 대한 artifact 1링크가 추가됩니다.

가장 최근 성공한 작업의 아티팩트 유지

  • GitLab 13.0.에 도입.
  • GitLab 13.4.에서 피처 플래그 삭제.
  • GitLab 13.8.에서 CI/CD 설정을 사용하여 선택적으로 제공됨.
  • GitLab 16.7.에서 블록되거나 실패한 파이프라인에 대한 아티팩트는 더 이상 무기한 유지되지 않음.

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

파이프라인의 아티팩트는 새 파이프라인이 동일한 참조에 대해 실행되는 경우에만 expire_in 구성에 따라 삭제됩니다.

  • 성공합니다.
  • 실패합니다.
  • 수동 작업으로 차단되어 실행이 중지됩니다.

추가로, 최신 파이프라인인지 여부와 상관없이 참조의 마지막 성공한 파이프라인의 아티팩트는 계속 유지됩니다. 결과적으로 새 파이프라인 실행이 실패하면, 해당 참조의 마지막 성공한 파이프라인의 아티팩트는 계속 유지됩니다.

최신 아티팩트를 유지하면 많은 작업이나 크기가 큰 아티팩트가 있는 프로젝트에서 많은 저장 공간을 사용할 수 있습니다. 최신 아티팩트가 프로젝트에 필요없는 경우, 이 동작을 비활성화하여 공간을 절약할 수 있습니다.

  1. 왼쪽 사이드바에서 검색 또는 이동하여 찾기를 선택하여 프로젝트를 찾습니다.
  2. 설정 > CI/CD를 선택합니다.
  3. 아티팩트를 확장합니다.
  4. 가장 최근 성공한 작업의 아티팩트 유지 확인란을 해제합니다.

이 설정을 비활성화한 후에 새 아티팩트는 모두 expire_in 구성에 따라 만료됩니다. 이전 파이프라인의 아티팩트는 같은 참조에 대해 새로운 파이프라인이 실행될 때까지 계속 유지됩니다. 그런 다음, 해당 참조의 이전 파이프라인의 아티팩트는 만료될 수 있습니다.

자체 관리 인스턴스의 모든 프로젝트에 대해 이 동작을 비활성화할 수 있습니다. 인스턴스의 CI/CD 설정에서 모든 최신 성공적인 파이프라인의 작업에 대한 최신 아티팩트 유지를 해제할 수 있습니다.