작업 아티팩트 관리

요약

이 문서는 관리자용 문서입니다. 아티팩트는 job 이 끝난 뒤 해당 job에 첨부되는 파일과 디렉터리의 목록입니다. 사이트 전체에서 아티팩트를 비활성화하는 방법은 다음과 같습니다. /etc/gitlab/gitlab.rb를 편집합니다.

이 문서는 관리자용 문서입니다. GitLab CI/CD 파이프라인에서 job 아티팩트를 사용하는 방법은 job 아티팩트 구성 문서를 참고합니다.

아티팩트는 job 이 끝난 뒤 해당 job에 첨부되는 파일과 디렉터리의 목록입니다. 이 기능은 모든 GitLab 설치에서 기본적으로 활성화되어 있습니다.

job 아티팩트 비활성화#

사이트 전체에서 아티팩트를 비활성화하는 방법은 다음과 같습니다.

/etc/gitlab/gitlab.rb를 편집합니다.

gitlab_rails['artifacts_enabled'] = false

파일을 저장하고 GitLab을 재구성합니다.
```
sudo gitlab-ctl reconfigure
```

Helm 값을 내보냅니다.

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml을 편집합니다.

global:
  appConfig:
    artifacts:
      enabled: false

파일을 저장하고 새 값을 적용합니다.

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

docker-compose.yml을 편집합니다.

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['artifacts_enabled'] = false

파일을 저장하고 GitLab을 재시작합니다.
```
docker compose up -d
```

/home/git/gitlab/config/gitlab.yml을 편집합니다.

production: &base
  artifacts:
    enabled: false

파일을 저장하고 GitLab을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

job 아티팩트 저장#

GitLab Runner는 job 아티팩트가 담긴 아카이브를 GitLab에 업로드할 수 있습니다. 기본적으로 job 이 성공했을 때 업로드하지만, artifacts:when 파라미터로 실패했을 때 또는 항상 업로드하도록 설정할 수도 있습니다.

대부분의 아티팩트는 코디네이터로 전송되기 전에 GitLab Runner가 압축합니다. 다만 reports 아티팩트는 업로드 후에 압축됩니다.

로컬 저장소 사용#

Linux 패키지를 사용하거나 직접 컴파일해 설치했다면 아티팩트가 로컬에 저장되는 위치를 변경할 수 있습니다.

Note

Docker 설치에서는 데이터를 마운트하는 경로를 변경할 수 있습니다. Helm chart에서는 오브젝트 스토리지를 사용합니다.

아티팩트는 기본적으로 /var/opt/gitlab/gitlab-rails/shared/artifacts에 저장됩니다.

저장 경로를 예를 들어 /mnt/storage/artifacts로 변경하려면 /etc/gitlab/gitlab.rb를 편집해 다음 줄을 추가합니다.
```
gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts"
```
파일을 저장하고 GitLab을 재구성합니다.
```
sudo gitlab-ctl reconfigure
```

아티팩트는 기본적으로 /home/git/gitlab/shared/artifacts에 저장됩니다.

저장 경로를 예를 들어 /mnt/storage/artifacts로 변경하려면 /home/git/gitlab/config/gitlab.yml을 편집해 다음 줄을 추가하거나 수정합니다.
```
production: &base
  artifacts:
    enabled: true
    path: /mnt/storage/artifacts
```

파일을 저장하고 GitLab을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

오브젝트 스토리지 사용#

아티팩트를 저장하는 데 GitLab 이 설치된 로컬 디스크를 사용하지 않으려면 AWS S3 같은 오브젝트 스토리지를 대신 사용할 수 있습니다.

아티팩트를 오브젝트 스토리지에 저장하도록 GitLab을 구성한다면 job 로그의 로컬 디스크 사용도 없애는 방안을 함께 검토합니다. 두 경우 모두 job 이 완료되면 job 로그가 아카이브되어 오브젝트 스토리지로 이동합니다.

Warning

다중 서버 구성에서는 job 로그의 로컬 디스크 사용을 없애는 옵션 중 하나를 반드시 사용해야 하며, 그렇지 않으면 job 로그가 유실될 수 있습니다.

통합 오브젝트 스토리지 설정을 사용하는 것이 좋습니다.

오브젝트 스토리지로 마이그레이션#

