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

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

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

관련 항목:

• Job 아티팩트 API

• Job 아티팩트 관리

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이 정의되지 않은 경우 Default artifacts expiration 인스턴스 설정이 사용됩니다.

아티팩트가 만료되지 않도록 하려면 job 세부 정보 페이지에서 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를 사용하세요.

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

아티팩트 가져오기#

기본적으로 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 아티팩트를 다운로드할 수 있습니다.

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

• 모든 Pipelines 목록. 파이프라인 오른쪽에서 Download artifacts ([download])를 선택합니다.

• 모든 Jobs 목록. job 오른쪽에서 Download artifacts ([download])를 선택합니다.

• job의 세부 정보 페이지. 페이지 오른쪽에서 Download를 선택합니다.

• 머지 리퀘스트 Overview 페이지. 최신 파이프라인 오른쪽에서 Artifacts ([download])를 선택합니다.

• Artifacts 페이지. job 오른쪽에서 Download ([download])를 선택합니다.

• 아티팩트 브라우저. 페이지 상단에서 Download artifacts archive ([download])를 선택합니다.

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

URL에서#

공개적으로 접근 가능한 URL로 특정 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 아티팩트가 반환됩니다.

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 키워드를 사용합니다.

아티팩트 다운로드 권한 제어#

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

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

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

아티팩트를 로컬로 다운로드하지 않고도 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 내 각 아티팩트 파일의 기본 최대 크기는 100 MB입니다.

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

• 인스턴스: 모든 프로젝트와 그룹에 적용되는 기본 설정.

• 그룹: 그룹 내 모든 프로젝트에 대한 인스턴스 설정을 재정의합니다.

• 프로젝트: 특정 프로젝트에 대한 인스턴스 및 그룹 설정을 모두 재정의합니다.

그룹 또는 프로젝트의 최대 아티팩트 크기를 변경하려면:

• 상단 바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.

• 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.

• General pipelines를 확장합니다.

• Maximum artifacts size 값(MB 단위)을 변경합니다.

• Save changes를 선택합니다.

Job 로그 및 아티팩트 삭제#

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

사전 조건:

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

job을 삭제하려면:

• job의 세부 정보 페이지로 이동합니다.

• job 로그의 오른쪽 상단에서 Erase job log and artifacts ([remove])를 선택합니다.

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

아티팩트 일괄 삭제#

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

• 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.

• 왼쪽 사이드바에서 Build > Artifacts를 선택합니다.

• 삭제하려는 아티팩트 옆의 체크박스를 선택합니다. 최대 100개의 아티팩트를 선택할 수 있습니다.

• 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에서 아티팩트 보관#

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

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

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

• 성공.

• 수동 job으로 인해 차단되어 중지.

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

• 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.

• 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.

• Artifacts를 확장합니다.

• 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 보고서 아티팩트를 사용하여 job 간 환경 변수 전달