작업 아티팩트

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라는 작업은 xelatex 명령을 호출하여 LaTeX 소스 파일인 mycv.tex에서 PDF 파일을 빌드합니다.

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 배치를 사용하여 셸 스크립트를 실행하는 경우 $를 %로 바꿔야 합니다:

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: []

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

GitLab 12.4에서 도입. 기본 설정으로 비활성화된 artifacts_management_page라는 플래그와 함께.
GitLab 15.6에서 개선된 모양.
GitLab 15.9에서 성능 향상.
GitLab 16.0에서 일반적으로 사용 가능. artifacts_management_page 피처 플래그가 제거됨.

빌드 > 아티팩트 페이지에서 프로젝트에 저장된 모든 아티팩트를 볼 수 있습니다. 이 디렉터리에는 모든 작업과 해당 아티팩트가 표시됩니다. 항목을 확장하여 작업과 관련된 모든 아티팩트에 액세스할 수 있고, 이는 다음을 포함합니다:

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

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

작업 아티팩트 다운로드

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

모든 파이프라인 디렉터리. 파이프라인의 오른쪽에서 아티팩트 다운로드를 선택합니다 ().
모든 작업 디렉터리. 작업의 오른쪽에서 아티팩트 다운로드를 선택합니다 ().
작업의 세부 정보 페이지. 페이지의 오른쪽에서 다운로드를 선택합니다.
Merge Request 개요 페이지. 최신 파이프라인의 오른쪽에서 아티팩트를 선택합니다 ().
아티팩트 페이지. 작업의 오른쪽에서 다운로드를 선택합니다 ().
아티팩트 브라우저. 페이지 상단에서 아티팩트 아카이브 다운로드를 선택합니다 ().

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

작업 아티팩트 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 Dedicated

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에서 아티팩트의 내용을 탐색할 수 있습니다.

모든 작업 디렉터리. 작업의 오른쪽에서 탐색을 선택합니다 ().
작업의 세부 정보 페이지. 페이지의 오른쪽에서 탐색을 선택합니다.
아티팩트 페이지. 작업의 오른쪽에서 탐색을 선택합니다 ().

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

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

파일 확장자	GitLab.com	빌트인 NGINX가 있는 Linux 패키지
`.html`	가능	가능
`.json`	가능	가능
`.xml`	가능	가능
`.txt`	불가능	가능
`.log`	불가능	가능

URL을 통한 탐색

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

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

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

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

작업 로그 및 아티팩트 삭제

작업 로그와 아티팩트를 삭제하는 것은 되돌릴 수 없는 파괴적인 작업입니다. 주의해서 사용하세요. 보고서 아티팩트, 작업 로그 및 메타데이터 파일을 포함한 특정 파일을 삭제하는 것은 이러한 파일을 데이터 원본으로 사용하는 GitLab 기능에 영향을 미칩니다.

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

전제 조건:

작업의 소유자이거나 프로젝트에 대해 최소한의 Maintainer 권한이 있는 사용자여야 합니다.

작업을 삭제하려면:

작업의 세부 정보 페이지로 이동합니다.
작업 로그의 오른쪽 상단에서 작업 로그 및 아티팩트 지우기를 선택합니다 ().

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

일괄 아티팩트 삭제

GitLab 15.10에서 도입됨 ci_job_artifact_bulk_destroy라는 플래그로 기본값은 비활성화됨.
GitLab 16.1에서 피처 플래그 삭제.

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

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

Merge Request UI에서 작업 아티팩트로 이동하는 링크

merge request UI에서 작업 아티팩트로 이동하는 링크를 표시하려면 artifacts:expose_as 키워드를 사용합니다.

예를 들어, 하나의 파일에 대한 아티팩트의 경우:

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

이 구성을 사용하면 GitLab은 artifact 1을 관련된 Merge Request의 View exposed artifact 섹션에 있는 file.txt로 연결합니다.

최근 성공한 작업에서 아티팩트 유지하기

GitLab 13.0에서 도입됨.
GitLab 13.4에서 피처 플래그가 제거됨.
GitLab 13.8에서 CI/CD 설정으로 선택 사항으로 제공됨.
GitLab 16.7에서 더는 GitLab에서 성공하지 못한 또는 차단된 파이프라인의 아티팩트를 영구히 유지하지 않음.

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

파이프라인의 아티팩트는 다음 조건을 충족할 때만 expire_in 구성에 따라 삭제됩니다.

성공합니다.
실패합니다.
매뉴얼 작업에 의해 차단될 때 실행을 멈춥니다.

추가로, 최근의 아티팩트는 최신 파이프라인이 아니더라도 ref의 마지막 성공한 파이프라인의 아티팩트는 여전히 유지됩니다. 결과적으로, 새로운 파이프라인 실행이 실패하는 경우 마지막 성공한 파이프라인의 아티팩트는 여전히 유지됩니다.

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

왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
설정 > CI/CD를 선택합니다.
Artifacts를 확장합니다.
Keep artifacts from most recent successful jobs 확인란을 선택 해제합니다.

이 설정을 비활성화한 후 모든 새로운 아티팩트는 expire_in 구성에 따라 만료됩니다. 이전 파이프라인의 아티팩트는 동일한 ref에 대해 새로운 파이프라인이 실행될 때까지 계속 유지됩니다. 그런 다음 해당 ref에 대한 이전 파이프라인의 아티팩트도 만료됩니다.

모든 프로젝트에서 이 동작을 비활성화하려면 스스로 관리하는 인스턴스의 인스턴스의 CI/CD 설정에서 이 동작을 비활성화할 수 있습니다.

작업 아티팩트

작업 아티팩트 생성

와일드카드 사용

만료 기간 설정

동적으로 정의된 이름 사용

Windows 러너 또는 셸 실행기 사용

제외 파일 없이

추적되지 않은 파일로

작업에서 아티팩트 다운로드 방지

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

작업 아티팩트 다운로드

URL을 통한 다운로드

CI/CD 작업 토큰으로

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

URL을 통한 탐색

작업 로그 및 아티팩트 삭제

일괄 아티팩트 삭제

Merge Request UI에서 작업 아티팩트로 이동하는 링크

최근 성공한 작업에서 아티팩트 유지하기

도움말

기능 사용 가능성과 제품 평가판

도움받기