job 아티팩트를 로컬 저장소에서 오브젝트 스토리지로 마이그레이션할 수 있습니다. 처리는 백그라운드 워커에서 이루어지며 중단 시간이 필요하지 않습니다.

오브젝트 스토리지를 구성합니다.
아티팩트를 마이그레이션합니다.

   sudo gitlab-rake gitlab:artifacts:migrate

   sudo docker exec -t <container name> gitlab-rake gitlab:artifacts:migrate

   sudo -u git -H bundle exec rake gitlab:artifacts:migrate RAILS_ENV=production

선택 사항. PostgreSQL 콘솔로 진행 상황을 추적하고 모든 job 아티팩트가 정상적으로 마이그레이션되었는지 검증합니다.
1. PostgreSQL 콘솔을 엽니다.

      sudo gitlab-psql
      ```

</div>

<div class="tab-panel" data-tab-index="1">

```shell
      sudo docker exec -it <container_name> /bin/bash
      gitlab-psql
      ```

</div>

<div class="tab-panel" data-tab-index="2">

```shell
      sudo -u git -H psql -d gitlabhq_production
      ```

</div>

</div>

   1. 다음 SQL 쿼리로 모든 아티팩트가 오브젝트 스토리지로 마이그레이션되었는지
      검증합니다. `objectstg`의 수가 `total`과 같아야 합니다.

      ```shell
      gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM p_ci_job_artifacts;

      total | filesystem | objectstg
      ------+------------+-----------
         19 |          0 |        19
      ```

1. `artifacts` 디렉터리의 디스크에 파일이 남아 있지 않은지 확인합니다.

   <div class="tabs-container" data-tabs><div class="tabs-nav"><button class="tab-button active" data-tab-index="0">Linux package (Omnibus)</button><button class="tab-button" data-tab-index="1">Docker</button><button class="tab-button" data-tab-index="2">Self-compiled (source)</button></div><div class="tab-panel active" data-tab-index="0">

```shell
   sudo find /var/opt/gitlab/gitlab-rails/shared/artifacts -type f | grep -v tmp | wc -l

/var/opt/gitlab을 /srv/gitlab에 마운트했다고 가정합니다.

sudo find /srv/gitlab/gitlab-rails/shared/artifacts -type f | grep -v tmp | wc -l

   sudo find /home/git/gitlab/shared/artifacts -type f | grep -v tmp | wc -l

Geo가 활성화되어 있다면 모든 job 아티팩트를 다시 검증합니다.

경우에 따라 고아 아티팩트를 정리하려면 고아 아티팩트 파일 정리 Rake 태스크를 실행해야 합니다.

오브젝트 스토리지에서 로컬 저장소로 마이그레이션#

아티팩트를 로컬 저장소로 되돌리는 방법은 다음과 같습니다.

gitlab-rake gitlab:artifacts:migrate_to_local을 실행합니다.
gitlab.rb에서 아티팩트 저장소를 선택적으로 비활성화합니다.
GitLab을 재구성합니다.

GitLab 18.6 이전에는 원격에서 로컬 저장소로 마이그레이션할 때 아티팩트가 잘못된 파일 이름으로 복사될 수 있었습니다.

아티팩트 만료#

artifacts:expire_in으로 아티팩트의 만료 기한을 설정하면 그 날짜가 지난 직후에 삭제 대상으로 표시됩니다. 설정하지 않으면 기본 아티팩트 만료 설정에 따라 만료됩니다.

만료된 아티팩트는 30 분마다(Cron 구문으로 */30 * * * *) 실행되는 Ci::ScheduleBulkDeleteJobArtifactCronWorker Sidekiq cron job 이 삭제하며, 이 job은 삭제를 수행할 Ci::BulkDeleteExpiredJobArtifactsWorker를 큐에 넣습니다.

Geo 배포에서는 아티팩트를 만료시키면 보조 사이트의 스토리지 사용량과 Geo 동기화, 검증, 메트릭 수집 부하도 줄어듭니다. 자세한 내용은 복제되는 데이터 양 줄이기를 참고합니다.

아티팩트의 최대 파일 크기 설정#

아티팩트가 활성화되어 있으면 Admin 영역 설정에서 아티팩트의 최대 파일 크기를 변경할 수 있습니다.

저장소 통계#

그룹과 프로젝트의 job 아티팩트가 사용하는 전체 저장 용량을 볼 수 있습니다.

