관리자 영역에서 GitLab 인스턴스의 CI/CD 설정을 구성합니다.

사전 요구 사항:

• 관리자 액세스 권한이 있어야 합니다.

다음 설정을 사용할 수 있습니다:

• 변수: 인스턴스의 모든 프로젝트에서 사용할 수 있는 CI/CD 변수를 구성합니다.
• 지속적인 통합 및 배포: Auto DevOps, job, 아티팩트, 인스턴스 러너, 파이프라인 기능에 대한 설정을 구성합니다.
• 패키지 레지스트리: 패키지 전달과 파일 크기 제한을 구성합니다.
• 러너: 러너 등록, 버전 관리, 토큰 설정을 구성합니다.
• job 토큰 권한: 프로젝트 간 job 토큰 액세스를 제어합니다.
• job 로그: 증분 로깅과 같은 job 로그 설정을 구성합니다.
• CI/CD 제한.

지속적인 통합 및 배포 설정 액세스#

Auto DevOps, 인스턴스 러너, job 아티팩트를 포함한 CI/CD 설정을 사용자 지정합니다.

이 설정에 액세스하려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Continuous Integration and Deployment를 확장합니다.

모든 프로젝트에 Auto DevOps 구성#

.gitlab-ci.yml 파일이 없는 모든 프로젝트에서 Auto DevOps가 실행되도록 구성합니다. 이 설정은 기존 프로젝트와 새 프로젝트 모두에 적용됩니다.

인스턴스의 모든 프로젝트에 Auto DevOps를 구성하려면:

1. Default to Auto DevOps pipeline for all projects 확인란을 선택합니다.
2. 선택 사항. Auto Deploy와 Auto Review Apps를 사용하려면 Auto DevOps 기본 도메인을 지정합니다.
3. Save changes를 선택합니다.

인스턴스 러너#

새 프로젝트에 인스턴스 러너 활성화#

기본적으로 모든 새 프로젝트에서 인스턴스 러너를 사용할 수 있게 합니다.

새 프로젝트에서 인스턴스 러너를 사용할 수 있게 하려면:

1. Enable instance runners for new projects 확인란을 선택합니다.
2. Save changes를 선택합니다.

인스턴스 러너 세부 정보 추가#

인스턴스 러너에 대한 설명 텍스트를 추가합니다. 이 텍스트는 모든 프로젝트의 러너 설정에 표시됩니다.

인스턴스 러너 세부 정보를 추가하려면:

1. Instance runner details 텍스트 상자에 텍스트를 입력합니다. Markdown 형식을 사용할 수 있습니다.
2. Save changes를 선택합니다.

렌더링된 세부 정보를 확인하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Runners를 확장합니다.

여러 프로젝트와 프로젝트 러너 공유#

프로젝트 러너를 여러 프로젝트와 공유합니다.

사전 요구 사항:

• 등록된 프로젝트 러너가 있어야 합니다.

프로젝트 러너를 여러 프로젝트와 공유하려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 CI/CD > Runners를 선택합니다.
3. 편집할 러너를 선택합니다.
4. 오른쪽 상단에서 Edit(✏️)를 선택합니다.
5. Restrict projects for this runner에서 프로젝트를 검색합니다.
6. 프로젝트 왼쪽에서 Enable을 선택합니다.
7. 추가할 프로젝트마다 이 과정을 반복합니다.

job 아티팩트#

job 아티팩트를 GitLab 인스턴스 전체에서 어떻게 저장하고 관리할지 제어합니다.

기본 아티팩트 만료 설정#

job 아티팩트가 자동으로 삭제되기 전까지 보관되는 기간을 설정합니다. 기본 만료 시간은 30일입니다.

기간 구문은 artifacts:expire_in에 설명되어 있습니다. 개별 job 정의는 프로젝트의 .gitlab-ci.yml 파일에서 이 기본값을 재정의할 수 있습니다.

이 설정의 변경은 새 아티팩트에만 적용됩니다. 기존 아티팩트는 원래 만료 시간을 유지합니다. 이전 아티팩트를 수동으로 만료시키는 방법은 문제 해결 문서를 참고합니다.

job 아티팩트의 기본 만료 시간을 설정하려면:

1. Default artifacts expiration 텍스트 상자에 값을 입력합니다.
2. Save changes를 선택합니다.

최신 성공 파이프라인의 아티팩트 보존#

각 Git ref(브랜치 또는 태그)에 대해 GitLab은 다음의 아티팩트를 보존합니다.

• 실패했거나 수동 job으로 차단되었더라도 해당 ref의 최신 파이프라인.
• 최신 파이프라인과 다르다면 가장 최근에 성공한 파이프라인.

기본적으로 이 아티팩트는 만료 시간과 관계없이 보존됩니다.

이 설정은 프로젝트 설정보다 우선합니다. 인스턴스에서 껐다면 개별 프로젝트에서는 켤 수 없습니다.

이 기능을 끄더라도 이미 보존된 아티팩트가 즉시 만료되지는 않습니다. 아티팩트가 만료되려면 먼저 해당 브랜치에서 더 새로운 파이프라인이 완료되거나 수동 job으로 차단되어야 합니다.

최신 성공 파이프라인의 아티팩트를 보존하려면:

1. Keep the latest artifacts for all jobs in the latest successful pipelines 확인란을 선택합니다.
2. Save changes를 선택합니다.

아티팩트가 만료 설정에 따라 만료되도록 하려면 확인란을 해제합니다.

외부 리디렉션 경고 페이지 표시 또는 숨기기#

사용자가 GitLab Pages를 통해 job 아티팩트를 볼 때 경고 페이지를 표시할지 제어합니다. 이 경고는 사용자 생성 콘텐츠로 인한 잠재적 보안 위험을 알립니다.

외부 리디렉션 경고 페이지는 기본적으로 표시됩니다. 숨기려면:

1. Enable the external redirect page for job artifacts 확인란을 해제합니다.
2. Save changes를 선택합니다.

파이프라인#

파이프라인 아카이브#

지정한 기간이 지나면 오래된 파이프라인과 그 모든 job을 자동으로 아카이브합니다. 아카이브된 job은 다음과 같습니다.

• job 로그 상단에 This job is archived 안내 알림을 표시합니다.
• 다시 실행하거나 재시도할 수 없습니다.
• 환경이 자동 중지될 때 on-stop 배포 작업으로 실행할 수 없습니다.
• job 로그는 계속 확인할 수 있습니다.

아카이브 기간은 파이프라인이 생성된 시점부터 측정되며, 최소 1일이어야 합니다. 유효한 기간의 예로는 15 days, 1 month, 2 years가 있습니다. 파이프라인을 자동으로 아카이브하지 않으려면 이 필드를 비워 둡니다.

GitLab.com은 파이프라인 아카이브를 참고합니다.

job 아카이브를 설정하려면:

1. Archive pipelines 텍스트 상자에 값을 입력합니다.
2. Save changes를 선택합니다.

기본적으로 파이프라인 변수 허용#

히스토리

• GitLab 18.1에서 도입되었습니다.

새 그룹의 새 프로젝트에서 파이프라인 변수를 기본적으로 허용할지 제어합니다.

비활성화하면 새 그룹의 파이프라인 변수를 사용할 수 있는 기본 권한 설정이 No one allowed로 지정되며, 이 값은 새 그룹의 새 프로젝트로 연쇄 적용됩니다. 활성화하면 이 설정의 기본값이 Developer가 됩니다.

새 그룹의 모든 새 프로젝트에서 파이프라인 변수를 기본적으로 허용하려면:

1. Allow pipeline variables by default in new groups 확인란을 선택합니다.
2. Save changes를 선택합니다.

그룹 또는 프로젝트를 생성한 뒤에는 Maintainer가 다른 설정을 선택할 수 있습니다.

기본적으로 CI/CD 변수 보호#

프로젝트와 그룹의 모든 새 CI/CD 변수를 기본적으로 보호되도록 설정합니다. 보호된 변수는 보호된 브랜치 또는 보호된 태그에서 실행되는 파이프라인에서만 사용할 수 있습니다.

모든 새 CI/CD 변수를 기본적으로 보호하려면:

1. Protect CI/CD variables by default 확인란을 선택합니다.
2. Save changes를 선택합니다.

기본 CI/CD 구성 파일 지정#

모든 새 프로젝트에서 CI/CD 구성 파일의 기본값으로 사용할 사용자 지정 경로와 파일 이름을 설정합니다. 기본적으로 GitLab은 프로젝트 루트 디렉터리의 .gitlab-ci.yml 파일을 사용합니다.