저장 용량을 가장 많이 사용하는 그룹이나 프로젝트를 확인하는 방법은 다음과 같습니다.

Admin 영역에서 Overview > Projects로 이동한 다음 Storage size로 정렬합니다.
groups API와 projects API로 각 그룹이나 프로젝트의 저장 용량 통계를 조회합니다.

구현 세부 사항#

GitLab 이 아티팩트 아카이브를 받으면 GitLab Workhorse가 아카이브 메타데이터 파일도 생성합니다. 이 메타데이터 파일은 아티팩트 아카이브 안에 있는 모든 항목을 기술합니다. 메타데이터 파일은 바이너리 형식이며 Gzip으로 추가 압축됩니다.

GitLab은 공간, 메모리, 디스크 I/O를 아끼기 위해 아티팩트 아카이브를 풀지 않습니다. 대신 관련 정보가 모두 들어 있는 메타데이터 파일을 확인합니다. 이는 아티팩트가 많거나 아카이브가 매우 큰 파일일 때 특히 중요합니다.

특정 파일을 선택하면 GitLab Workhorse가 아카이브에서 해당 파일을 추출하고 다운로드가 시작됩니다. 이 구현은 공간, 메모리, 디스크 I/O를 아낍니다.

작업 아티팩트 관리

GitLab v19.5

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

원문 보기

번역일: 2026-10-15

요약

이 문서는 관리자용 문서입니다. GitLab CI/CD 파이프라인에서 job 아티팩트를 사용하는 방법은 job 아티팩트 구성 문서를 참고합니다.

아티팩트는 job 이 끝난 뒤 해당 job에 첨부되는 파일과 디렉터리의 목록입니다. 이 기능은 모든 GitLab 설치에서 기본적으로 활성화되어 있습니다.

job 아티팩트 비활성화#

사이트 전체에서 아티팩트를 비활성화하는 방법은 다음과 같습니다.

/etc/gitlab/gitlab.rb를 편집합니다.

gitlab_rails['artifacts_enabled'] = false

파일을 저장하고 GitLab을 재구성합니다.
```
sudo gitlab-ctl reconfigure
```

Helm 값을 내보냅니다.

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml을 편집합니다.

global:
  appConfig:
    artifacts:
      enabled: false

파일을 저장하고 새 값을 적용합니다.

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

docker-compose.yml을 편집합니다.

version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['artifacts_enabled'] = false

파일을 저장하고 GitLab을 재시작합니다.
```
docker compose up -d
```

/home/git/gitlab/config/gitlab.yml을 편집합니다.

production: &base
  artifacts:
    enabled: false

파일을 저장하고 GitLab을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

job 아티팩트 저장#

대부분의 아티팩트는 코디네이터로 전송되기 전에 GitLab Runner가 압축합니다. 다만 reports 아티팩트는 업로드 후에 압축됩니다.

로컬 저장소 사용#

Linux 패키지를 사용하거나 직접 컴파일해 설치했다면 아티팩트가 로컬에 저장되는 위치를 변경할 수 있습니다.

Note

Docker 설치에서는 데이터를 마운트하는 경로를 변경할 수 있습니다. Helm chart에서는 오브젝트 스토리지를 사용합니다.

아티팩트는 기본적으로 /var/opt/gitlab/gitlab-rails/shared/artifacts에 저장됩니다.

저장 경로를 예를 들어 /mnt/storage/artifacts로 변경하려면 /etc/gitlab/gitlab.rb를 편집해 다음 줄을 추가합니다.
```
gitlab_rails['artifacts_path'] = "/mnt/storage/artifacts"
```
파일을 저장하고 GitLab을 재구성합니다.
```
sudo gitlab-ctl reconfigure
```

아티팩트는 기본적으로 /home/git/gitlab/shared/artifacts에 저장됩니다.

저장 경로를 예를 들어 /mnt/storage/artifacts로 변경하려면 /home/git/gitlab/config/gitlab.yml을 편집해 다음 줄을 추가하거나 수정합니다.
```
production: &base
  artifacts:
    enabled: true
    path: /mnt/storage/artifacts
```

파일을 저장하고 GitLab을 재시작합니다.

# For systems running systemd
sudo systemctl restart gitlab.target

# For systems running SysV init
sudo service gitlab restart

오브젝트 스토리지 사용#