이 설정은 변경한 뒤에 생성된 새 프로젝트에만 적용됩니다. 기존 프로젝트는 현재의 CI/CD 구성 파일 경로를 계속 사용합니다.

사용자 지정 기본 CI/CD 구성 파일 경로를 설정하려면:

1. Default CI/CD configuration file 텍스트 상자에 값을 입력합니다.
2. Save changes를 선택합니다.

개별 프로젝트는 사용자 지정 CI/CD 구성 파일 지정으로 이 인스턴스 기본값을 재정의할 수 있습니다.

Jenkins 마이그레이션 배너 표시 또는 숨기기#

히스토리

• GitLab 17.7에서 도입되었습니다.

Jenkins에서 GitLab CI/CD로 마이그레이션하도록 권장하는 배너를 표시할지 제어합니다. 이 배너는 Jenkins 통합이 활성화된 프로젝트의 머지 리퀘스트에 나타납니다.

Jenkins 마이그레이션 배너는 기본적으로 표시됩니다. 숨기려면:

1. Show the migrate from Jenkins banner 확인란을 선택합니다.
2. Save changes를 선택합니다.

패키지 레지스트리 설정 액세스#

NuGet 패키지 유효성 검사, Helm 패키지 제한, 패키지 파일 크기 제한, 패키지 전달을 구성합니다.

이 설정에 액세스하려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Package registry를 확장합니다.

NuGet 패키지 메타데이터 URL 유효성 검사 건너뛰기#

NuGet 패키지의 projectUrl, iconUrl, licenseUrl 메타데이터에 대한 유효성 검사를 건너뜁니다.

기본적으로 GitLab은 이 URL들을 검증합니다. GitLab 인스턴스에 인터넷 액세스가 없으면 이 검증이 실패하고 NuGet 패키지를 업로드할 수 없습니다.

NuGet 패키지 메타데이터 URL 유효성 검사를 건너뛰려면:

1. Skip metadata URL validation for the NuGet package 확인란을 선택합니다.
2. Save changes를 선택합니다.

채널당 최대 Helm 패키지 수 설정#

채널당 나열할 수 있는 Helm 패키지의 최대 개수를 설정합니다.

Helm 패키지 제한을 설정하려면:

1. Package limits에서 Maximum number of Helm packages per channel 필드에 값을 입력합니다.
2. Save changes를 선택합니다.

패키지 파일 크기 제한 설정#

스토리지 사용량을 제어하고 시스템 성능을 유지하기 위해 패키지 유형별로 최대 파일 크기 제한을 설정합니다.

다음 패키지에 대해 최대 파일 크기 제한을 바이트 단위로 구성할 수 있습니다.

• Conan 패키지
• Helm 차트
• Maven 패키지
• npm 패키지
• NuGet 패키지
• PyPI 패키지
• Terraform Module 패키지
• 일반 패키지

패키지 파일 크기 제한을 구성하려면:

1. Package file size limits에서 구성할 제한 값을 입력합니다.
2. Save size limits를 선택합니다.

패키지 전달 제어#

GitLab 패키지 레지스트리에서 패키지를 찾을 수 없을 때 패키지 요청을 공개 레지스트리로 전달할지 제어합니다.

기본적으로 GitLab은 패키지 요청을 해당 공개 레지스트리로 전달합니다.

• Maven 요청은 Maven Central로 전달됩니다.
• npm 요청은 npmjs.com으로 전달됩니다.
• PyPI 요청은 pypi.org로 전달됩니다.

패키지 전달을 끄려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Overview > Groups를 선택하고 그룹을 찾습니다.
3. Settings > CI/CD를 선택합니다.
4. Package registry를 확장합니다.
5. 다음 확인란 중 하나를 해제합니다.
   • Forward npm package requests
   • Forward PyPI package requests
6. Save changes를 선택합니다.

Maven 패키지의 요청 전달을 끄려면 패키지 레지스트리의 Maven 패키지를 참고합니다.

러너 설정 액세스#

러너 버전 관리와 등록 설정을 구성합니다.

이 설정에 액세스하려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Runners를 확장합니다.

러너 버전 관리 제어#

러너의 업그레이드 필요 여부를 판단하기 위해 인스턴스가 GitLab.com에서 공식 러너 버전 데이터를 가져올지 제어합니다.

기본적으로 GitLab은 러너 버전 데이터를 가져옵니다. 이 데이터 가져오기를 중단하려면:

1. Runner version management에서 Fetch GitLab Runner release version data from GitLab.com 확인란을 해제합니다.
2. Save changes를 선택합니다.

러너 등록 제어#

누가 러너를 등록할 수 있는지와 등록 토큰을 허용할지 제어합니다.

기본적으로 러너 등록 토큰과 프로젝트 및 그룹 멤버의 등록이 모두 허용됩니다. 러너 등록을 제한하려면:

1. Runner registration에서 다음 확인란 중 하나를 해제합니다.
   • Allow runner registration token
   • Members of the project can create runners
   • Members of the group can create runners
2. Save changes를 선택합니다.

특정 그룹의 러너 등록 제한#

특정 그룹의 멤버가 러너를 등록할 수 있는지 제어합니다.

사전 요구 사항:

• 러너 등록 설정에서 Members of the group can create runners 확인란이 선택되어 있어야 합니다.

특정 그룹의 러너 등록을 제한하려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Overview > Groups를 선택하고 그룹을 찾습니다.
3. Edit를 선택합니다.
4. Runner Registration에서 New group runners can be registered 확인란을 해제합니다.
5. Save changes를 선택합니다.

job 토큰 권한 설정 액세스#

CI/CD job 토큰이 프로젝트에 액세스하는 방식을 제어합니다.

이 설정에 액세스하려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Job token permissions를 확장합니다.

job 토큰 허용 목록 적용#

히스토리

• GitLab 17.6에서 도입되었습니다.

모든 프로젝트가 허용 목록으로 job 토큰 액세스를 제어하도록 요구합니다.

이 설정을 활성화하면 다음과 같이 동작합니다.

• CI/CD job 토큰은 해당 토큰의 소스 프로젝트가 허용 목록에 추가된 프로젝트에만 액세스할 수 있습니다.
• 사용자가 허용 목록을 비활성화하려고 하면 CI/CD job 토큰 스코프 API가 오류를 반환합니다.

자세한 내용은 프로젝트에 대한 job 토큰 액세스 제어를 참고합니다.

job 토큰 허용 목록을 적용하려면:

1. Authorized groups and projects에서 Enable and enforce job token allowlist for all projects 확인란을 선택합니다.
2. Save changes를 선택합니다.

회수된 프로젝트 경로에 대한 JWT 제한#

히스토리

• 제한이 GitLab 19.1에서 도입되었습니다.
• block_jwt_for_reclaimed_paths 애플리케이션 설정이 GitLab 19.4에서 도입되었습니다.

GitLab은 이전에 사용된 네임스페이스 경로로 이름이 변경되거나 이동된 프로젝트에 대해 CI/CD 파이프라인에서 JWT와 OIDC 토큰 생성을 차단합니다. 이 제한은 네임스페이스 회수를 이용한 인증 우회 공격을 방지합니다.

이동되거나 이름이 변경된 프로젝트에서 CI/CD 파이프라인이 차단되는 경우 관리자가 이 제한을 비활성화할 수 있으나, 이는 보안 위험입니다.

회수된 경로에 대한 JWT 제한을 비활성화하려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Continuous Integration and Deployment를 확장합니다.
4. Block JWT generation in reclaimed project paths 확인란을 해제합니다.
5. Save changes를 선택합니다.

활성화된 경우 CI/CD job에서 토큰 생성이 다음 오류와 함께 실패합니다.

• ID token issuance is disabled in CI because a project path in the `sub` claim was previously used by a different project.

job 로그 설정 액세스#

CI/CD job 로그를 저장, 처리, 업데이트하는 방식을 제어합니다.

이 설정에 액세스하려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Job logs를 확장합니다.

job 로그 업데이트 빈도 구성#

히스토리

• GitLab 19.5에서 도입되었습니다.

job이 실행되는 동안 job 로그 업데이트를 전송하는 빈도를 구성합니다. 간격이 짧을수록 job 로그가 더 빨리 표시되지만 트레이스 업데이트 요청 수가 늘어납니다. job 로그가 열려 있을 때 사용하는 간격은 job 로그가 열려 있지 않을 때 사용하는 간격보다 작거나 같아야 합니다.

job 로그 업데이트 간격을 구성하려면:

1. Job log update interval에 값을 입력합니다.
2. Job log update interval when open에 값을 입력합니다.
3. Save changes를 선택합니다.