아티팩트를 저장하는 데 GitLab 이 설치된 로컬 디스크를 사용하지 않으려면 AWS S3 같은 오브젝트 스토리지를 대신 사용할 수 있습니다.

Warning

다중 서버 구성에서는 job 로그의 로컬 디스크 사용을 없애는 옵션 중 하나를 반드시 사용해야 하며, 그렇지 않으면 job 로그가 유실될 수 있습니다.

통합 오브젝트 스토리지 설정을 사용하는 것이 좋습니다.

오브젝트 스토리지로 마이그레이션#

오브젝트 스토리지를 구성합니다.
아티팩트를 마이그레이션합니다.

   sudo gitlab-rake gitlab:artifacts:migrate

   sudo docker exec -t <container name> gitlab-rake gitlab:artifacts:migrate

   sudo -u git -H bundle exec rake gitlab:artifacts:migrate RAILS_ENV=production

선택 사항. PostgreSQL 콘솔로 진행 상황을 추적하고 모든 job 아티팩트가 정상적으로 마이그레이션되었는지 검증합니다.
1. PostgreSQL 콘솔을 엽니다.

      sudo gitlab-psql
      ```

</div>

<div class="tab-panel" data-tab-index="1">

```shell
      sudo docker exec -it <container_name> /bin/bash
      gitlab-psql
      ```

</div>

<div class="tab-panel" data-tab-index="2">

```shell
      sudo -u git -H psql -d gitlabhq_production
      ```

</div>

</div>

   1. 다음 SQL 쿼리로 모든 아티팩트가 오브젝트 스토리지로 마이그레이션되었는지
      검증합니다. `objectstg`의 수가 `total`과 같아야 합니다.

      ```shell
      gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM p_ci_job_artifacts;

      total | filesystem | objectstg
      ------+------------+-----------
         19 |          0 |        19
      ```

1. `artifacts` 디렉터리의 디스크에 파일이 남아 있지 않은지 확인합니다.

   <div class="tabs-container" data-tabs><div class="tabs-nav"><button class="tab-button active" data-tab-index="0">Linux package (Omnibus)</button><button class="tab-button" data-tab-index="1">Docker</button><button class="tab-button" data-tab-index="2">Self-compiled (source)</button></div><div class="tab-panel active" data-tab-index="0">

```shell
   sudo find /var/opt/gitlab/gitlab-rails/shared/artifacts -type f | grep -v tmp | wc -l

/var/opt/gitlab을 /srv/gitlab에 마운트했다고 가정합니다.

sudo find /srv/gitlab/gitlab-rails/shared/artifacts -type f | grep -v tmp | wc -l

   sudo find /home/git/gitlab/shared/artifacts -type f | grep -v tmp | wc -l

Geo가 활성화되어 있다면 모든 job 아티팩트를 다시 검증합니다.

경우에 따라 고아 아티팩트를 정리하려면 고아 아티팩트 파일 정리 Rake 태스크를 실행해야 합니다.

오브젝트 스토리지에서 로컬 저장소로 마이그레이션#

아티팩트를 로컬 저장소로 되돌리는 방법은 다음과 같습니다.

gitlab-rake gitlab:artifacts:migrate_to_local을 실행합니다.
gitlab.rb에서 아티팩트 저장소를 선택적으로 비활성화합니다.
GitLab을 재구성합니다.

GitLab 18.6 이전에는 원격에서 로컬 저장소로 마이그레이션할 때 아티팩트가 잘못된 파일 이름으로 복사될 수 있었습니다.

아티팩트 만료#

아티팩트의 최대 파일 크기 설정#

아티팩트가 활성화되어 있으면 Admin 영역 설정에서 아티팩트의 최대 파일 크기를 변경할 수 있습니다.

저장소 통계#

그룹과 프로젝트의 job 아티팩트가 사용하는 전체 저장 용량을 볼 수 있습니다.

저장 용량을 가장 많이 사용하는 그룹이나 프로젝트를 확인하는 방법은 다음과 같습니다.

Admin 영역에서 Overview > Projects로 이동한 다음 Storage size로 정렬합니다.
groups API와 projects API로 각 그룹이나 프로젝트의 저장 용량 통계를 조회합니다.

구현 세부 사항#

특정 파일을 선택하면 GitLab Workhorse가 아카이브에서 해당 파일을 추출하고 다운로드가 시작됩니다. 이 구현은 공간, 메모리, 디스크 I/O를 아낍니다.