증분 로깅 구성#

히스토리

• 인스턴스 설정이 GitLab 17.11에서 도입되어 ci_enable_live_trace 기능 플래그를 대체했습니다.
• ci_enable_live_trace 기능 플래그가 GitLab 18.0에서 제거되었습니다.

Redis를 사용해 job 로그를 임시로 캐시하고 아카이브된 로그를 오브젝트 스토리지에 증분 방식으로 업로드합니다. 이렇게 하면 성능이 향상되고 디스크 공간 사용량이 줄어듭니다.

자세한 내용은 증분 로깅을 참고합니다.

사전 요구 사항:

• CI/CD 아티팩트, 로그, 빌드에 대해 오브젝트 스토리지를 구성해야 합니다.

모든 프로젝트에서 증분 로깅을 켜려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Job logs 섹션을 확장합니다.
4. Incremental logging configuration에서 Turn on incremental logging 확인란을 선택합니다.
5. Save changes를 선택합니다.

CI/CD 카탈로그 설정#

히스토리

• GitLab 18.7에서 도입되었습니다.

어떤 프로젝트가 CI/CD 카탈로그에 컴포넌트를 게시할 수 있는지 제어합니다.

이 설정에 액세스하려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Catalog를 확장합니다.

CI/CD 카탈로그 게시 제한#

기본적으로 모든 프로젝트가 CI/CD 카탈로그에 컴포넌트를 게시할 수 있습니다. 허용 목록을 구성해 게시를 특정 프로젝트로 제한할 수 있습니다.

허용 목록의 상태에 따라 다음과 같이 동작합니다.

• 비어 있음(기본값): 모든 프로젝트가 카탈로그에 게시할 수 있습니다.
• 프로젝트가 하나 이상 등록됨: 허용 목록의 항목과 일치하는 프로젝트만 게시할 수 있습니다.

허용 목록의 항목은 다음으로 정의할 수 있습니다.

• 정확한 프로젝트 경로. 예를 들어 my-group/my-project입니다.
• 정규 표현식. 예를 들면 다음과 같습니다.
  • my-group/.*: 해당 그룹의 모든 프로젝트입니다.
  • my-group/security-.*: security-로 시작하는 프로젝트입니다.

CI/CD 카탈로그 게시 허용 목록을 구성하려면:

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Catalog를 확장합니다.
4. CI/CD Catalog publishing allowlist 텍스트 영역에 한 줄에 하나씩 경로 패턴을 입력합니다.
5. Save changes를 선택합니다.

허용 목록에 없는 프로젝트가 컴포넌트 버전을 게시하려고 하면 not authorized to publish 오류를 받습니다.

필수 파이프라인 구성(더 이상 사용되지 않음)#

히스토리

• GitLab 17.0에서 제거되었습니다.
• GitLab 17.4에서 required_pipelines라는 이름의 기능 플래그와 함께 다시 추가되었습니다. 기본적으로 비활성화되어 있습니다.

GitLab 인스턴스의 모든 프로젝트에 대해 CI/CD 템플릿을 필수 파이프라인 구성으로 설정할 수 있습니다. 다음에서 가져온 템플릿을 사용할 수 있습니다.

• 기본 CI/CD 템플릿입니다.

• 인스턴스 템플릿 리포지터리에 저장된 사용자 지정 템플릿입니다.

  [!note] 인스턴스 템플릿 리포지터리에 정의된 구성을 사용하면 중첩된 include: 키워드 (include:file, include:local, include:remote, include:template 포함)가 동작하지 않습니다.

파이프라인이 실행될 때 프로젝트 CI/CD 구성이 필수 파이프라인 구성에 병합됩니다. 병합된 구성은 필수 파이프라인 구성이 include 키워드로 프로젝트 구성을 추가한 것과 동일합니다. 프로젝트의 전체 병합 구성을 확인하려면 파이프라인 에디터에서 전체 구성 보기를 사용합니다.

필수 파이프라인 구성에 사용할 CI/CD 템플릿을 선택하려면:

1. 왼쪽 사이드바 하단에서 Admin을 선택합니다.
2. Settings > CI/CD를 선택합니다.
3. Required pipeline configuration 섹션을 확장합니다.
4. 드롭다운 목록에서 CI/CD 템플릿을 선택합니다.
5. Save changes를 선택합니다.