이 문서는 GitLab .gitlab-ci.yml 파일의 설정 옵션을 정리합니다. 이 파일에서 파이프라인을 구성하는 CI/CD job을 정의합니다.

• 기본 CI/CD 개념에 이미 익숙하다면, 다음 튜토리얼을 따라 하면서 직접 .gitlab-ci.yml 파일을 만들어 보십시오. 이 튜토리얼은 기본 또는 복잡한 파이프라인을 보여줍니다.
• 예제 모음은 GitLab CI/CD 예제를 참고합니다.
• 기업에서 사용하는 대규모 .gitlab-ci.yml 파일을 보려면 gitlab의 .gitlab-ci.yml 파일을 참고합니다.

.gitlab-ci.yml 파일을 편집할 때는 CI Lint 도구로 유효성을 검증할 수 있습니다.

GitLab CI/CD 설정은 YAML 형식을 사용하므로, 별도로 명시하지 않는 한 키워드의 순서는 중요하지 않습니다.

더 동적인 파이프라인 설정 옵션을 사용하려면 CI/CD 표현식을 활용합니다.

키워드#

GitLab CI/CD 파이프라인 설정은 다음으로 구성됩니다:

• 파이프라인 동작을 설정하는 전역 키워드:

  키워드	설명
  default	job 키워드에 대한 사용자 지정 기본값입니다.
  include	다른 YAML 파일에서 설정을 가져옵니다.
  stages	파이프라인 Stage의 이름과 순서입니다.
  variables	파이프라인의 모든 job에 대한 기본 CI/CD 변수를 정의합니다.
  workflow	실행되는 파이프라인의 유형을 제어합니다.

• 헤더 키워드

  키워드	설명
  spec	외부 설정 파일에 대한 사양을 정의합니다.

• Job은 job 키워드를 사용하여 구성됩니다:

  키워드	설명
  after_script	job 이후에 실행되는 명령 집합을 재정의합니다.
  allow_failure	job 이 실패해도 허용합니다. 실패한 job 이 있어도 파이프라인은 실패하지 않습니다.
  artifacts	성공 시 job에 첨부할 파일 및 디렉터리 목록입니다.
  before_script	job 이전에 실행되는 명령 집합을 재정의합니다.
  cache	이후 실행 간에 캐시해야 할 파일 목록입니다.
  coverage	특정 job에 대한 코드 커버리지 설정입니다.
  dast_configuration	job 수준에서 DAST 프로필의 설정을 사용합니다.
  dependencies	아티팩트를 가져올 job 목록을 지정하여 특정 job에 전달되는 아티팩트를 제한합니다.
  environment	job 이 배포되는 환경의 이름입니다.
  extends	이 job 이 상속받는 설정 항목입니다.
  identity	ID 페더레이션을 사용하여 서드파티 서비스에 인증합니다.
  image	Docker 이미지를 사용합니다.
  inherit	모든 job 이 상속할 전역 기본값을 선택합니다.
  interruptible	새 실행으로 인해 불필요해진 job을 취소할 수 있는지 정의합니다.
  manual_confirmation	수동 job에 대한 사용자 지정 확인 메시지를 정의합니다.
  needs	Stage 순서보다 먼저 job을 실행합니다.
  pages	GitLab Pages에서 사용할 job 결과를 업로드합니다.
  parallel	job 인스턴스를 병렬로 몇 개 실행할지 지정합니다.
  release	러너에게 릴리스 객체를 생성하도록 지시합니다.
  resource_group	job 동시 실행을 제한합니다.
  retry	job 이 실패했을 때 언제, 몇 번 자동으로 재시도할 수 있는지 지정합니다.
  rules	job의 특정 속성과 생성 여부를 결정하기 위해 평가할 조건 목록입니다.
  script	러너가 실행하는 셸 스크립트입니다.
  run	러너가 실행하는 run 설정입니다.
  secrets	job에 필요한 CI/CD 시크릿입니다.
  services	Docker 서비스 이미지를 사용합니다.
  stage	job의 Stage를 정의합니다.
  start_in	지정한 기간만큼 job 실행을 지연시킵니다. when: delayed가 필요합니다.
  tags	러너를 선택하는 데 사용되는 태그 목록입니다.
  timeout	프로젝트 전체 설정보다 우선하는 job 수준의 사용자 지정 타임아웃을 정의합니다.
  trigger	다운스트림 파이프라인 트리거를 정의합니다.
  variables	개별 job에 대한 CI/CD 변수를 정의합니다.
  when	job을 실행할 시점입니다.

• 더 이상 사용을 권장하지 않는 지원 중단된 키워드입니다.

---

전역 키워드#

일부 키워드는 job 안에 정의되지 않습니다. 이러한 키워드는 파이프라인 동작을 제어하거나 추가 파이프라인 설정을 가져옵니다.

---

default#

일부 키워드에 전역 기본값을 설정할 수 있습니다. 각 기본 키워드는 아직 정의되지 않은 모든 job에 복사됩니다.

기본 설정은 job 설정과 병합되지 않습니다. job에 이미 키워드가 정의되어 있으면 해당 job의 키워드가 우선하며, 그 키워드에 대한 기본 설정은 사용되지 않습니다.

키워드 유형: 전역 키워드입니다.

지원되는 값: 다음 키워드에 사용자 지정 기본값을 설정할 수 있습니다:

• after_script
• artifacts
• before_script
• cache
• hooks
• id_tokens
• image
• interruptible
• retry
• services
• tags

default 예시:

default:
  image: ruby:3.0
  retry: 2

rspec:
  script: bundle exec rspec

rspec 2.7:
  image: ruby:2.7
  script: bundle exec rspec

이 예시에서:

• image: ruby:3.0과 retry: 2는 파이프라인의 모든 job에 대한 기본 키워드입니다.
• rspec job은 image 나 retry가 정의되어 있지 않으므로 기본값인 image: ruby:3.0과 retry: 2를 사용합니다.
• rspec 2.7 job은 retry가 정의되어 있지 않지만 image는 명시적으로 정의되어 있습니다. 이 job은 기본값 retry: 2를 사용하지만, 기본 image는 무시하고 job에 정의된 image: ruby:2.7을 사용합니다.

추가 정보:

• job에서 기본 키워드의 상속 여부는 inherit:default로 제어합니다.
• 전역 기본값은 다운스트림 파이프라인에 전달되지 않습니다. 다운스트림 파이프라인은 이를 트리거한 업스트림 파이프라인과 독립적으로 실행됩니다.

---

include#

CI/CD 설정에 외부 YAML 파일을 포함하려면 include를 사용합니다. 하나의 긴 .gitlab-ci.yml 파일을 여러 파일로 분할하여 가독성을 높이거나, 여러 곳에서 동일한 설정이 중복되는 것을 줄일 수 있습니다.

템플릿 파일을 중앙 리포지터리에 저장하고 프로젝트에서 포함시킬 수도 있습니다.

include 파일은 다음과 같습니다:

• .gitlab-ci.yml 파일의 내용과 병합됩니다.
• include 키워드의 위치와 관계없이 항상 먼저 평가된 다음 .gitlab-ci.yml 파일의 내용과 병합됩니다.

모든 파일을 확인하는 데 걸리는 시간 제한은 30초입니다.

키워드 유형: 전역 키워드입니다.

지원되는 값: include의 하위 키:

• include:component
• include:local
• include:project
• include:remote
• include:template

그리고 선택적으로:

• include:inputs
• include:rules
• include:integrity
• include:cache

추가 정보:

• include 키워드와 함께 사용할 수 있는 것은 특정 CI/CD 변수뿐입니다.
• 병합 기능을 사용하여 로컬 설정으로 포함된 CI/CD 설정을 사용자 지정하거나 재정의할 수 있습니다.
• .gitlab-ci.yml 파일에 동일한 job 이름이나 전역 키워드를 두어 포함된 설정을 재정의할 수 있습니다. 두 설정은 함께 병합되며, .gitlab-ci.yml 파일의 설정이 포함된 설정보다 우선합니다.
• 다음을 재실행하는 경우:
  • Job: include 파일을 다시 가져오지 않습니다. 파이프라인의 모든 job은 파이프라인이 생성될 때 가져온 설정을 사용합니다. 원본 include 파일이 변경되어도 job 재실행에는 영향을 주지 않습니다.
  • Pipeline: include 파일을 다시 가져옵니다. 마지막 파이프라인 실행 이후 파일이 변경되었다면, 새 파이프라인은 변경된 설정을 사용합니다.
• 중첩을 포함하여 파이프라인당 기본적으로 최대 150개의 include를 사용할 수 있습니다. 추가로:
  • GitLab Self-Managed 사용자는 최대 include 개수 값을 변경할 수 있습니다.
  • 중첩된 include에서는 동일한 파일을 여러 번 포함할 수 있지만, 중복된 include도 개수 제한에 포함됩니다.

---

include:component#

파이프라인 설정에 CI/CD 컴포넌트를 추가하려면 include:component를 사용합니다.

키워드 유형: 전역 키워드입니다.

지원되는 값: <fully-qualified-domain-name>/<project-path>/<component-name>@<specific-version> 형식의 CI/CD 컴포넌트 전체 주소입니다.

include:component 예시:

include:
  - component: $CI_SERVER_FQDN/my-org/security-components/secret-detection@1.0

추가 정보:

• 컴포넌트의 소스 프로젝트가 비공개인 경우, 파이프라인을 실행하는 사용자는 최소 Reporter 권한이 있어야 합니다. 내부 프로젝트의 경우 인증된 비외부 사용자라면 누구나 컴포넌트에 접근할 수 있습니다. 공개 프로젝트의 경우 멤버십이 필요하지 않습니다.

관련 항목:

• CI/CD 컴포넌트 사용하기.

---

include:local#

include:local을 사용하면 include 키워드가 포함된 설정 파일과 동일한 리포지터리 및 브랜치에 있는 파일을 포함할 수 있습니다. 심볼릭 링크 대신 include:local을 사용합니다.

키워드 유형: 전역 키워드입니다.

지원되는 값:

루트 디렉터리(/) 기준의 전체 경로:

• YAML 파일의 확장자는 .yml 또는 .yaml 이어야 합니다.
• 파일 경로에 *와 ** 와일드카드를 사용할 수 있습니다.
• 특정 CI/CD 변수를 사용할 수 있습니다.

include:local 예시:

include:
  - local: '/templates/.gitlab-ci-template.yml'

경로를 정의할 때 더 짧은 구문을 사용할 수도 있습니다:

include: '.gitlab-ci-production.yml'

추가 정보:

• .gitlab-ci.yml 파일과 로컬 파일은 동일한 브랜치에 있어야 합니다.
• Git 서브모듈 경로를 통해 로컬 파일을 포함할 수는 없습니다.
• include 설정은 파이프라인을 실행하는 프로젝트가 아니라, include 키워드가 포함된 파일의 위치를 기준으로 항상 평가됩니다. 중첩된 include가 다른 프로젝트의 설정 파일에 있는 경우, include: local은 해당 파일을 그 다른 프로젝트에서 찾습니다.

---

include:project#

동일한 GitLab 인스턴스에 있는 다른 비공개 프로젝트의 파일을 포함하려면 include:project와 include:file을 사용합니다.

키워드 유형: 전역 키워드입니다.

지원되는 값:

• include:project: GitLab 프로젝트의 전체 경로입니다.
• include:file: 루트 디렉터리(/) 기준의 전체 파일 경로 또는 파일 경로 배열입니다. YAML 파일의 확장자는 .yml 또는 .yaml 이어야 합니다.
• include:ref: 선택 사항입니다. 파일을 가져올 ref 입니다. 지정하지 않으면 프로젝트의 HEAD를 기본값으로 사용합니다. 브랜치 이름, 태그 이름 또는 커밋 SHA일 수 있습니다. 같은 이름의 브랜치와 태그 사이의 모호함을 피하려면 refs/heads/<branch> 또는 refs/tags/<tag> 같은 정규화된 ref를 사용합니다.
• 특정 CI/CD 변수를 사용할 수 있습니다.

include:project 예시:

include:
  - project: 'my-group/my-project'
    file: '/templates/.gitlab-ci-template.yml'
  - project: 'my-group/my-subgroup/my-project-2'
    file:
      - '/templates/.builds.yml'
      - '/templates/.tests.yml'

ref를 지정할 수도 있습니다:

include:
  - project: 'my-group/my-project'
    ref: refs/heads/main                           # Git branch, fully qualified
    file: '/templates/.gitlab-ci-template.yml'
  - project: 'my-group/my-project'
    ref: refs/tags/v1.0.0                          # Git tag, fully qualified
    file: '/templates/.gitlab-ci-template.yml'
  - project: 'my-group/my-project'
    ref: main                                      # Git branch or tag, short form
    file: '/templates/.gitlab-ci-template.yml'
  - project: 'my-group/my-project'
    ref: 787123b47f14b552955ca2786bc9542ae66fee5b  # Git SHA
    file: '/templates/.gitlab-ci-template.yml'

추가 정보:

• include 설정은 파이프라인을 실행하는 프로젝트가 아니라, include 키워드가 포함된 파일의 위치를 기준으로 항상 평가됩니다. 중첩된 include가 다른 프로젝트의 설정 파일에 있는 경우, include: local은 해당 파일을 그 다른 프로젝트에서 찾습니다.
• 파이프라인이 시작되면 모든 방식으로 포함된 .gitlab-ci.yml 파일 설정이 평가됩니다. 이 설정은 특정 시점의 스냅샷으로 데이터베이스에 저장됩니다. GitLab은 다음 파이프라인이 시작되기 전까지 참조된 .gitlab-ci.yml 파일 설정의 변경 사항을 반영하지 않습니다.
• include:project에 지정된 비공개 프로젝트의 경우, 파이프라인을 실행하는 사용자는 최소 Reporter 권한이 있어야 합니다. 내부 프로젝트의 경우 인증된 비외부 사용자라면 누구나 포함된 파일에 접근할 수 있습니다. 공개 프로젝트의 경우 멤버십이 필요하지 않습니다. 사용자가 포함된 프로젝트에 대한 충분한 권한이 없으면 not found or access denied 오류가 표시됩니다.
• 다른 프로젝트의 CI/CD 설정 파일을 포함할 때는 주의합니다. CI/CD 설정 파일이 변경되어도 파이프라인이나 알림이 트리거되지 않습니다. 보안 관점에서 이는 서드파티 의존성을 가져오는 것과 유사합니다. ref에 대해서는 다음을 고려합니다:
  • 가장 안정적인 방법은 특정 SHA 해시를 사용하는 것입니다. ref에 짧은 SHA 해시를 사용하면 모호할 수 있으므로, 원하는 커밋이 확실히 참조되도록 40자리 전체 SHA 해시를 사용합니다.
  • main 같은 짧은 이름 대신 refs/heads/<branch> 또는 refs/tags/<tag> 같은 정규화된 ref를 사용합니다. 짧은 이름은 브랜치와 태그에 모두 일치할 수 있습니다. 둘 다 존재하면, 같은 이름의 보호된 브랜치에서 파일을 포함하려고 했더라도 태그에서 파일을 가져옵니다.
  • 다른 프로젝트의 ref에 보호된 브랜치와 보호된 태그 규칙을 모두 적용합니다. 보호된 태그와 브랜치는 변경되기 전에 변경 관리를 거칠 가능성이 더 높습니다.

---

include:remote#

다른 위치의 파일을 포함하려면 전체 URL과 함께 include:remote를 사용합니다.

키워드 유형: 전역 키워드입니다.

지원되는 값:

HTTP/HTTPS GET 요청으로 접근 가능한 공개 URL:

• 원격 URL에 대한 인증은 지원되지 않습니다.
• YAML 파일의 확장자는 .yml 또는 .yaml 이어야 합니다.
• 특정 CI/CD 변수를 사용할 수 있습니다.

include:remote 예시:

include:
  - remote: 'https://gitlab.com/example-project/-/raw/main/.gitlab-ci.yml'

추가 정보:

• 중첩된 include는 모두 공개 사용자로서 컨텍스트 없이 실행되므로, 공개 프로젝트나 템플릿만 포함할 수 있습니다. 중첩된 include의 include 섹션에서는 변수를 사용할 수 없습니다.
• 다른 프로젝트의 CI/CD 설정 파일을 포함할 때는 주의합니다. 다른 프로젝트의 파일이 변경되어도 파이프라인이나 알림이 트리거되지 않습니다. 보안 관점에서 이는 서드파티 의존성을 가져오는 것과 유사합니다. 포함된 파일의 무결성을 검증하려면 integrity 키워드 사용을 고려합니다. 자신이 소유한 다른 GitLab 프로젝트를 링크하는 경우, 변경 관리 규칙을 적용하기 위해 보호된 브랜치와 보호된 태그를 모두 사용하는 것을 고려합니다.

---

include:template#

.gitlab-ci.yml 템플릿을 포함하려면 include:template을 사용합니다.

키워드 유형: 전역 키워드입니다.

지원되는 값:

• CI/CD 템플릿의 파일명입니다(예: Auto-DevOps.gitlab-ci.yml).
• 특정 CI/CD 변수를 사용할 수 있습니다.

include:template 예시:

# File sourced from the GitLab template collection
include:
  - template: Auto-DevOps.gitlab-ci.yml

여러 개의 include:template 파일:

include:
  - template: Android-Fastlane.gitlab-ci.yml
  - template: Auto-DevOps.gitlab-ci.yml

추가 정보:

• 모든 템플릿은 lib/gitlab/ci/templates에서 확인할 수 있습니다. 모든 템플릿이 include:template과 함께 사용하도록 설계된 것은 아니므로, 사용하기 전에 템플릿 주석을 확인합니다.
• 중첩된 include는 모두 공개 사용자로서 컨텍스트 없이 실행되므로, 공개 프로젝트나 템플릿만 포함할 수 있습니다. 중첩된 include의 include 섹션에서는 변수를 사용할 수 없습니다.

---

include:inputs#

히스토리

• GitLab 17.0에서 GA(일반 제공)로 전환되었습니다.

포함된 설정이 spec:inputs를 사용하고 파이프라인에 추가될 때, 입력 파라미터 값을 설정하려면 include:inputs를 사용합니다.

키워드 유형: 전역 키워드입니다.

지원되는 값: 문자열, 숫자 값 또는 불리언입니다.

include:inputs 예시:

include:
  - local: 'custom_configuration.yml'
    inputs:
      website: "My website"

이 예시에서:

• custom_configuration.yml에 포함된 설정이 파이프라인에 추가되며, 포함된 설정의 website 입력 값은 My website로 설정됩니다.

추가 정보:

• 포함된 설정 파일이 spec:inputs:type을 사용하는 경우, 입력 값은 정의된 유형과 일치해야 합니다.
• 포함된 설정 파일이 spec:inputs:options를 사용하는 경우, 입력 값은 나열된 옵션 중 하나와 일치해야 합니다.

관련 항목:

• include 사용 시 입력 값 설정하기.

---

include:rules#

rules를 include와 함께 사용하면 다른 설정 파일을 조건부로 포함할 수 있습니다.

키워드 유형: 전역 키워드.

지원되는 값: 다음 rules 하위 키:

• rules:if.
• rules:exists.
• rules:changes.

일부 CI/CD 변수를 사용할 수 있습니다.

include:rules의 예시:

include:
  - local: build_jobs.yml
    rules:
      - if: $INCLUDE_BUILDS == "true"

test-job:
  stage: test
  script: echo "This is a test job"

이 예시에서 INCLUDE_BUILDS 변수가 다음과 같으면:

• true이면 파이프라인에 build_jobs.yml 설정이 포함됩니다.
• true가 아니거나 존재하지 않으면 파이프라인에 build_jobs.yml 설정이 포함되지 않습니다.

관련 항목:

• include를 다음과 함께 사용하는 예시:
  • rules:if.
  • rules:changes.
  • rules:exists.

---

include:integrity#

히스토리

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

integrity를 include:remote와 함께 사용하면 포함된 원격 파일의 SHA256 해시를 지정할 수 있습니다. integrity가 실제 콘텐츠와 일치하지 않으면 원격 파일이 처리되지 않고 파이프라인이 실패합니다.

키워드 유형: 전역 키워드.

지원되는 값: 포함된 콘텐츠의 Base64 인코딩된 SHA256 해시입니다.

include:integrity의 예시:

include:
  - remote: 'https://gitlab.com/example-project/-/raw/main/.gitlab-ci.yml'
    integrity: 'sha256-L3/GAoKaw0Arw6hDCKeKQlV1QPEgHYxGBHsH4zG1IY8='

---

include:cache#

히스토리

• GitLab 18.9에서 실험 기능으로
• GitLab 19.0에서 일반 공급(GA)되었습니다. ci_cache_remote_includes 기능 플래그가 제거되었습니다.

cache를 include:remote와 함께 사용하면 가져온 원격 파일 콘텐츠를 캐시하여 HTTP 요청을 줄일 수 있습니다. 활성화하면 지정된 TTL(time-to-live) 동안 원격 파일이 캐시됩니다. 이 캐싱은 동일한 원격 include를 재사용하는 설정의 파이프라인 성능을 향상시킵니다.

캐시 기간을 설정할 때는 성능과 최신성 사이의 트레이드오프를 고려해야 합니다. 캐시 기간을 길게 설정하면 성능은 향상되지만, 원격 파일이 자주 변경되는 경우 오래된 콘텐츠를 사용할 수 있습니다.

cache를 정의하지 않으면 매번 원격 파일을 가져옵니다.

키워드 유형: 전역 키워드.

지원되는 값:

• true: 기본 TTL(time-to-live) 1시간으로 캐싱을 활성화합니다.
• 기간(문자열): 유효한 TTL 기간 문자열은 다음 시간 단위를 사용합니다 (minutes, hours, days, 최소 1 minute).

include:cache의 예시:

include:
  - remote: 'https://gitlab.com/example-project/-/raw/main/sample1.gitlab-ci.yml'
    cache: true
  - remote: 'https://gitlab.com/example-project/-/raw/main/sample2.gitlab-ci.yml'
    cache: '1 day'

추가 정보:

• 캐싱은 include:remote에만 사용할 수 있습니다.
• 원격 파일이 캐시된 후에는, TTL이 만료될 때까지 원격 파일 콘텐츠가 변경되더라도 캐시된 버전이 계속 사용됩니다.
• cache와 함께 integrity를 사용하면, 캐시된 콘텐츠를 사용하는 경우에도 파이프라인을 실행할 때마다 무결성 검사가 수행됩니다.

---

stages#

stages를 사용하면 job 그룹을 포함하는 스테이지를 정의할 수 있습니다. job이 특정 스테이지에서 실행되도록 설정하려면 job에서 stage를 사용합니다.

.gitlab-ci.yml 파일에 stages가 정의되어 있지 않으면 기본 파이프라인 스테이지는 다음과 같습니다:

• .pre
• build
• test
• deploy
• .post

stages에 나열된 항목의 순서가 job의 실행 순서를 정의합니다:

• 같은 스테이지의 job은 병렬로 실행됩니다.
• 다음 스테이지의 job은 이전 스테이지의 job이 모두 성공적으로 완료된 후 실행됩니다.

파이프라인에 .pre 또는 .post 스테이지의 job만 있으면 파이프라인이 실행되지 않습니다. 다른 스테이지에 최소 하나의 job이 더 있어야 합니다.

키워드 유형: 전역 키워드.

stages의 예시:

stages:
  - build
  - test
  - deploy

이 예시에서:

1. build의 모든 job이 병렬로 실행됩니다.
2. build의 모든 job이 성공하면 test job이 병렬로 실행됩니다.
3. test의 모든 job이 성공하면 deploy job이 병렬로 실행됩니다.
4. deploy의 모든 job이 성공하면 파이프라인이 passed로 표시됩니다.

job이 하나라도 실패하면 파이프라인은 failed로 표시되고 이후 스테이지의 job은 시작되지 않습니다. 현재 스테이지의 job은 중단되지 않고 계속 실행됩니다.

추가 정보:

• job이 stage를 지정하지 않으면 해당 job에는 test 스테이지가 할당됩니다.
• 스테이지가 정의되어 있지만 사용하는 job이 없으면 해당 스테이지는 파이프라인에 표시되지 않으며, 이는 컴플라이언스 파이프라인 설정에 도움이 될 수 있습니다:
  • 컴플라이언스 설정에서 스테이지를 정의할 수 있지만, 사용하지 않으면 숨겨진 상태로 유지됩니다.
  • 개발자가 job 정의에서 해당 스테이지를 사용하면 정의된 스테이지가 표시됩니다.

관련 항목:

• job을 더 일찍 시작하고 스테이지 순서를 무시하게 하려면 needs 키워드를 사용합니다.

---

workflow#

파이프라인 동작을 제어하려면 workflow를 사용합니다.

workflow 설정에서는 일부 사전 정의된 CI/CD 변수를 사용할 수 있지만, job이 시작될 때만 정의되는 변수는 사용할 수 없습니다.

관련 항목:

• workflow: rules examples
• 브랜치 파이프라인과 머지 리퀘스트 파이프라인 간 전환

---

workflow:auto_cancel:on_new_commit#

workflow:auto_cancel:on_new_commit을 사용하면 중복 파이프라인 자동 취소 기능의 동작을 설정할 수 있습니다.

지원되는 값:

• conservative: interruptible: false인 job이 아직 시작되지 않은 경우에만 파이프라인을 취소합니다. 정의하지 않았을 때의 기본값입니다.
• interruptible: interruptible: true인 job만 취소합니다.
• none: 어떤 job도 자동으로 취소하지 않습니다.

workflow:auto_cancel:on_new_commit의 예시:

workflow:
  auto_cancel:
    on_new_commit: interruptible

job1:
  interruptible: true
  script: sleep 60

job2:
  interruptible: false  # Default when not defined.
  script: sleep 60

이 예시에서:

• 브랜치에 새 커밋이 푸시되면 GitLab이 새 파이프라인을 생성하고 job1과 job2가 시작됩니다.
• job이 완료되기 전에 브랜치에 새 커밋이 푸시되면 job1만 취소됩니다.

---

workflow:auto_cancel:on_job_failure#

workflow:auto_cancel:on_job_failure를 사용하면 job이 하나라도 실패했을 때 즉시 취소할 job을 설정할 수 있습니다.

지원되는 값:

• all: job이 하나라도 실패하면 즉시 파이프라인과 실행 중인 모든 job을 취소합니다.
• none: 어떤 job도 자동으로 취소하지 않습니다.

workflow:auto_cancel:on_job_failure의 예시:

stages: [stage_a, stage_b]

workflow:
  auto_cancel:
    on_job_failure: all

job1:
  stage: stage_a
  script: sleep 60

job2:
  stage: stage_a
  script:
    - sleep 30
    - exit 1

job3:
  stage: stage_b
  script:
    - sleep 30

이 예시에서 job2가 실패하면, job1이 아직 실행 중이면 취소되고 job3은 시작되지 않습니다.

관련 항목:

• 다운스트림 파이프라인에서 상위 파이프라인 자동 취소

---

workflow:name#

workflow:에서 name을 사용하면 파이프라인의 이름을 정의할 수 있습니다.

모든 파이프라인에 정의된 이름이 할당됩니다. 이름의 앞뒤 공백은 제거됩니다.

지원되는 값:

• 문자열.
• CI/CD 변수.
• 둘의 조합.

workflow:name의 예시:

사전 정의된 변수를 사용한 파이프라인 이름:

workflow:
  name: 'Pipeline for branch: $CI_COMMIT_BRANCH'

파이프라인 조건에 따라 다른 파이프라인 이름을 사용하는 설정:

variables:
  PROJECT1_PIPELINE_NAME: 'Default pipeline name'  # A default is not required

workflow:
  name: '$PROJECT1_PIPELINE_NAME'
  rules:
    - if: '$CI_MERGE_REQUEST_LABELS =~ /pipeline:run-in-ruby3/'
      variables:
        PROJECT1_PIPELINE_NAME: 'Ruby 3 pipeline'
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      variables:
        PROJECT1_PIPELINE_NAME: 'MR pipeline: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME'
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH  # For default branch pipelines, use the default name

추가 정보:

• 이름이 빈 문자열이면 파이프라인에 이름이 할당되지 않습니다. CI/CD 변수로만 구성된 이름은 모든 변수가 비어 있으면 빈 문자열로 평가될 수 있습니다.
• workflow:rules:variables는 모든 job에서 사용할 수 있는 기본 변수가 되며, 기본적으로 다운스트림 파이프라인에 변수를 전달하는 trigger job도 포함됩니다. 다운스트림 파이프라인이 동일한 변수를 사용하면, 업스트림 변수 값에 의해 변수가 덮어써집니다. 다음 중 하나를 반드시 수행합니다:
  • PROJECT1_PIPELINE_NAME처럼 프로젝트마다 고유한 변수 이름을 파이프라인 설정에서 사용합니다.
  • trigger job에서 inherit:variables를 사용하고 다운스트림 파이프라인으로 전달할 정확한 변수를 나열합니다.

---

workflow:rules#

workflow의 rules 키워드는 job에서 정의하는 rules와 유사하지만, 파이프라인 전체를 생성할지 여부를 제어합니다.

어떤 규칙도 true로 평가되지 않으면 파이프라인이 실행되지 않습니다.

지원되는 값: job 수준의 rules와 동일한 키워드 중 일부를 사용할 수 있습니다:

• rules: if.
• rules: changes.
• rules: exists.
• when, workflow와 함께 사용할 때는 always 또는 never만 가능합니다.
• variables.

workflow:rules의 예시:

workflow:
  rules:
    - if: $CI_COMMIT_TITLE =~ /-draft$/
      when: never
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

이 예시에서는 커밋 제목(커밋 메시지의 첫 줄)이 -draft로 끝나지 않고 다음 중 하나에 해당하는 파이프라인일 경우 파이프라인이 실행됩니다:

• 머지 리퀘스트
• 기본 브랜치.

추가 정보:

• 규칙이 (기본 브랜치가 아닌) 브랜치 파이프라인과 머지 리퀘스트 파이프라인 둘 다에 일치하면 중복 파이프라인이 발생할 수 있습니다.
• start_in, allow_failure, needs는 workflow:rules에서 지원되지 않지만, 구문 위반을 일으키지는 않습니다. 효과는 없지만, 이후 구문 오류를 일으킬 수 있으므로 workflow:rules에서 사용하지 않아야 합니다. 자세한 내용은 이슈 436473을 참조합니다.

관련 항목:

• workflow:rules에 자주 사용되는 if 절.
• rules를 사용해 머지 리퀘스트 파이프라인 실행하기.

---

workflow:rules:variables#

workflow:rules에서 variables를 사용하면 특정 파이프라인 조건에 대한 변수를 정의할 수 있습니다.

조건이 일치하면 변수가 생성되어 파이프라인의 모든 job에서 사용할 수 있습니다. 변수가 이미 최상위 수준에서 기본 변수로 정의되어 있으면 workflow 변수가 우선하여 기본 변수를 재정의합니다.

키워드 유형: 전역 키워드.

지원되는 값: 변수 이름과 값 쌍:

• 이름에는 숫자, 문자, 밑줄(_)만 사용할 수 있습니다.
• 값은 문자열이어야 합니다.

workflow:rules:variables의 예시:

variables:
  DEPLOY_VARIABLE: "default-deploy"

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      variables:
        DEPLOY_VARIABLE: "deploy-production"  # Override globally-defined DEPLOY_VARIABLE
    - if: $CI_COMMIT_BRANCH =~ /feature/
      variables:
        IS_A_FEATURE: "true"                  # Define a new variable.
    - if: $CI_COMMIT_BRANCH                   # Run the pipeline in other cases

job1:
  variables:
    DEPLOY_VARIABLE: "job1-default-deploy"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      variables:                                   # Override DEPLOY_VARIABLE defined
        DEPLOY_VARIABLE: "job1-deploy-production"  # at the job level.
    - when: on_success                             # Run the job in other cases
  script:
    - echo "Run script with $DEPLOY_VARIABLE as an argument"
    - echo "Run another script if $IS_A_FEATURE exists"

job2:
  script:
    - echo "Run script with $DEPLOY_VARIABLE as an argument"
    - echo "Run another script if $IS_A_FEATURE exists"

브랜치가 기본 브랜치인 경우:

• job1의 DEPLOY_VARIABLE은 job1-deploy-production입니다.
• job2의 DEPLOY_VARIABLE은 deploy-production입니다.

브랜치가 feature인 경우:

• job1의 DEPLOY_VARIABLE은 job1-default-deploy이고, IS_A_FEATURE는 true입니다.
• job2의 DEPLOY_VARIABLE은 default-deploy이고, IS_A_FEATURE는 true입니다.

브랜치가 그 외의 경우:

• job1의 DEPLOY_VARIABLE은 job1-default-deploy입니다.
• job2의 DEPLOY_VARIABLE은 default-deploy입니다.

추가 정보:

• workflow:rules:variables는 모든 job에서 사용할 수 있는 기본 변수가 되며, 기본적으로 다운스트림 파이프라인에 변수를 전달하는 trigger job도 포함됩니다. 다운스트림 파이프라인이 동일한 변수를 사용하면, 업스트림 변수 값에 의해 변수가 덮어써집니다. 다음 중 하나를 반드시 수행합니다:
  • PROJECT1_VARIABLE_NAME처럼 프로젝트마다 고유한 변수 이름을 파이프라인 설정에서 사용합니다.
  • trigger job에서 inherit:variables를 사용하고 다운스트림 파이프라인으로 전달할 정확한 변수를 나열합니다.

---

workflow:rules:auto_cancel#

workflow:rules:auto_cancel을 사용하면 workflow:auto_cancel:on_new_commit 또는 workflow:auto_cancel:on_job_failure 기능의 동작을 설정할 수 있습니다.

지원되는 값:

• on_new_commit: workflow:auto_cancel:on_new_commit
• on_job_failure: workflow:auto_cancel:on_job_failure

workflow:rules:auto_cancel의 예시:

workflow:
  auto_cancel:
    on_new_commit: interruptible
    on_job_failure: all
  rules:
    - if: $CI_COMMIT_REF_PROTECTED == 'true'
      auto_cancel:
        on_new_commit: none
        on_job_failure: none
    - when: always                  # Run the pipeline in other cases

test-job1:
  script: sleep 10
  interruptible: false

test-job2:
  script: sleep 10
  interruptible: true

이 예시에서 workflow:auto_cancel:on_new_commit은 기본적으로 모든 job에 대해 interruptible로 설정되고, workflow:auto_cancel:on_job_failure는 all로 설정됩니다. 하지만 파이프라인이 보호된 브랜치에서 실행되면, 규칙이 기본값을 on_new_commit: none과 on_job_failure: none으로 재정의합니다. 예를 들어 파이프라인이 다음에 대해 실행되는 경우:

• 보호되지 않은 브랜치이고 새 커밋이 푸시되면, test-job1은 계속 실행되고 test-job2는 취소됩니다.
• 보호된 브랜치이고 새 커밋이 푸시되면, test-job1과 test-job2 모두 계속 실행됩니다.

---

Header keywords#

일부 키워드는 YAML 설정 파일의 헤더 섹션에 정의해야 합니다. 헤더는 파일의 맨 위에 있어야 하며, 나머지 설정과는 ---로 구분되어야 합니다.

---

spec#

YAML 파일 헤더에 spec 섹션을 추가하면 해당 파일을 포함하는 파이프라인의 동작을 제어할 수 있습니다.

Spec는 구성 파일의 맨 위, 나머지 구성과 ---로 구분된 헤더 섹션에 선언해야 합니다.

---

spec:inputs#

spec:inputs를 사용하면 CI/CD 구성의 입력을 정의할 수 있습니다.

헤더 섹션 밖에서 값을 참조하려면 보간 형식 $[[ inputs.input-id ]]를 사용합니다.

입력은 파이프라인 생성 중 구성을 가져올 때 평가되고 보간됩니다. inputs를 사용할 때 보간은 구성이 .gitlab-ci.yml 파일의 내용과 병합되기 전에 완료됩니다.

키워드 유형: 헤더 키워드입니다. spec은 구성 파일의 맨 위, 헤더 섹션에 선언해야 합니다.

지원되는 값: 예상되는 입력을 나타내는 문자열 해시입니다.

spec:inputs 예시:

spec:
  inputs:
    environment:
    job-stage:
---

scan-website:
  stage: $[[ inputs.job-stage ]]
  script: ./scan-website $[[ inputs.environment ]]

추가 세부 사항:

• spec:inputs:default로 기본값을 설정하지 않는 한 입력은 필수입니다. include:inputs와 함께만 입력을 사용하는 경우가 아니라면 필수 입력은 피합니다.
• spec:inputs:type로 다른 입력 유형을 설정하지 않는 한 입력은 문자열을 기대합니다.
• 보간 블록을 포함하는 문자열은 1MB를 초과할 수 없습니다.
• 보간 블록 내부의 문자열은 1KB를 초과할 수 없습니다.
• 새 파이프라인을 실행할 때 입력 값을 정의할 수 있습니다.

관련 주제:

• spec:inputs로 입력 매개변수 정의하기.

---

spec:inputs:default#

spec:inputs:default로 기본값을 설정하지 않으면 입력은 포함될 때 필수입니다.

기본값이 없도록 하려면 default: ''를 사용합니다.

키워드 유형: 헤더 키워드입니다. spec은 구성 파일의 맨 위, 헤더 섹션에 선언해야 합니다.

지원되는 값: 기본값을 나타내는 문자열, 또는 ''입니다.

spec:inputs:default 예시:

spec:
  inputs:
    website:
    user:
      default: 'test-user'
    flags:
      default: ''
---
# The pipeline configuration would follow...

이 예시에서:

• website는 필수이며 반드시 정의해야 합니다.
• user는 선택 사항입니다. 정의하지 않으면 값은 test-user입니다.
• flags는 선택 사항입니다. 정의하지 않으면 값이 없습니다.

추가 세부 사항:

• 다음 경우 파이프라인은 검증 오류와 함께 실패합니다.
  • default와 options를 모두 사용하지만 기본값이 나열된 옵션 중 하나가 아닌 경우.
  • default와 regex를 모두 사용하지만 기본값이 정규 표현식과 일치하지 않는 경우.
  • 값이 type과 일치하지 않는 경우.

---

spec:inputs:description#

특정 입력에 설명을 붙이려면 description을 사용합니다. 이 설명은 입력의 동작에 영향을 주지 않으며, 파일을 사용하는 사람이 입력을 이해하는 데 도움을 주기 위해서만 사용됩니다.

키워드 유형: 헤더 키워드입니다. spec은 구성 파일의 맨 위, 헤더 섹션에 선언해야 합니다.

지원되는 값: 설명을 나타내는 문자열입니다.

spec:inputs:description 예시:

spec:
  inputs:
    flags:
      description: 'Sample description of the `flags` input details.'
---
# The pipeline configuration would follow...

---

spec:inputs:options#

히스토리

• 배열 유형 입력 지원이 GitLab 19.0에서 도입되었습니다.

입력은 options를 사용하여 허용되는 값의 목록을 지정할 수 있습니다. 입력당 옵션 한도는 50개입니다.

키워드 유형: 헤더 키워드입니다. spec은 구성 파일의 맨 위, 헤더 섹션에 선언해야 합니다.

지원되는 값: 입력 옵션의 배열입니다.

spec:inputs:options 예시:

spec:
  inputs:
    environment:
      options:
        - development
        - staging
        - production
---
# The pipeline configuration would follow...

이 예시에서:

• environment는 필수이며 목록에 있는 값 중 하나로 정의해야 합니다.

추가 세부 사항:

• 다음 경우 파이프라인은 검증 오류와 함께 실패합니다.
  • 입력이 options와 default를 모두 사용하지만 기본값이 나열된 옵션 중 하나가 아닌 경우.
  • 입력 옵션 중 하나라도 type과 일치하지 않는 경우, 이때 type은 string 또는 number일 수 있으나 options 사용 시 boolean은 아닙니다.

---

spec:inputs:regex#

입력이 일치해야 하는 정규 표현식을 지정하려면 spec:inputs:regex를 사용합니다.

키워드 유형: 헤더 키워드입니다. spec은 구성 파일의 맨 위, 헤더 섹션에 선언해야 합니다.

지원되는 값: 정규 표현식이어야 합니다.

spec:inputs:regex 예시:

spec:
  inputs:
    version:
      regex: ^v\d\.\d+(\.\d+)?$
---
# The pipeline configuration would follow...

이 예시에서 v1.0 또는 v1.2.3 입력은 정규 표현식과 일치하여 검증을 통과합니다. v1.A.B 입력은 정규 표현식과 일치하지 않아 검증에 실패합니다.

추가 세부 사항:

• inputs:regex는 type이 string인 경우에만 사용할 수 있으며, number나 boolean에는 사용할 수 없습니다.
• 정규 표현식을 / 문자로 감싸지 않습니다. 예를 들어 /regex.*/가 아니라 regex.*를 사용합니다.
• inputs:regex는 정규 표현식을 파싱하는 데 RE2를 사용합니다.
• 정규 표현식에 대한 입력 검증은 변수 확장 전에 이루어집니다. 입력 텍스트에 변수 이름이 포함된 경우, 변수 값이 아니라 입력의 원시 값(변수 이름)이 검증됩니다.

---

spec:inputs:rules#

히스토리

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

다른 입력의 값을 기준으로 조건부 options와 default 값을 정의하려면 spec:inputs:rules를 사용합니다.

키워드 유형: 헤더 키워드입니다. spec은 구성 파일의 맨 위, 헤더 섹션에 선언해야 합니다.

지원되는 값: 규칙 객체의 배열입니다. 각 규칙은 다음을 가질 수 있습니다.

• if: $[[ inputs.input-id ]] 구문을 사용해 입력 값을 확인하는 조건식입니다.
• options: 입력에 허용되는 값의 배열입니다.
• default: 이 규칙이 일치할 때 입력에 적용되는 기본값입니다. 사용자가 입력에 직접 값을 입력할 수 있게 하려면 default: null을 사용합니다.

spec:inputs:rules 예시:

spec:
  inputs:
    environment:
      options: ['development', 'production']
      default: 'development'

    instance_type:
      description: 'VM instance size'
      rules:
        - if: $[[ inputs.environment ]] == 'development'
          options: ['small', 'medium']
          default: 'small'
        - if: $[[ inputs.environment ]] == 'production'
          options: ['large', 'xlarge']
          default: 'large'
---

deploy:
  script: echo "Deploying $[[ inputs.instance_type ]] instance"

이 예시에서 environment가 development이면 사용자는 small 또는 medium 인스턴스만 선택할 수 있습니다. environment가 production이면 large 또는 xlarge 인스턴스만 사용할 수 있습니다.

추가 세부 사항:

• 규칙은 순서대로 평가됩니다. if 조건이 일치하는 첫 번째 규칙이 사용됩니다.
• if 조건이 없는 규칙은 다른 규칙이 일치하지 않을 때 폴백 역할을 합니다.
• 폴백 규칙은 options를 최소 한 개 이상의 값으로 정의해야 합니다.
• options가 있는 모든 규칙은 options 목록에 존재하는 default 값도 함께 정의해야 합니다.
• 같은 입력에 rules와 최상위 options 또는 default를 함께 사용할 수 없습니다.

관련 주제:

• spec:inputs:rules로 조건부 입력 옵션 정의하기.

---

spec:inputs:type#

기본적으로 입력은 문자열을 기대합니다. 입력에 다른 필수 유형을 설정하려면 spec:inputs:type을 사용합니다.

키워드 유형: 헤더 키워드입니다. spec은 구성 파일의 맨 위, 헤더 섹션에 선언해야 합니다.

지원되는 값: 다음 중 하나일 수 있습니다.

• array: 입력의 배열을 허용합니다.
• string: 문자열 입력을 허용합니다(정의하지 않을 때의 기본값).
• number: 숫자 입력만 허용합니다.
• boolean: true 또는 false 입력만 허용합니다.

spec:inputs:type 예시:

spec:
  inputs:
    job_name:
    website:
      type: string
    port:
      type: number
    available:
      type: boolean
    array_input:
      type: array
---
# The pipeline configuration would follow...

---

spec:include#

히스토리

• GitLab 18.6에서 ci_file_inputs라는 이름의 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 18.9에서 일반 공급(GA)되었습니다. 기능 플래그 ci_file_inputs가 제거되었습니다.
• GitLab 19.4에서 ci_spec_include_own_context라는 이름의 기능 플래그와 함께 변경되었습니다. 기본적으로 비활성화되어 있습니다.

다른 파일의 외부 입력 정의를 포함하려면 spec:include를 사용합니다. 여러 파이프라인 구성에서 입력 정의를 공유하고 재사용할 수 있습니다.

키워드 유형: 헤더 키워드입니다. spec은 구성 파일의 맨 위, 헤더 섹션에 선언해야 합니다.

지원되는 값: 포함 위치의 배열입니다. local, remote, project 포함만 지원합니다.

spec:include 예시:

spec:
  include:
    - local: /shared-inputs.yml
  inputs:
    environment:
      default: production
---

deploy:
  script: echo "Deploying to $[[ inputs.environment ]]"

서로 다른 소스에서 여러 개를 포함하는 경우:

spec:
  include:
    - local: /base-inputs.yml
    - remote: 'https://example.com/ci/common-inputs.yml'
    - project: 'my-group/shared-configs'
      ref: main
      file: '/ci/team-inputs.yml'
  inputs:
    environment:
      default: production
---

deploy:
  script: echo "Deploying to $[[ inputs.environment ]]"

추가 세부 사항:

• CI/CD 컴포넌트에서는 spec:include를 사용할 수 없습니다.
• 외부 입력 파일에는 inputs 키만 있어야 합니다. 다른 키가 있으면 검증 오류가 발생합니다.
• 외부 입력이 먼저 병합된 다음 인라인 입력이 적용됩니다.
• 인라인 입력은 포함된 입력과 같은 이름을 가질 수 없습니다.
• 여러 입력 파일을 포함하면 지정한 순서대로 병합됩니다.
• local, remote, project 포함 유형을 지원합니다. template, component, artifact 포함은 지원하지 않습니다.
• 포함 위치는 포함한 파일이 아니라 spec 섹션을 담고 있는 파일의 리포지터리와 ref를 기준으로 해석됩니다. local 위치는 spec:include를 선언한 파일을 기준으로 합니다.
• include:remote 또는 include:template로 추가한 파일에서는 local 위치를 사용할 수 없습니다. 이런 파일은 기준으로 삼을 리포지터리가 없기 때문입니다. 대신 include:project를 사용합니다.

관련 주제:

• 외부 파일의 입력 사용하기.

---

spec:component#

히스토리

• GitLab 18.6에서 베타로, ci_component_context_interpolation이라는 이름의 기능 플래그와 함께 도입되었습니다. 기본적으로 활성화되어 있습니다.
• GitLab 18.7에서 일반 공급(GA)되었습니다. 기능 플래그 ci_component_context_interpolation이 제거되었습니다.

CI/CD 컴포넌트에서 보간에 사용할 수 있는 컴포넌트 컨텍스트 데이터를 정의하려면 spec:component를 사용합니다.

컴포넌트 컨텍스트는 이름, 버전, 커밋 SHA 등 컴포넌트 자체에 대한 메타데이터를 제공합니다. 이를 통해 컴포넌트 템플릿이 자신의 메타데이터를 동적으로 참조할 수 있습니다.

컴포넌트 템플릿에서 컴포넌트 컨텍스트 값을 참조하려면 보간 형식 $[[ component.field-name ]]을 사용합니다.

키워드 유형: 헤더 키워드입니다. spec은 구성 파일의 맨 위, 헤더 섹션에 선언해야 합니다.

지원되는 값: 문자열의 배열입니다. 각 문자열은 다음 중 하나여야 합니다.

• name: 컴포넌트 경로에 지정된 컴포넌트 이름입니다.
• sha: 컴포넌트의 커밋 SHA 입니다.
• version: 카탈로그 리소스에서 확인된 시맨틱 버전입니다. 다음의 경우 null을 반환합니다.
  • 컴포넌트가 카탈로그 리소스가 아닌 경우.
  • 참조가 (릴리스된 버전이 아니라) 브랜치 이름이나 커밋 SHA 인 경우.
• reference: 컴포넌트 경로에서 @ 뒤에 지정된 원본 참조입니다. 예를 들어 1.0, ~latest, 브랜치 이름, 커밋 SHA 등입니다.

spec:component 예시:

spec:
  component: [name, version, reference]
  inputs:
    stage:
      default: build
---

build-image:
  stage: $[[ inputs.stage ]]
  image: registry.example.com/$[[ component.name ]]:$[[ component.version ]]
  script:
    - echo "Building with component version $[[ component.version ]]"
    - echo "Component reference: $[[ component.reference ]]"

추가 세부 사항:

• version 필드는 다음을 사용할 때 실제 시맨틱 버전으로 확인됩니다.
  • @1.0.0과 같은 전체 버전 (1.0.0을 반환)
  • @1.0과 같은 부분 버전 (일치하는 최신 버전을 반환, 예: 1.0.2)
  • @~latest (최신 버전을 반환)
• reference 필드는 항상 @ 뒤에 지정된 값을 그대로 반환합니다.
  • @1.0은 1.0을 반환합니다(version은 1.0.2를 반환할 수 있음)
  • @~latest는 ~latest를 반환합니다(version은 실제 버전 번호를 반환함)
  • @abc123은 abc123을 반환합니다(version은 null을 반환함)

관련 주제:

• 컴포넌트에서 컴포넌트 컨텍스트 사용하기.

---

spec:description#

히스토리

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

컴포넌트에 대한 간단한 설명을 제공하려면 spec:description을 사용합니다. 이 설명은 CI/CD 카탈로그의 컴포넌트 상세 페이지에서 입력 테이블 위에 표시됩니다.

키워드 유형: 헤더 키워드입니다. spec은 구성 파일의 맨 위, 헤더 섹션에 선언해야 합니다.

지원되는 값: 컴포넌트를 설명하는 문자열입니다.

spec:description 예시:

spec:
  description: "A description of the component visible to users in the CI/CD Catalog."
  inputs:
    stage:
      default: test
---
scan-job:
  stage: $[[ inputs.stage ]]
  script: ./run-scan.sh

---

Job 키워드#

다음 항목에서는 키워드를 사용하여 CI/CD 파이프라인을 구성하는 방법을 설명합니다.

---

after_script#

히스토리

• 취소된 job에 대해 after_script 명령을 실행하는 기능이 GitLab 17.0에서 도입되었습니다.

after_script를 사용하면 job의 before_script와 script 섹션이 완료된 후 마지막으로 실행할 명령 배열을 정의할 수 있습니다. after_script 명령은 다음의 경우에도 실행됩니다.

• before_script 또는 script 섹션이 아직 실행 중일 때 job이 취소된 경우
• job이 script_failure 실패 유형으로 실패한 경우(다른 실패 유형은 제외)

job 설정과 기본(default) 설정은 병합되지 않습니다. 파이프라인에 default:after_script가 정의되어 있고 job에도 after_script가 있는 경우, job 설정이 우선 적용되며 기본 설정은 사용되지 않습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값: 다음을 포함하는 배열입니다.

• 한 줄 명령
• 여러 줄로 나눈 긴 명령
• YAML 앵커

CI/CD 변수가 지원됩니다.

after_script 예시:

job:
  script:
    - echo "An example script section."
  after_script:
    - echo "Execute this command after the `script` section completes."

추가 세부정보:

after_script에 지정한 스크립트는 before_script나 script 명령과는 별도로 새로운 셸에서 실행됩니다. 그 결과 다음과 같은 특징이 있습니다.

• 현재 작업 디렉터리가 기본값으로 재설정됩니다(러너가 Git 요청을 처리하는 방식을 정의하는 변수 참고).
• before_script나 script에 정의된 명령이 수행한 변경 사항에 접근할 수 없습니다. 여기에는 다음이 포함됩니다.
  • script 스크립트에서 내보낸(export) 명령 별칭 및 변수
  • (러너 executor에 따라) 작업 트리 외부의 변경 사항, 예를 들어 before_script나 script 스크립트가 설치한 소프트웨어
• 별도의 타임아웃이 있습니다. 기본값은 5분이며 RUNNER_AFTER_SCRIPT_TIMEOUT 변수로 설정할 수 있습니다.
• job의 종료 코드에 영향을 주지 않습니다. script 섹션이 성공하고 after_script가 타임아웃되거나 실패해도, job은 코드 0(Job Succeeded)으로 종료됩니다.
• 타임아웃되는 job의 경우:
  • after_script 명령은 기본적으로 실행되지 않습니다.
  • job의 타임아웃을 초과하지 않는 적절한 RUNNER_SCRIPT_TIMEOUT 및 RUNNER_AFTER_SCRIPT_TIMEOUT 값을 설정하여 after_script가 실행되도록 타임아웃 값을 구성할 수 있습니다.
• default 섹션이 아닌 최상위 수준에서 after_script를 사용하는 것은 더 이상 사용되지 않습니다(deprecated).

실행 시점 및 파일 포함:

after_script 명령은 캐시 및 아티팩트 업로드 작업 이전에 실행됩니다.

• 아티팩트 수집을 구성한 경우:
  • after_script에서 생성하거나 수정한 파일은 아티팩트에 포함됩니다.
  • after_script에서 수행한 변경 사항은 캐시 업로드에 포함됩니다.
• after_script가 지정된 캐시 또는 아티팩트 경로에서 생성하거나 수정하는 파일은 캡처되어 업로드됩니다. 이 시점을 다음과 같은 시나리오에 활용할 수 있습니다.
  • 메인 스크립트 이후 테스트 리포트나 커버리지 데이터 생성
  • 요약 파일 또는 로그 생성
  • 빌드 결과물 후처리

다음 예시에서 포함되지 않는 파일은 아티팩트 또는 캐시 업로드 단계 이후에 생성되거나 수정된 파일뿐입니다.

job:
  script:
    - echo "main" > output.txt
    - build_something

  after_script:
    - echo "modified in after_script" >> output.txt  # This WILL be in the artifact
    - generate_test_report > report.html            # This WILL be in the artifact

  artifacts:
    paths:
      - output.txt
      - report.html

  cache:
    paths:
      - output.txt  # Will include the "modified in after_script" line

자세한 내용은 job 실행 흐름을 참고합니다.

관련 주제:

• 모든 job 이후에 실행할 기본 명령 배열을 정의하려면 default와 함께 after_script 사용을 참고합니다.
• job이 취소된 경우 after_script 명령을 건너뛰도록 job을 구성할 수 있습니다.
• 0이 아닌 종료 코드를 무시할 수 있습니다.
• job 로그를 더 쉽게 검토할 수 있도록 after_script에 색상 코드를 사용할 수 있습니다.
• job 로그 출력을 단순화하려면 사용자 지정 접이식 섹션 생성을 참고합니다.
• after_script의 오류를 무시할 수 있습니다.

---

allow_failure#

allow_failure를 사용하면 job이 실패했을 때 파이프라인을 계속 실행할지 여부를 결정할 수 있습니다.

• 파이프라인이 이후 job을 계속 실행하도록 하려면 allow_failure: true를 사용합니다.
• 파이프라인이 이후 job을 실행하지 않도록 하려면 allow_failure: false를 사용합니다.

job의 실패가 허용된 경우(allow_failure: true) 주황색 경고([status_warning])가 표시되어 job이 실패했음을 나타냅니다. 하지만 파이프라인은 성공하며, 관련 커밋은 경고 없이 통과로 표시됩니다.

다음의 경우에도 동일한 경고가 표시됩니다.

• 해당 stage의 다른 모든 job이 성공한 경우
• 파이프라인의 다른 모든 job이 성공한 경우

allow_failure의 기본값은 다음과 같습니다.

• 수동 job의 경우 true
• rules 내에서 when: manual을 사용하는 job의 경우 false
• 그 외의 모든 경우 false

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• true 또는 false

allow_failure 예시:

job1:
  stage: test
  script:
    - execute_script_1

job2:
  stage: test
  script:
    - execute_script_2
  allow_failure: true

job3:
  stage: deploy
  script:
    - deploy_to_staging
  environment: staging

이 예시에서 job1과 job2는 병렬로 실행됩니다.

• job1이 실패하면 deploy stage의 job이 시작되지 않습니다.
• job2가 실패해도 deploy stage의 job은 시작될 수 있습니다.

추가 세부정보:

• allow_failure는 rules의 하위 키로 사용할 수 있습니다.
• allow_failure: true가 설정되면 해당 job은 항상 성공한 것으로 간주되며, 이 job이 실패해도 when: on_failure를 사용하는 이후 job은 시작되지 않습니다.
• 수동 job에 allow_failure: false를 사용하면 차단 수동 job(blocking manual job)을 만들 수 있습니다. 차단된 파이프라인은 해당 수동 job이 시작되어 성공적으로 완료될 때까지 이후 stage의 job을 실행하지 않습니다.

---

allow_failure:exit_codes#

allow_failure:exit_codes를 사용하면 job의 실패를 허용할 시점을 제어할 수 있습니다. 나열된 종료 코드 중 하나에 해당하면 job은 allow_failure: true가 되고, 그 외의 종료 코드에서는 allow_failure가 false가 됩니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• 단일 종료 코드
• 종료 코드 배열

allow_failure 예시:

test_job_1:
  script:
    - echo "Run a script that results in exit code 1. This job fails."
    - exit 1
  allow_failure:
    exit_codes: 137

test_job_2:
  script:
    - echo "Run a script that results in exit code 137. This job is allowed to fail."
    - exit 137
  allow_failure:
    exit_codes:
      - 137
      - 255

---

artifacts#

히스토리

• GitLab Runner 18.1에서 업데이트되었습니다. 캐싱 과정에서

artifacts를 사용하여 job 아티팩트로 저장할 파일을 지정합니다. job 아티팩트는 job이 성공하거나, 실패하거나, 항상 job에 첨부되는 파일 및 디렉터리 목록입니다.

아티팩트는 job이 끝난 후 GitLab으로 전송됩니다. 크기가 최대 아티팩트 크기보다 작으면 GitLab UI에서 다운로드할 수 있습니다.

기본적으로 이후 stage의 job은 이전 stage의 job이 생성한 모든 아티팩트를 자동으로 다운로드합니다. dependencies를 사용해 job의 아티팩트 다운로드 동작을 제어할 수 있습니다.

needs 키워드를 사용하는 경우, job은 needs 설정에 정의된 job의 아티팩트만 다운로드할 수 있습니다.

job 아티팩트는 기본적으로 성공한 job에 대해서만 수집되며, 아티팩트는 캐시 이후에 복원됩니다.

job 설정과 기본 설정은 병합되지 않습니다. 파이프라인에 default:artifacts가 정의되어 있고 job에도 artifacts가 있는 경우, job 설정이 우선 적용되며 기본 설정은 사용되지 않습니다.

아티팩트에 대해 자세히 알아보기.

---

artifacts:paths#

경로는 프로젝트 디렉터리($CI_PROJECT_DIR)를 기준으로 하며 해당 디렉터리 외부를 직접 가리킬 수 없습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• 프로젝트 디렉터리 기준의 파일 경로 배열
• glob 패턴 및 doublestar.Glob 패턴을 사용하는 와일드카드를 사용할 수 있습니다.
• GitLab Pages job의 경우:
  • GitLab 17.10 이상에서는 pages.publish 경로가 artifacts:paths에 자동으로 추가되므로 다시 지정할 필요가 없습니다.
  • GitLab 17.10 이상에서는 pages.publish 경로가 지정되지 않은 경우 public 디렉터리가 artifacts:paths에 자동으로 추가됩니다.

CI/CD 변수가 지원됩니다.

artifacts:paths 예시:

job:
  artifacts:
    paths:
      - binaries/
      - .config

이 예시는 .config와 binaries 디렉터리의 모든 파일로 아티팩트를 생성합니다.

추가 세부정보:

• artifacts:name과 함께 사용하지 않으면 아티팩트 파일 이름은 artifacts가 되며, 다운로드 시 artifacts.zip이 됩니다.

관련 주제:

• 특정 job이 어떤 job으로부터 아티팩트를 가져올지 제한하려면 dependencies를 참고합니다.
• job 아티팩트 생성.

---

artifacts:exclude#

artifacts:exclude를 사용하면 파일이 아티팩트 아카이브에 추가되지 않도록 할 수 있습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• 프로젝트 디렉터리 기준의 파일 경로 배열
• glob 또는 doublestar.PathMatch 패턴을 사용하는 와일드카드를 사용할 수 있습니다.

artifacts:exclude 예시:

artifacts:
  paths:
    - binaries/
  exclude:
    - binaries/**/*.o

이 예시는 binaries/의 모든 파일을 저장하지만, binaries/의 하위 디렉터리에 있는 *.o 파일은 저장하지 않습니다.

추가 세부정보:

• artifacts:exclude 경로는 재귀적으로 검색되지 않습니다.
• artifacts:untracked에 매칭된 파일도 artifacts:exclude로 제외할 수 있습니다.

관련 주제:

• job 아티팩트에서 파일 제외.

---

artifacts:expire_in#

expire_in을 사용하면 job 아티팩트가 만료되어 삭제되기까지 저장되는 기간을 지정할 수 있습니다. expire_in 설정은 다음에는 영향을 미치지 않습니다.

• 프로젝트 단위 또는 인스턴스 전체로 최신 job 아티팩트를 보관하는 기능이 비활성화되지 않은 한, 최신 job의 아티팩트

만료 후 아티팩트는 기본적으로 매시간(cron job을 통해) 삭제되며 더 이상 접근할 수 없습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값: 만료 시간입니다. 단위를 지정하지 않으면 초 단위로 처리됩니다. 유효한 값은 다음과 같습니다.

• '42'
• 42 seconds
• 3 mins 4 sec
• 2 hrs 20 min
• 2h20min
• 6 mos 1 day
• 47 yrs 6 mos and 4d
• 3 weeks and 2 days
• never

artifacts:expire_in 예시:

job:
  artifacts:
    expire_in: 1 week

추가 세부정보:

• 만료 기간은 아티팩트가 업로드되어 GitLab에 저장되는 시점부터 시작됩니다. 만료 시간이 정의되지 않은 경우 인스턴스 전체 설정이 기본값으로 사용됩니다.
• 만료 날짜를 재정의하여 아티팩트가 자동으로 삭제되지 않도록 보호하려면:
  • job 페이지에서 Keep을 선택합니다.
  • expire_in 값을 never로 설정합니다.
• 만료 시간이 너무 짧으면 긴 파이프라인의 이후 stage에 있는 job이 이전 job의 만료된 아티팩트를 가져오려고 시도할 수 있습니다. 아티팩트가 만료된 경우, 이를 가져오려는 job은 could not retrieve the needed artifacts 오류와 함께 실패합니다. 만료 시간을 더 길게 설정하거나, 이후 job에서 dependencies를 사용하여 만료된 아티팩트를 가져오려 시도하지 않도록 합니다.
• artifacts:expire_in은 GitLab Pages 배포에는 영향을 주지 않습니다. Pages 배포의 만료를 설정하려면 pages.expire_in을 사용합니다.

---

artifacts:expose_as#

artifacts:expose_as 키워드를 사용하면 머지 리퀘스트 UI에 아티팩트를 노출할 수 있습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• 머지 리퀘스트 UI에서 아티팩트 다운로드 링크에 표시할 이름입니다. artifacts:paths와 함께 사용해야 합니다.

artifacts:expose_as 예시:

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

추가 세부정보:

• expose_as는 job당 한 번만 사용할 수 있으며, 머지 리퀘스트당 최대 10개의 job까지 사용할 수 있습니다.
• glob 패턴은 지원되지 않습니다.
• 아티팩트는 항상 GitLab으로 전송됩니다. 다음에 해당하지 않는 한 UI에 표시됩니다.
  • artifacts:paths 값이 CI/CD 변수를 사용하는 경우
  • artifacts:paths 값이 디렉터리를 정의하지만 /로 끝나지 않는 경우. 예를 들어 directory/는 artifacts:expose_as와 함께 작동하지만, directory는 작동하지 않습니다.
• artifacts:paths에 파일이 하나만 포함된 경우 링크를 클릭하면 해당 파일이 바로 열립니다. 그 외의 모든 경우에는 링크가 아티팩트 브라우저를 엽니다.
• 링크된 파일은 기본적으로 다운로드됩니다. GitLab Pages가 활성화된 경우 일부 아티팩트 파일 확장자는 브라우저에서 바로 미리 볼 수 있습니다. 자세한 내용은 아티팩트 아카이브 콘텐츠 탐색을 참고합니다.

관련 주제:

• 머지 리퀘스트 UI에 job 아티팩트 노출.

---

artifacts:name#

artifacts:name 키워드를 사용하면 생성되는 아티팩트 아카이브의 이름을 정의할 수 있습니다. 아카이브마다 고유한 이름을 지정할 수 있습니다.

정의하지 않으면 기본 이름은 artifacts이며, 다운로드 시 artifacts.zip이 됩니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• 아티팩트 아카이브의 이름입니다. CI/CD 변수가 지원됩니다. artifacts:paths와 함께 사용해야 합니다.

artifacts:name 예시:

현재 job의 이름으로 아카이브를 생성하려면:

job:
  artifacts:
    name: "job1-artifacts-file"
    paths:
      - binaries/

관련 주제:

• CI/CD 변수를 사용해 아티팩트 설정 정의

---

artifacts:public#

artifacts:public을 사용하면 공개 파이프라인의 job 아티팩트를 익명 사용자나 Guest, Reporter 권한이 GitLab UI 및 API로 다운로드할 수 있는지 여부를 제어할 수 있습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• true(기본값): 공개 파이프라인의 job 아티팩트는 익명 사용자, Guest, Reporter 권한을 포함해 누구나 다운로드할 수 있습니다.
• false: job 아티팩트는 Developer, Maintainer, Owner 권한을 가진 사용자만 다운로드할 수 있습니다.

artifacts:public 예시:

job:
  artifacts:
    public: false

---

artifacts:access#

히스토리

• maintainer 옵션이 GitLab 18.4에서 도입되었습니다.

artifacts:access를 사용하면 job 아티팩트를 GitLab UI 또는 API에서 누가 접근할 수 있는지 결정할 수 있습니다. 이 옵션은 다운스트림 파이프라인으로 아티팩트를 전달하는 것을 막지는 않습니다.

같은 job에서 artifacts:public과 artifacts:access를 함께 사용할 수 없습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• all(기본값): 퍼블릭 파이프라인의 job에 있는 아티팩트는 익명 사용자, 게스트, 리포터를 포함해 누구나 다운로드할 수 있습니다.
• developer: job의 아티팩트는 Developer, Maintainer, Owner 권한을 가진 사용자만 다운로드할 수 있습니다.
• maintainer: job의 아티팩트는 Maintainer 또는 Owner 권한을 가진 사용자만 다운로드할 수 있습니다.
• none: job의 아티팩트는 누구도 다운로드할 수 없습니다.

artifacts:access 예시:

job:
  artifacts:
    access: 'developer'

추가 세부 정보:

• artifacts:access는 artifacts:reports에도 모두 영향을 미치므로, 리포트용 아티팩트에 대한 접근도 제한할 수 있습니다.

---

artifacts:reports#

artifacts:reports를 사용하면 job에 포함된 템플릿이 생성한 아티팩트를 수집할 수 있습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• 사용 가능한 아티팩트 리포트 유형 목록을 참조합니다.

artifacts:reports 예시:

rspec:
  stage: test
  script:
    - bundle install
    - rspec --format RspecJunitFormatter --out rspec.xml
  artifacts:
    reports:
      junit: rspec.xml

추가 세부 정보:

• 자식 파이프라인의 아티팩트를 사용해 상위 파이프라인에서 리포트를 결합하는 것은 지원되지 않습니다. 자세한 내용은 epic 8205를 참조합니다.
• 리포트 출력 파일을 탐색하고 다운로드하려면 artifacts:paths 키워드를 포함합니다. 이렇게 하면 아티팩트가 두 번 업로드되고 저장됩니다.
• artifacts: reports용으로 생성된 아티팩트는 job 결과(성공 또는 실패)와 무관하게 항상 업로드됩니다. 아티팩트의 만료 날짜를 설정하려면 artifacts:expire_in을 사용할 수 있습니다.

---

artifacts:untracked#

artifacts:untracked를 사용하면 Git에서 추적되지 않는 모든 파일을 아티팩트로 추가할 수 있습니다 (artifacts:paths에 정의된 경로와 함께). artifacts:untracked는 리포지터리의 .gitignore 설정을 무시하므로, .gitignore에 일치하는 아티팩트도 포함됩니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• true 또는 false(정의하지 않으면 기본값).

artifacts:untracked 예시:

Git에서 추적되지 않는 모든 파일을 저장합니다:

job:
  artifacts:
    untracked: true

관련 항목:

• 아티팩트에 추적되지 않는 파일 추가.

---

artifacts:when#

artifacts:when을 사용하면 job이 실패했을 때 또는 실패 여부와 관계없이 아티팩트를 업로드할 수 있습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• on_success(기본값): job이 성공했을 때만 아티팩트를 업로드합니다.
• on_failure: job이 실패했을 때만 아티팩트를 업로드합니다.
• always: job이 타임아웃되는 경우를 제외하고 항상 아티팩트를 업로드합니다. 예를 들어 실패한 테스트를 문제 해결하는 데 필요한 아티팩트 업로드에 사용합니다.

artifacts:when 예시:

job:
  artifacts:
    when: on_failure

추가 세부 정보:

• artifacts:reports용으로 생성된 아티팩트는 job 결과(성공 또는 실패)와 무관하게 항상 업로드됩니다. artifacts:when은 이 동작을 바꾸지 않습니다.

---

before_script#

before_script를 사용하면 각 job의 script 명령보다 먼저, 그러나 아티팩트가 복원된 후에 실행해야 하는 명령 배열을 정의할 수 있습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값: 다음을 포함하는 배열입니다:

• 한 줄 명령.
• 여러 줄로 나눈 긴 명령.
• YAML 앵커.

CI/CD 변수는 지원됩니다.

before_script 예시:

job:
  before_script:
    - echo "Execute this command before any 'script:' commands."
  script:
    - echo "This command executes after the job's 'before_script' commands."

추가 세부 정보:

• before_script에 지정한 스크립트는 메인 script에 지정한 스크립트와 연결됩니다. 결합된 스크립트는 하나의 셸에서 함께 실행됩니다.
• default 섹션이 아닌 최상위 레벨에서 before_script를 사용하는 것은 지원 중단되었습니다.

관련 항목:

• 모든 job의 script 명령보다 먼저 실행해야 하는 기본 명령 배열을 정의하려면 default와 함께 before_script 사용을 참조합니다.
  • job 설정과 기본 설정은 서로 병합되지 않습니다. 파이프라인에 default:before_script가 정의되어 있고 job에도 before_script가 있으면, job 설정이 우선하며 기본 설정은 사용되지 않습니다.
• 0이 아닌 종료 코드를 무시할 수 있습니다.
• job 로그를 더 쉽게 검토할 수 있도록 before_script에 색상 코드 사용을 활용합니다.
• job 로그 출력을 단순화하려면 커스텀 접이식 섹션 생성을 사용합니다.

---

cache#

히스토리

• GitLab Runner 18.1에서 업데이트되었습니다. 캐싱 프로세스 중

cache를 사용하면 job 간에 캐시할 파일과 디렉터리 목록을 지정할 수 있습니다. 로컬 작업 사본에 있는 경로만 사용할 수 있습니다.

캐시는 다음과 같습니다:

• 파이프라인과 job 간에 공유됩니다.
• 기본적으로 보호된 브랜치와 보호되지 않은 브랜치 간에는 공유되지 않습니다.
• 아티팩트보다 먼저 복원됩니다.
• 최대 4개의 서로 다른 캐시로 제한됩니다.

특정 job에서 캐싱을 비활성화할 수 있으며, 예를 들어 다음을 재정의하는 데 사용할 수 있습니다:

• default로 정의된 기본 캐시.
• include로 추가된 job의 설정.

job 설정과 기본 설정은 서로 병합되지 않습니다. 파이프라인에 default:cache가 정의되어 있고 job에도 cache가 있으면, job 설정이 우선하며 기본 설정은 사용되지 않습니다.

캐시에 대한 자세한 내용은 GitLab CI/CD의 캐싱을 참조합니다.

default 섹션이 아닌 최상위 레벨에서 cache를 사용하는 것은 지원 중단되었습니다.

---

cache:paths#

cache:paths 키워드를 사용하면 캐시할 파일 또는 디렉터리를 선택할 수 있습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• 프로젝트 디렉터리($CI_PROJECT_DIR)를 기준으로 한 상대 경로의 배열. glob과 doublestar.Glob 패턴을 사용하는 와일드카드를 사용할 수 있습니다.

CI/CD 변수가 지원됩니다.

cache:paths 예시:

.apk로 끝나는 binaries의 모든 파일과 .config 파일을 캐시합니다:

rspec:
  script:
    - echo "This job uses a cache."
  cache:
    key: binaries-cache
    paths:
      - binaries/*.apk
      - .config

추가 세부 정보:

• cache:paths 키워드는 파일이 추적되지 않거나 .gitignore 파일에 있어도 포함합니다.

관련 항목:

• cache:paths에 대한 더 많은 예시는 CI/CD 캐싱 예시를 참조합니다.

---

cache:key#

cache:key 키워드를 사용하면 각 캐시에 고유한 식별 키를 부여할 수 있습니다. 동일한 캐시 키를 사용하는 모든 job은 다른 파이프라인에서도 동일한 캐시를 사용합니다.

설정하지 않으면 기본 키는 default입니다. cache 키워드는 있지만 cache:key가 없는 모든 job은 default 캐시를 공유합니다.

cache: paths와 함께 사용해야 하며, 그렇지 않으면 아무것도 캐시되지 않습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• 문자열.
• 미리 정의된 CI/CD 변수.
• 두 가지의 조합.

cache:key 예시:

cache-job:
  script:
    - echo "This job uses a cache."
  cache:
    key: binaries-cache-$CI_COMMIT_REF_SLUG
    paths:
      - binaries/

추가 세부 정보:

• 셸 스크립트를 실행하는 데 Windows Batch를 사용하는 경우 $를 %로 바꿔야 합니다. 예를 들어: key: %CI_COMMIT_REF_SLUG%
• cache:key 값에는 다음을 포함할 수 없습니다:
  • / 문자 또는 이에 상응하는 URI 인코딩 %2F.
  • . 문자만(개수 무관) 또는 이에 상응하는 URI 인코딩 %2E.
• 캐시는 job 간에 공유되므로, job마다 다른 경로를 사용한다면 서로 다른 cache:key도 함께 설정해야 합니다. 그렇지 않으면 캐시 내용이 덮어쓰일 수 있습니다.

관련 항목:

• 지정한 cache:key를 찾을 수 없을 때 사용할 폴백 캐시 키를 지정할 수 있습니다.
• 하나의 job에서 여러 캐시 키를 사용할 수 있습니다.
• cache:key에 대한 더 많은 예시는 CI/CD 캐싱 예시를 참조합니다.

---

cache:key:files#

히스토리

• 파일 경로 한도가 GitLab 19.5에서 increase_ci_cache_key_files_limit라는 기능 플래그와 함께 10개로 변경되었습니다. 기본적으로 비활성화되어 있습니다.

cache:key:files를 사용하면 지정한 파일의 내용이 변경될 때 새 캐시 키를 생성할 수 있습니다. 내용이 변경되지 않으면 캐시 키는 브랜치와 파이프라인 전체에서 일관되게 유지됩니다. 캐시를 재사용하고 재빌드 빈도를 줄일 수 있어, 이후 파이프라인 실행 속도가 빨라집니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• 최대 10개의 파일 경로 또는 패턴 배열.

CI/CD 변수는 지원되지 않습니다.

cache:key:files 예시:

cache-job:
  script:
    - echo "This job uses a cache."
  cache:
    key:
      files:
        - Gemfile.lock
        - package.json
    paths:
      - vendor/ruby
      - node_modules

이 예시는 Ruby와 Node.js 의존성을 위한 캐시를 생성합니다. 이 캐시는 Gemfile.lock과 package.json 파일의 현재 버전에 연결됩니다. 이 파일 중 하나가 변경되면 새 캐시 키가 계산되고 새 캐시가 생성됩니다. 이후에 동일한 Gemfile.lock과 package.json을 cache:key:files와 함께 사용하는 job 실행은 의존성을 다시 빌드하는 대신 새 캐시를 사용합니다.

추가 세부 정보:

• 캐시 key는 나열된 파일의 내용으로 계산된 SHA입니다. 파일이 존재하지 않으면 키 계산에서 무시됩니다. 지정한 파일이 하나도 존재하지 않으면 폴백 키는 default입니다.
• **/package.json과 같은 와일드카드 패턴을 사용할 수 있습니다.
• 최대 10개의 파일을 지정할 수 있습니다.

---

cache:key:files_commits#

cache:key:files_commits를 사용하면 지정한 파일의 최신 커밋이 변경될 때 새 캐시 키를 생성할 수 있습니다. cache:key:files_commits 캐시 키는 파일 내용이 동일하더라도 지정한 파일에 새 커밋이 있을 때마다 변경됩니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• 최대 2개의 파일 경로 또는 패턴 배열.

cache:key:files_commits 예시:

cache-job:
  script:
    - echo "This job uses a commit-based cache."
  cache:
    key:
      files_commits:
        - package.json
        - yarn.lock
    paths:
      - node_modules

이 예시는 package.json과 yarn.lock의 커밋 히스토리를 기반으로 캐시를 생성합니다. 이 파일들의 커밋 히스토리가 변경되면 새 캐시 키가 계산되고 새 캐시가 생성됩니다.

추가 세부 정보:

• 캐시 key는 지정한 각 파일의 가장 최근 커밋으로 계산된 SHA입니다.
• 파일이 존재하지 않으면 키 계산에서 무시됩니다.
• 지정한 파일이 하나도 존재하지 않으면 폴백 키는 default입니다.
• 동일한 캐시 설정에서 cache:key:files와 함께 사용할 수 없습니다.

---

cache:key:prefix#

cache:key:prefix를 사용하면 cache:key:files로 계산된 SHA에 접두사를 결합할 수 있습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• 문자열.
• 미리 정의된 CI/CD 변수.
• 두 가지의 조합.

cache:key:prefix 예시:

rspec:
  script:
    - echo "This rspec job uses a cache."
  cache:
    key:
      files:
        - Gemfile.lock
      prefix: $CI_JOB_NAME
    paths:
      - vendor/ruby

예를 들어 $CI_JOB_NAME의 prefix를 추가하면 키는 rspec-feef9576d21ee9b6a32e30c5c79d0a0ceb68d1e5처럼 됩니다. 브랜치가 Gemfile.lock을 변경하면 해당 브랜치는 cache:key:files에 대한 새로운 SHA 체크섬을 갖게 됩니다. 새 캐시 키가 생성되고 해당 키에 대한 새 캐시가 만들어집니다. Gemfile.lock을 찾을 수 없으면 접두사가 default에 추가되므로, 예시의 키는 rspec-default가 됩니다.

추가 세부 정보:

• 어떤 커밋에서도 cache:key:files의 파일이 변경되지 않으면 접두사가 default 키에 추가됩니다.

---

cache:untracked#

untracked: true를 사용하면 Git 리포지터리에서 추적되지 않는 모든 파일을 캐시할 수 있습니다. 추적되지 않는 파일에는 다음과 같은 파일이 포함됩니다:

• .gitignore 설정으로 인해 무시된 파일.
• 생성되었지만 git add로 체크아웃에 추가되지 않은 파일.

추적되지 않는 파일을 캐시하면 job이 다음을 다운로드하는 경우 예상보다 큰 캐시가 생길 수 있습니다:

• 일반적으로 추적되지 않는 gem이나 node module 같은 의존성.
• 다른 job의 아티팩트. 아티팩트에서 추출된 파일은 기본적으로 추적되지 않습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• true 또는 false(기본값).

cache:untracked 예시:

rspec:
  script: test
  cache:
    untracked: true

추가 세부 정보:

• cache:untracked와 cache:paths를 결합하면 추적되지 않는 모든 파일과 설정된 경로의 파일을 함께 캐시할 수 있습니다. 추적된 파일이나 작업 디렉터리 밖의 파일을 포함해 특정 파일을 캐시하려면 cache:paths를 사용하고, 추적되지 않는 모든 파일도 캐시하려면 cache: untracked를 사용합니다. 예를 들어:

  rspec:
    script: test
    cache:
      untracked: true
      paths:
        - binaries/
  

  이 예시에서 job은 리포지터리의 모든 추적되지 않는 파일과 binaries/의 모든 파일을 캐시합니다. binaries/에 추적되지 않는 파일이 있으면 두 키워드 모두에 해당됩니다.

---

cache:unprotect#

cache:unprotect를 사용하면 캐시를 보호된 브랜치와 보호되지 않은 브랜치 간에 공유되도록 설정할 수 있습니다.

키워드 유형: Job 키워드입니다. job 내부 또는 default 섹션에서만 사용할 수 있습니다.

지원되는 값:

• true 또는 false(기본값).

cache:unprotect의 예시:

rspec:
  script: test
  cache:
    unprotect: true

---

cache:when#

cache:when을 사용하면 job의 상태에 따라 캐시를 저장할 시점을 정의할 수 있습니다.

cache: paths와 함께 사용해야 하며, 그렇지 않으면 아무것도 캐시되지 않습니다.

키워드 유형: Job 키워드입니다. job 내부 또는 default 섹션에서만 사용할 수 있습니다.

지원되는 값:

• on_success(기본값): job이 성공한 경우에만 캐시를 저장합니다.
• on_failure: job이 실패한 경우에만 캐시를 저장합니다.
• always: 항상 캐시를 저장합니다.

cache:when의 예시:

rspec:
  script: rspec
  cache:
    paths:
      - rspec/
    when: 'always'

이 예시에서는 job이 실패하든 성공하든 관계없이 캐시를 저장합니다.

---

cache:policy#

캐시의 업로드 및 다운로드 동작을 변경하려면 cache:policy 키워드를 사용합니다. 기본적으로 job은 시작할 때 캐시를 다운로드하고, 종료할 때 변경 사항을 캐시에 업로드합니다. 이러한 캐싱 방식이 pull-push 정책(기본값)입니다.

job이 시작할 때 캐시를 다운로드만 하고 종료할 때는 절대 변경 사항을 업로드하지 않도록 설정하려면 cache:policy:pull을 사용합니다.

job이 종료할 때 캐시를 업로드만 하고 시작할 때는 캐시를 다운로드하지 않도록 설정하려면 cache:policy:push를 사용합니다.

동일한 캐시를 사용하는 job이 많이 병렬로 실행되는 경우 pull 정책을 사용합니다. 이 정책은 job 실행 속도를 높이고 캐시 서버의 부하를 줄여줍니다. push 정책을 사용하는 job으로 캐시를 빌드할 수 있습니다.

cache: paths와 함께 사용해야 하며, 그렇지 않으면 아무것도 캐시되지 않습니다.

키워드 유형: Job 키워드입니다. job 내부 또는 default 섹션에서만 사용할 수 있습니다.

지원되는 값:

• pull
• push
• pull-push(기본값)
• CI/CD 변수.

cache:policy의 예시:

prepare-dependencies-job:
  stage: build
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: push
  script:
    - echo "This job only downloads dependencies and builds the cache."
    - echo "Downloading dependencies..."

faster-test-job:
  stage: test
  cache:
    key: gems
    paths:
      - vendor/bundle
    policy: pull
  script:
    - echo "This job script uses the cache, but does not update it."
    - echo "Running tests..."

관련 항목:

• 변수를 사용하여 job의 캐시 정책을 제어할 수 있습니다.

---

cache:fallback_keys#

cache:fallback_keys를 사용하면 cache:key에 해당하는 캐시를 찾지 못했을 때 복원을 시도할 키 목록을 지정할 수 있습니다. 캐시는 fallback_keys 섹션에 지정된 순서대로 검색됩니다.

키워드 유형: Job 키워드입니다. job 내부 또는 default 섹션에서만 사용할 수 있습니다.

지원되는 값:

• 캐시 키의 배열

cache:fallback_keys의 예시:

rspec:
  script: rspec
  cache:
    key: gems-$CI_COMMIT_REF_SLUG
    paths:
      - rspec/
    fallback_keys:
      - gems
    when: 'always'

---

coverage#

coverage와 사용자 지정 정규 표현식을 사용하면 job 출력에서 코드 커버리지를 추출하는 방식을 구성할 수 있습니다. GitLab은 일치한 백분율을 머지 리퀘스트 위젯, 파이프라인 job 목록, 분석 그래프에 표시합니다.

지원되는 값:

• RE2 정규 표현식입니다. /로 시작하고 끝나야 합니다. 커버리지 숫자와 일치해야 합니다. 주변 텍스트와도 일치할 수 있으므로, 정확한 숫자를 캡처하기 위해 정규 표현식 문자 그룹을 사용할 필요는 없습니다. RE2 구문을 사용하므로 모든 그룹은 비캡처 그룹이어야 합니다.

coverage의 예시:

job1:
  script: rspec
  coverage: '/Code coverage: \d+(?:\.\d+)?/'

이 예시에서는 다음과 같습니다.

1. GitLab은 job 로그에서 정규 표현식과 일치하는 부분을 확인합니다. Code coverage: 67.89% of lines covered와 같은 줄이 일치합니다.
2. 그런 다음 GitLab은 일치한 부분을 \d+(?:\.\d+)?와 대조하여 숫자를 추출합니다. 예시 정규 표현식은 67.89와 일치합니다.

추가 세부 정보:

• job 출력에 일치하는 줄이 여러 개 있으면 마지막 줄이 사용됩니다.
• 한 줄에 여러 개의 일치 항목이 있으면 마지막 일치 항목이 사용됩니다.
• 일치한 부분에 여러 개의 커버리지 숫자가 있으면 첫 번째 숫자가 사용됩니다.
• 앞자리의 0은 제거됩니다.
• 하위 파이프라인의 커버리지 출력은 기록되지 않습니다. 이슈 280818을 참조합니다.
• 머지 리퀘스트 diff에 줄 단위 커버리지 주석을 표시하려면 artifacts:reports:coverage_report를 별도로 구성해야 합니다. 하나를 구성한다고 해서 다른 하나가 자동으로 활성화되지는 않습니다.

관련 항목:

• 커버리지 정규 표현식 패턴
• 커버리지 시각화

---

dast_configuration#

dast_configuration 키워드를 사용하면 CI/CD 구성에서 사용할 사이트 프로필과 스캐너 프로필을 지정할 수 있습니다. 두 프로필 모두 먼저 프로젝트에 생성되어 있어야 합니다. job의 stage는 dast여야 합니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값: site_profile과 scanner_profile 각각 하나씩입니다.

• site_profile을 사용하면 job에서 사용할 사이트 프로필을 지정할 수 있습니다.
• scanner_profile을 사용하면 job에서 사용할 스캐너 프로필을 지정할 수 있습니다.

dast_configuration의 예시:

stages:
  - build
  - dast

include:
  - template: DAST.gitlab-ci.yml

dast:
  dast_configuration:
    site_profile: "Example Co"
    scanner_profile: "Quick Passive Test"

이 예시에서 dast job은 include 키워드로 추가된 dast 구성을 확장하여 특정 사이트 프로필과 스캐너 프로필을 선택합니다.

추가 세부 정보:

• 사이트 프로필이나 스캐너 프로필에 포함된 설정이 DAST 템플릿에 포함된 설정보다 우선합니다.

관련 항목:

• 사이트 프로필.
• 스캐너 프로필.

---

dependencies#

dependencies 키워드를 사용하면 아티팩트를 가져올 특정 job의 목록을 정의할 수 있습니다. 지정한 job은 모두 이전 stage에 있어야 합니다. job이 아티팩트를 전혀 다운로드하지 않도록 설정할 수도 있습니다.

job에 dependencies가 정의되어 있지 않으면 이전 stage의 모든 job이 종속된 것으로 간주되며, 해당 job은 그 job들의 모든 아티팩트를 가져옵니다.

동일한 stage에 있는 job에서 아티팩트를 가져오려면 needs:artifacts를 사용해야 합니다. 동일한 job에서 dependencies와 needs를 함께 사용해서는 안 됩니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• 아티팩트를 가져올 job의 이름입니다.
• job이 아티팩트를 전혀 다운로드하지 않도록 구성하는 빈 배열([])입니다.

dependencies의 예시:

build mac:
  stage: build
  script: make build:mac
  artifacts:
    paths:
      - binaries/

build linux:
  stage: build
  script: make build:linux
  artifacts:
    paths:
      - binaries/

test mac:
  stage: test
  script: make test:mac
  dependencies:
    - build mac

test linux:
  stage: test
  script: make test:linux
  dependencies:
    - build linux

deploy:
  stage: deploy
  script: make deploy
  environment: production

이 예시에서 아티팩트를 가진 job은 build mac과 build linux 두 개입니다. test mac이 실행되면 build mac의 아티팩트가 다운로드되어 빌드 컨텍스트에서 압축이 해제됩니다. test linux와 build linux의 아티팩트에서도 동일한 일이 일어납니다.

deploy job은 stage 우선순위로 인해 이전의 모든 job에서 아티팩트를 다운로드합니다.

추가 세부 정보:

• 이전 job이 아티팩트를 생성하지 않거나 실행되지 않은 수동 job인 경우에도 종속된 job은 계속 실행되며 오류가 발생하지 않습니다.
• 종속된 job의 아티팩트가 만료되었거나 삭제된 경우 해당 job은 실패합니다.

---

environment#

environment를 사용하면 job이 배포되는 환경을 정의할 수 있습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값: job이 배포되는 환경의 이름이며, 다음 형식 중 하나를 사용합니다.

• 문자, 숫자, 공백, 그리고 -, _, /, $, {, } 문자를 포함한 일반 텍스트입니다.
• 미리 정의된 변수, 프로젝트, 그룹, 인스턴스 변수, 또는 .gitlab-ci.yml 파일에 정의된 변수를 포함한 CI/CD 변수입니다. script 섹션에 정의된 변수는 사용할 수 없습니다.

environment의 예시:

deploy to production:
  stage: deploy
  script: git push production HEAD:main
  environment: production

추가 세부 정보:

• environment를 지정했는데 해당 이름의 환경이 존재하지 않으면 환경이 생성됩니다.

---

environment:name#

환경의 이름을 설정합니다.

일반적인 환경 이름은 qa, staging, production이지만 원하는 이름을 사용할 수 있습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값: job이 배포되는 환경의 이름이며, 다음 형식 중 하나를 사용합니다.

• 문자, 숫자, 공백, 그리고 -, _, /, $, {, } 문자를 포함한 일반 텍스트입니다.
• 미리 정의된 변수, 프로젝트, 그룹, 인스턴스 변수, 또는 .gitlab-ci.yml 파일에 정의된 변수를 포함한 CI/CD 변수입니다. script 섹션에 정의된 변수는 사용할 수 없습니다.

environment:name의 예시:

deploy to production:
  stage: deploy
  script: git push production HEAD:main
  environment:
    name: production

---

environment:url#

환경의 URL을 설정합니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값: 다음 형식 중 하나로 된 단일 URL입니다.

• https://prod.example.com과 같은 일반 텍스트입니다.
• 미리 정의된 변수, 프로젝트, 그룹, 인스턴스 변수, 또는 .gitlab-ci.yml 파일에 정의된 변수를 포함한 CI/CD 변수입니다. script 섹션에 정의된 변수는 사용할 수 없습니다.

environment:url의 예시:

deploy to production:
  stage: deploy
  script: git push production HEAD:main
  environment:
    name: production
    url: https://prod.example.com

추가 세부 정보:

• job이 완료된 후에는 머지 리퀘스트, 환경, 배포 페이지에서 버튼을 선택하여 URL에 접근할 수 있습니다.

---

environment:on_stop#

환경을 닫는(중지하는) 작업은 environment 아래에 정의된 on_stop 키워드로 수행할 수 있습니다. 이 키워드는 환경을 닫기 위해 실행되는 다른 job을 선언합니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

추가 세부 정보:

• 자세한 내용과 예시는 environment:action을 참조합니다.

---

environment:action#

action 키워드를 사용하면 job이 환경과 상호작용하는 방식을 지정할 수 있습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값: 다음 키워드 중 하나입니다.

environment:action의 예시:

stop_review_app:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script: make delete-app
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop

---

environment:auto_stop_in#

히스토리

• GitLab 17.7에서 prepare, access, verify 환경 액션을 지원하도록 업데이트되었습니다.

auto_stop_in 키워드는 환경의 수명을 지정합니다. 환경이 만료되면 GitLab이 자동으로 환경을 중지합니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값: 자연어로 작성된 기간입니다. 예를 들어 다음은 모두 동일합니다.

• 168 hours
• 7 days
• one week
• never

CI/CD 변수가 지원됩니다.

environment:auto_stop_in의 예시:

review_app:
  script: deploy-review-app
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    auto_stop_in: 1 day

review_app의 환경이 생성되면 환경의 수명이 1 day로 설정됩니다. 리뷰 앱이 배포될 때마다 해당 수명도 1 day로 재설정됩니다.

auto_stop_in 키워드는 stop을 제외한 모든 환경 액션에 사용할 수 있습니다. 일부 액션은 환경의 예약된 중지 시간을 재설정하는 데 사용할 수 있습니다. 자세한 내용은 준비 또는 검증 목적으로 환경에 접근하기를 참조합니다.

관련 항목:

• 환경 자동 중지 문서.

---

environment:kubernetes#

히스토리

• agent 키워드가 GitLab 17.6에서 도입됨.
• namespace, flux_resource_path 키워드가 GitLab 17.7에서 도입됨.
• namespace, flux_resource_path 키워드가 GitLab 18.4에서 지원 중단됨.
• dashboard:namespace, dashboard:flux_resource_path 키워드가 GitLab 18.4에서 도입됨.

kubernetes 키워드를 사용하면 환경에 대해 Kubernetes용 대시보드 와 GitLab 관리형 Kubernetes 리소스를 구성할 수 있습니다.

키워드 유형: Job 키워드입니다. Job의 일부로만 사용할 수 있습니다.

지원되는 값:

• agent: Kubernetes용 GitLab 에이전트를 지정하는 문자열입니다. 형식은 path/to/agent/project:agent-name입니다. 에이전트가 파이프라인을 실행하는 프로젝트에 연결되어 있다면 $CI_PROJECT_PATH:agent-name을 사용합니다.
• dashboard:namespace: 환경이 배포되는 Kubernetes 네임스페이스를 나타내는 문자열입니다. 네임스페이스는 agent 키워드와 함께 설정해야 합니다. namespace는 지원 중단되었습니다.
• dashboard:flux_resource_path: HelmRelease와 같은 Flux 리소스의 전체 경로를 나타내는 문자열입니다. Flux 리소스는 agent, dashboard:namespace 키워드와 함께 설정해야 합니다. flux_resource_path는 지원 중단되었습니다.
• managed_resources: 환경에 대해 GitLab 관리형 Kubernetes 리소스를 구성하는 enabled 키워드를 가진 해시입니다.
  • managed_resources:enabled: 환경에서 GitLab 관리형 Kubernetes 리소스가 활성화되어 있는지 나타내는 불리언 값입니다.
• dashboard: 환경에 대해 Kubernetes용 대시보드를 구성하는 dashboard:namespace, dashboard:flux_resource_path 키워드를 가진 해시입니다.

environment:kubernetes의 예시:

deploy:
  stage: deploy
  script: make deploy-app
  environment:
    name: production
    kubernetes:
      agent: path/to/agent/project:agent-name
      dashboard:
        namespace: my-namespace
        flux_resource_path: helm.toolkit.fluxcd.io/v2/namespaces/flux-system/helmreleases/helm-release-resource

관리형 리소스를 비활성화하는 경우의 environment:kubernetes의 예시:

deploy:
  stage: deploy
  script: make deploy-app
  environment:
    name: production
    kubernetes:
      agent: path/to/agent/project:agent-name
      managed_resources:
        enabled: false
      dashboard:
        namespace: my-namespace
        flux_resource_path: helm.toolkit.fluxcd.io/v2/namespaces/flux-system/helmreleases/helm-release-resource

이 설정은 다음과 같이 작동합니다:

• deploy job 이 production 환경에 배포되도록 설정합니다.
• agent-name이라는 에이전트를 환경과 연결합니다.
• 네임스페이스가 my-namespace이고 flux_resource_path가 helm.toolkit.fluxcd.io/v2/namespaces/flux-system/helmreleases/helm-release-resource로 설정된 환경에 대해 Kubernetes용 대시보드를 구성합니다.

추가 세부 정보:

• 대시보드를 사용하려면 Kubernetes용 GitLab 에이전트를 설치하고 환경의 프로젝트 또는 상위 그룹에 대해 user_access를 구성해야 합니다.
• job을 실행하는 사용자는 클러스터 에이전트에 액세스할 권한이 있어야 합니다. 그렇지 않으면 대시보드가 agent, namespace, flux_resource_path 속성을 무시합니다.
• agent만 설정하려는 경우 namespace를 설정할 필요는 없으며 flux_resource_path는 설정할 수 없습니다. 다만 이렇게 설정하면 Kubernetes용 대시보드에 클러스터의 모든 네임스페이스가 표시됩니다.

---

environment:deployment_tier#

히스토리

• CI/CD 변수 지원이 GitLab 18.5에서 추가됨.

deployment_tier 키워드를 사용하면 배포 환경의 티어를 지정할 수 있습니다.

키워드 유형: Job 키워드입니다. Job의 일부로만 사용할 수 있습니다.

지원되는 값: 다음 중 하나입니다:

• production
• staging
• testing
• development
• other
• CI/CD 변수: 사전 정의된 변수, 프로젝트·그룹·인스턴스 변수, .gitlab-ci.yml 파일에 정의된 변수를 포함합니다. script 섹션에 정의된 변수는 사용할 수 없습니다.

environment:deployment_tier의 예시:

deploy:
  script: echo
  environment:
    name: customer-portal
    deployment_tier: production

추가 세부 정보:

• 이 job 정의로 생성된 환경에는 이 값을 기반으로 티어가 할당됩니다.
• 기존 환경은 이 값이 나중에 추가되어도 티어가 갱신되지 않습니다. 기존 환경의 티어는 Environments API를 사용해 갱신해야 합니다.

관련 주제:

• 환경의 배포 티어.

---

동적 환경#

CI/CD 변수를 사용하면 환경 이름을 동적으로 지정할 수 있습니다.

예시:

deploy as review app:
  stage: deploy
  script: make deploy
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_ENVIRONMENT_SLUG.example.com/

deploy as review app job은 동적으로 review/$CI_COMMIT_REF_SLUG 환경을 생성하는 배포로 표시됩니다. $CI_COMMIT_REF_SLUG는 러너가 설정하는 CI/CD 변수입니다. $CI_ENVIRONMENT_SLUG 변수는 환경 이름을 기반으로 하지만 URL에 포함하기에 적합합니다. deploy as review app job 이 pow라는 브랜치에서 실행되면 이 환경은 https://review-pow.example.com/과 같은 URL로 액세스할 수 있습니다.

일반적인 사용 사례는 브랜치에 대해 동적 환경을 생성하여 리뷰 앱으로 사용하는 것입니다. 리뷰 앱을 사용하는 예시는 https://gitlab.com/gitlab-examples/review-apps-nginx/에서 확인할 수 있습니다.

---

extends#

extends를 사용하면 설정 섹션을 재사용할 수 있습니다. YAML 앵커의 대안이며 조금 더 유연하고 가독성이 좋습니다.

키워드 유형: Job 키워드입니다. Job의 일부로만 사용할 수 있습니다.

지원되는 값:

• 파이프라인 내 다른 job의 이름입니다.
• 파이프라인 내 다른 job 이름들의 목록(배열)입니다.

extends의 예시:

.tests:
  stage: test
  image: ruby:3.0

rspec:
  extends: .tests
  script: rake rspec

rubocop:
  extends: .tests
  script: bundle exec rubocop

이 예시에서 rspec job은 .tests 템플릿 job의 설정을 사용합니다. 파이프라인을 생성할 때 GitLab은 다음을 수행합니다:

• 키를 기준으로 역방향 딥 머지(reverse deep merge)를 수행합니다.
• .tests의 내용을 rspec job과 병합합니다.
• 키의 값은 병합하지 않습니다.

결합된 설정은 다음 job 들과 동일합니다:

rspec:
  stage: test
  image: ruby:3.0
  script: rake rspec

rubocop:
  stage: test
  image: ruby:3.0
  script: bundle exec rubocop

추가 세부 정보:

• extends에는 여러 부모를 사용할 수 있습니다.
• extends 키워드는 최대 11 단계의 상속을 지원하지만 3 단계 이상 사용하는 것은 피해야 합니다.
• 앞의 예시에서 .tests는 숨겨진 job이지만, 일반 job의 설정도 확장할 수 있습니다.

관련 주제:

• extends를 사용해 설정 섹션 재사용하기.
• 포함된 설정 파일의 설정을 재사용하려면 extends를 사용합니다.

---

hooks#

hooks를 사용하면 job 실행의 특정 단계(예: Git 리포지터리를 가져오기 전)에 러너에서 실행할 명령어 목록을 지정할 수 있습니다.

Job 설정과 기본 설정은 서로 병합되지 않습니다. 파이프라인에 default:hooks가 정의되어 있고 job에도 hooks가 있으면 job 설정이 우선하며 기본 설정은 사용되지 않습니다.

키워드 유형: Job 키워드입니다. Job의 일부로 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• hook과 해당 명령어의 해시입니다. 사용 가능한 hook: pre_get_sources_script.

---

hooks:pre_get_sources_script#

hooks:pre_get_sources_script를 사용하면 Git 리포지터리와 서브모듈을 클론하기 전에 러너에서 실행할 명령어 목록을 지정할 수 있습니다. 예를 들어 다음과 같은 용도로 사용할 수 있습니다:

• Git 설정을 조정합니다.
• 추적 변수를 내보냅니다(export).

지원되는 값: 다음을 포함하는 배열입니다:

• 한 줄 명령어입니다.
• 여러 줄로 분할된 긴 명령어입니다.
• YAML 앵커입니다.

CI/CD 변수가 지원됩니다.

hooks:pre_get_sources_script의 예시:

job1:
  hooks:
    pre_get_sources_script:
      - echo 'hello job1 pre_get_sources_script'
  script: echo 'hello job1 script'

관련 주제:

• GitLab Runner 설정

---

identity#

히스토리

• GitLab 16.9에서 google_cloud_support_feature_flag라는 이름의 기능 플래그와 함께 도입됨. 이 기능은 베타 상태입니다.
• GitLab 17.1에서 GitLab.com에 활성화됨. google_cloud_support_feature_flag 기능 플래그가 제거되었습니다.

이 기능은 베타 상태입니다.

identity를 사용하면 ID 페더레이션(identity federation)을 사용해 서드파티 서비스로 인증할 수 있습니다.

키워드 유형: Job 키워드입니다. Job의 일부로만 사용할 수 있습니다.

지원되는 값: 식별자입니다. 지원되는 공급자:

• google_cloud: Google Cloud 입니다. Google Cloud IAM 통합으로 구성해야 합니다.

identity의 예시:

job_with_workload_identity:
  identity: google_cloud
  script:
    - gcloud compute instances list

관련 주제:

• Workload Identity Federation.
• Google Cloud IAM 통합.

---

id_tokens#

id_tokens를 사용하면 서드파티 서비스로 인증하기 위한 ID 토큰을 생성할 수 있습니다. 이 방식으로 생성된 모든 JWT는 OIDC 인증을 지원합니다. 필수 aud 하위 키워드는 JWT의 aud 클레임을 구성하는 데 사용됩니다.

Job 설정과 기본 설정은 서로 병합되지 않습니다. 파이프라인에 default:id_tokens가 정의되어 있고 job에도 id_tokens가 있으면 job 설정이 우선하며 기본 설정은 사용되지 않습니다.

지원되는 값:

• 토큰 이름과 해당 aud 클레임입니다. aud는 다음을 지원합니다:
  • 단일 문자열.
  • 문자열 배열.
  • CI/CD 변수.

id_tokens의 예시:

job_with_id_tokens:
  id_tokens:
    ID_TOKEN_1:
      aud: https://vault.example.com
    ID_TOKEN_2:
      aud:
        - https://gcp.com
        - https://aws.com
    SIGSTORE_ID_TOKEN:
      aud: sigstore
  script:
    - command_to_authenticate_with_vault $ID_TOKEN_1
    - command_to_authenticate_with_aws $ID_TOKEN_2
    - command_to_authenticate_with_gcp $ID_TOKEN_2

관련 주제:

• ID 토큰 인증.
• 클라우드 서비스에 연결하기.
• Sigstore를 사용한 키리스 서명.

---

image#

image를 사용하면 job 이 실행되는 Docker 이미지를 지정할 수 있습니다.

Job 설정과 기본 설정은 서로 병합되지 않습니다. 파이프라인에 default:image가 정의되어 있고 job에도 image가 있으면 job 설정이 우선하며 기본 설정은 사용되지 않습니다.

키워드 유형: Job 키워드입니다. Job의 일부로 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값: 필요한 경우 레지스트리 경로를 포함한 이미지 이름이며, 다음 형식 중 하나입니다:

• <image-name>(latest 태그와 함께 <image-name>을 사용하는 것과 동일)
• <image-name>:<tag>
• <image-name>@<digest>

CI/CD 변수가 지원됩니다.

image의 예시:

default:
  image: ruby:3.0

rspec:
  script: bundle exec rspec

rspec 2.7:
  image: registry.example.com/my-group/my-project/ruby:2.7
  script: bundle exec rspec

이 예시에서 ruby:3.0 이미지는 파이프라인 내 모든 job의 기본값입니다. rspec 2.7 job은 job 별 image 섹션으로 기본값을 재정의하므로 기본값을 사용하지 않습니다.

추가 세부 정보:

• default 섹션이 아닌 최상위 수준에서 image를 사용하는 것은 지원 중단되었습니다.

관련 주제:

• Docker 컨테이너에서 CI/CD job 실행하기.

---

image:name#

job 이 실행되는 Docker 이미지의 이름입니다. 단독으로 사용되는 image와 유사합니다.

키워드 유형: Job 키워드입니다. Job의 일부로 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값: 필요한 경우 레지스트리 경로를 포함한 이미지 이름이며, 다음 형식 중 하나입니다:

• <image-name>(latest 태그와 함께 <image-name>을 사용하는 것과 동일)
• <image-name>:<tag>
• <image-name>@<digest>

CI/CD 변수가 지원됩니다.

image:name의 예시:

test-job:
  image:
    name: "registry.example.com/my/image:latest"
  script: echo "Hello world"

관련 주제:

• Docker 컨테이너에서 CI/CD job 실행하기.

---

image:entrypoint#

컨테이너의 진입점(entry point)으로 실행할 명령어 또는 스크립트입니다.

Docker 컨테이너가 생성될 때 entrypoint는 Docker의 --entrypoint 옵션으로 변환됩니다. 구문은 Dockerfile의 ENTRYPOINT 지시어와 유사하며, 각 셸 토큰이 배열 내 별도의 문자열이 됩니다.

키워드 유형: Job 키워드입니다. Job의 일부로 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• 문자열입니다.

image:entrypoint의 예시:

test-job:
  image:
    name: super/sql:experimental
    entrypoint: [""]
  script: echo "Hello world"

관련 주제:

• 이미지의 진입점 재정의하기.

---

image:docker#

image:docker를 사용하면 Docker executor를 사용하는 러너 또는 Kubernetes executor를 사용하는 러너에 옵션을 전달할 수 있습니다. 이 키워드는 다른 executor 유형에서는 동작하지 않습니다.

키워드 유형: Job 키워드입니다. job 또는 default 섹션의 일부로만 사용할 수 있습니다.

지원되는 값:

Docker executor에 대한 옵션의 해시이며, 다음을 포함할 수 있습니다:

• platform: 풀(pull)할 이미지의 아키텍처를 선택합니다. 지정하지 않으면 기본값은 호스트 러너와 동일한 플랫폼입니다.
• user: 컨테이너를 실행할 때 사용할 사용자 이름 또는 UID를 지정합니다.

image:docker 예시:

arm-sql-job:
  script: echo "Run sql tests"
  image:
    name: super/sql:experimental
    docker:
      platform: arm64/v8
      user: dave

추가 세부 정보:

• image:docker:platform은 docker pull --platform 옵션에 매핑됩니다.
• image:docker:user는 docker run --user 옵션에 매핑됩니다.
• Docker executor를 사용할 때, 러너와 다른 아키텍처용으로 빌드된 이미지를 실행하려면 호스트에 binfmt_misc로 등록된 에뮬레이션 지원이 있어야 합니다. 예를 들어 QEMU 에뮬레이터를 설치하려면 호스트에서 docker run --privileged --rm tonistiigi/binfmt --install all 명령을 실행합니다. 에뮬레이션 지원이 없으면 job은 exec format error 메시지와 함께 실패합니다. GitLab Runner 19.1 이하 버전에서는 호스트와 일치하지 않는 platform 값이 조용히 무시되고 컨테이너가 호스트 아키텍처로 대신 실행될 수 있었습니다.

---

image:kubernetes#

히스토리

• GitLab 18.0에서 도입되었습니다. GitLab Runner 17.11 이상이 필요합니다.
• user 입력 옵션이 GitLab Runner 17.11에서 도입되었습니다.
• user 입력 옵션이 GitLab 18.0에서 uid:gid 형식을 지원하도록 확장되었습니다.

image:kubernetes를 사용하면 GitLab Runner Kubernetes executor에 옵션을 전달할 수 있습니다. 이 키워드는 다른 executor 유형에서는 동작하지 않습니다.

키워드 유형: Job 키워드입니다. job 또는 default 섹션의 일부로만 사용할 수 있습니다.

지원되는 값:

Kubernetes executor에 대한 옵션의 해시이며, 다음을 포함할 수 있습니다:

• user: 컨테이너 실행 시 사용할 사용자 이름 또는 UID를 지정합니다. UID:GID 형식을 사용해 GID도 설정할 수 있습니다.

UID만 사용하는 image:kubernetes 예시:

arm-sql-job:
  script: echo "Run sql tests"
  image:
    name: super/sql:experimental
    kubernetes:
      user: "1001"

UID와 GID를 모두 사용하는 image:kubernetes 예시:

arm-sql-job:
  script: echo "Run sql tests"
  image:
    name: super/sql:experimental
    kubernetes:
      user: "1001:1001"

---

image:pull_policy#

러너가 Docker 이미지를 가져올 때 사용하는 풀 정책입니다.

키워드 유형: Job 키워드입니다. job 또는 default 섹션의 일부로만 사용할 수 있습니다.

지원되는 값:

• 단일 풀 정책, 또는 배열 형태의 여러 풀 정책. always, if-not-present, never 중 하나일 수 있습니다.

image:pull_policy 예시:

job1:
  script: echo "A single pull policy."
  image:
    name: ruby:3.0
    pull_policy: if-not-present

job2:
  script: echo "Multiple pull policies."
  image:
    name: ruby:3.0
    pull_policy: [always, if-not-present]

추가 세부 정보:

• 러너가 정의된 풀 정책을 지원하지 않으면 job은 다음과 유사한 오류와 함께 실패합니다: ERROR: Job failed (system failure): the configured PullPolicies ([always]) are not allowed by AllowedPullPolicies ([never]).

관련 주제:

• Docker 컨테이너에서 CI/CD job 실행.
• 러너가 이미지를 가져오는 방식 구성.
• 여러 풀 정책 설정.

---

inputs#

히스토리

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

inputs를 사용하면 job에 대해 타입이 지정되고 검증되는 입력을 정의할 수 있습니다. job 입력은 job을 수동으로 실행하거나 재시도할 때 재정의할 수 있습니다.

Job 입력은 타입 안전성과 검증을 제공하는 매개변수입니다. CI/CD 변수와 달리 job을 실행하거나 재시도할 때는 job에 명시적으로 정의된 입력만 지정할 수 있습니다. 모든 job 입력 이름은 미리 정의되어 있어야 합니다.

${{ job.inputs.INPUT_NAME }} Moa 표현식 구문으로 job 입력 값을 참조합니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

입력 이름의 해시이며, 각 입력은 하나 이상의 하위 키로 구성됩니다:

• default (필수)
• type
• options
• description
• regex

inputs 예시:

test_job:
  inputs:
    test_suite:
      default: unit
      description: Which test suite to run
      options: [unit, integration, e2e]
    parallel_count:
      type: number
      default: 5
      description: Number of parallel test runners
    verbose:
      type: boolean
      default: false
      description: Enable verbose test output
  script:
    - 'echo "Running ${{ job.inputs.test_suite }} tests"'
    - 'if [ "${{ job.inputs.verbose }}" == "true" ]; then export TEST_VERBOSE=1; fi'
    - ./run_tests.sh --suite ${{ job.inputs.test_suite }} --parallel ${{ job.inputs.parallel_count }}

추가 세부 정보:

• Job 입력은 job 이 생성될 때와 새 입력 값으로 job을 재시도하려고 할 때 검증됩니다. 검증에 실패하면 job 이 시작되지 않습니다.
• Job 입력은 정의된 job에 범위가 한정되며 다른 job에서는 접근할 수 없습니다.
• job 입력을 지원하는 키워드의 전체 목록은 job 입력을 사용할 수 있는 위치를 참조합니다.

---

inputs:default#

모든 job 입력에는 default로 정의된 기본값이 있어야 합니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값: 입력의 type과 일치하는 모든 값.

inputs:default 예시:

test_job:
  inputs:
    environment:
      default: staging
    timeout:
      type: number
      default: 30

---

inputs:type#

type을 사용하면 입력 값의 데이터 타입을 정의할 수 있습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• string (기본값)
• number
• boolean
• array.

inputs:type 예시:

test_job:
  inputs:
    count:
      type: number
      default: 5
    enabled:
      type: boolean
      default: true

---

inputs:description#

description을 사용하면 입력의 목적에 대한 정보를 제공할 수 있습니다. description은 입력의 동작에 영향을 주지 않습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값: 문자열.

inputs:description 예시:

deploy_job:
  inputs:
    environment:
      default: staging
      description: Target deployment environment

---

inputs:options#

options을 사용하면 입력에 허용되는 값의 목록을 지정할 수 있습니다.

입력 값은 나열된 옵션 중 하나와 정확히(대소문자 구분) 일치해야 합니다. 값이 옵션과 일치하지 않으면 검증에 실패합니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값: 허용되는 값의 배열.

inputs:options 예시:

deploy_job:
  inputs:
    environment:
      default: staging
      options: [development, staging, production]

---

inputs:regex#

regex를 사용하면 입력 값이 일치해야 하는 정규 표현식 패턴을 지정할 수 있습니다.

값이 정규 표현식과 일치하지 않으면 검증에 실패합니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값: 정규 표현식 문자열.

inputs:regex 예시:

deploy_job:
  inputs:
    version:
      default: v1.0.0
      regex: ^v\d+\.\d+\.\d+$

이 예시에서 v1.1.1 입력 값은 정규 표현식 검증을 통과하지만 v1.1.1-beta는 통과하지 못합니다.

---

inherit#

inherit를 사용하면 기본 키워드와 변수의 상속을 제어할 수 있습니다.

---

inherit:default#

inherit:default를 사용하면 기본 키워드의 상속을 제어할 수 있습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• true(기본값) 또는 false로 모든 기본 키워드의 상속을 활성화하거나 비활성화합니다.
• 상속할 특정 기본 키워드의 목록.

inherit:default 예시:

default:
  retry: 2
  image: ruby:3.0
  interruptible: true

job1:
  script: echo "This job does not inherit any default keywords."
  inherit:
    default: false

job2:
  script: echo "This job inherits only the two listed default keywords. It does not inherit 'interruptible'."
  inherit:
    default:
      - retry
      - image

추가 세부 정보:

• 상속할 기본 키워드는 한 줄로도 나열할 수 있습니다: default: [keyword1, keyword2]

---

inherit:variables#

inherit:variables를 사용하면 기본 변수 키워드의 상속을 제어할 수 있습니다.

키워드 유형: Job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• true(기본값) 또는 false로 모든 기본 변수의 상속을 활성화하거나 비활성화합니다.
• 상속할 특정 변수의 목록.

inherit:variables 예시:

variables:
  VARIABLE1: "This is default variable 1"
  VARIABLE2: "This is default variable 2"
  VARIABLE3: "This is default variable 3"

job1:
  script: echo "This job does not inherit any default variables."
  inherit:
    variables: false

job2:
  script: echo "This job inherits only the two listed default variables. It does not inherit 'VARIABLE3'."
  inherit:
    variables:
      - VARIABLE1
      - VARIABLE2

추가 세부 정보:

• 상속할 기본 변수는 한 줄로도 나열할 수 있습니다: variables: [VARIABLE1, VARIABLE2]

---

interruptible#

interruptible를 사용하면 중복 파이프라인 자동 취소 기능을 구성할 수 있습니다. 이 기능은 동일한 ref에서 새 커밋에 대한 파이프라인이 시작되면 job 이 완료되기 전에 취소합니다. 비활성화되어 있으면 이 키워드는 아무 효과가 없습니다.

예를 들어 New pipeline으로 동일한 커밋에 대해 파이프라인을 다시 실행하면 이 키워드는 아무 효과가 없습니다.

Auto-cancel redundant pipelines 기능의 동작은 workflow:auto_cancel:on_new_commit 설정으로 제어할 수 있습니다.

키워드 유형: Job 키워드입니다. job 또는 default 섹션의 일부로만 사용할 수 있습니다.

지원되는 값:

• true 또는 false(기본값).

기본 동작에서의 interruptible 예시:

workflow:
  auto_cancel:
    on_new_commit: conservative # the default behavior

stages:
  - stage1
  - stage2
  - stage3

step-1:
  stage: stage1
  script:
    - echo "Can be canceled."
  interruptible: true

step-2:
  stage: stage2
  script:
    - echo "Can not be canceled."

step-3:
  stage: stage3
  script:
    - echo "Because step-2 can not be canceled, this step can never be canceled, even though it's set as interruptible."
  interruptible: true

이 예시에서 새 파이프라인은 실행 중인 파이프라인을 다음과 같이 처리합니다:

• step-1만 실행 중이거나 대기 중이면 취소됩니다.
• step-2가 시작된 이후에는 취소되지 않습니다.

auto_cancel:on_new_commit:interruptible 설정에서의 interruptible 예시:

workflow:
  auto_cancel:
    on_new_commit: interruptible

stages:
  - stage1
  - stage2
  - stage3

step-1:
  stage: stage1
  script:
    - echo "Can be canceled."
  interruptible: true

step-2:
  stage: stage2
  script:
    - echo "Can not be canceled."

step-3:
  stage: stage3
  script:
    - echo "Can be canceled."
  interruptible: true

이 예시에서 새 파이프라인은 step-1과 step-3 이 실행 중이거나 대기 중이면 이를 취소합니다.

추가 세부 정보:

• job 이 시작된 후 안전하게 취소할 수 있는 경우에만, 예를 들어 빌드 job처럼, interruptible: true를 설정합니다. 배포 job은 부분 배포를 방지하기 위해 보통 취소하면 안 됩니다.
• 기본 동작 또는 workflow:auto_cancel:on_new_commit: conservative를 사용하는 경우:
  • 아직 시작되지 않은 job은 job의 구성과 관계없이 항상 interruptible: true로 간주됩니다. interruptible 구성은 job 이 시작된 이후에만 고려됩니다.
  • 실행 중인 파이프라인은 실행 중인 모든 job 이 interruptible: true로 구성되어 있거나 interruptible: false로 구성된 job 이 어느 시점에도 시작되지 않은 경우에만 취소됩니다. interruptible: false 인 job 이 시작된 이후에는 전체 파이프라인이 더 이상 interruptible로 간주되지 않습니다.
  • 파이프라인이 다운스트림 파이프라인을 트리거했지만 다운스트림 파이프라인에서 interruptible: false 인 job 이 아직 시작되지 않았다면 다운스트림 파이프라인도 취소됩니다.
• 파이프라인의 첫 번째 스테이지에 interruptible: false 인 선택적 수동 job을 추가하면 사용자가 파이프라인이 자동으로 취소되는 것을 수동으로 막을 수 있도록 할 수 있습니다. 사용자가 job을 시작한 이후에는 파이프라인이 Auto-cancel redundant pipelines 기능으로 취소될 수 없습니다.
• 트리거 job과 함께 interruptible을 사용하는 경우:
  • 트리거된 다운스트림 파이프라인은 트리거 job의 interruptible 구성에 영향을 받지 않습니다.
  • workflow:auto_cancel 이 conservative로 설정되어 있으면 트리거 job의 interruptible 구성은 아무 효과가 없습니다.
  • workflow:auto_cancel 이 interruptible로 설정되어 있으면 interruptible: true 인 트리거 job은 자동으로 취소될 수 있습니다.

---

needs#

needs를 사용하면 잡을 순서와 무관하게 실행할 수 있습니다. needs를 사용하는 잡 간의 관계는 방향성 비순환 그래프로 시각화할 수 있습니다.

스테이지 순서를 무시하고 다른 잡이 끝나기를 기다리지 않고 일부 잡을 실행할 수 있습니다. 여러 스테이지에 속한 잡도 동시에 실행할 수 있습니다.

키워드 유형: 잡 키워드. 잡의 일부로만 사용할 수 있습니다.

지원되는 값:

• 잡의 배열(최대 50개 잡).
• 빈 배열([]). 파이프라인이 생성되는 즉시 잡을 시작하도록 설정합니다.

needs 예시:

linux:build:
  stage: build
  script: echo "Building linux..."

mac:build:
  stage: build
  script: echo "Building mac..."

lint:
  stage: test
  needs: []
  script: echo "Linting..."

linux:rspec:
  stage: test
  needs: ["linux:build"]
  script: echo "Running rspec on linux..."

mac:rspec:
  stage: test
  needs: ["mac:build"]
  script: echo "Running rspec on mac..."

production:
  stage: deploy
  script: echo "Running production..."
  environment: production

이 예시는 네 개의 실행 경로를 만듭니다.

• 린터: lint 잡은 needs가 없어(needs: []) build 스테이지가 끝나기를 기다리지 않고 즉시 실행됩니다.
• Linux 경로: linux:rspec 잡은 mac:build 잡이 끝나기를 기다리지 않고 linux:build 잡이 끝나는 즉시 실행됩니다.
• macOS 경로: mac:rspec 잡은 linux:build 잡이 끝나기를 기다리지 않고 mac:build 잡이 끝나는 즉시 실행됩니다.
• production 잡은 이전의 모든 잡, 즉 lint, linux:build, linux:rspec, mac:build, mac:rspec가 끝나는 즉시 실행됩니다.

추가 세부 정보:

• 하나의 잡이 needs 배열에 가질 수 있는 잡 수에는 제한이 있습니다.
  • GitLab.com의 경우 제한은 50개입니다. 자세한 내용은 issue 350398를 참고합니다.
  • GitLab Self-Managed 및 GitLab Dedicated의 경우 기본 제한은 50개입니다. 이 제한은 관리자 영역에서 CI/CD 제한을 업데이트해 변경할 수 있습니다.
• needs가 parallel 키워드를 사용하는 잡을 참조하면 하나의 잡뿐 아니라 병렬로 생성된 모든 잡에 의존합니다. 또한 기본적으로 병렬 잡 전부에서 아티팩트를 다운로드합니다. 아티팩트 이름이 같으면 서로 덮어써서 마지막으로 다운로드된 아티팩트만 저장됩니다.
  • needs가 병렬화된 잡 전체가 아니라 일부만 참조하게 하려면 needs:parallel:matrix 키워드를 사용합니다.
• 구성 중인 잡과 같은 스테이지에 있는 잡을 참조할 수 있습니다.
• needs가 only, except, rules 때문에 파이프라인에서 제외될 수도 있는 잡을 참조하면 파이프라인 생성이 실패할 수 있습니다. 파이프라인 생성 실패를 해결하려면 needs:optional 키워드를 사용합니다.
• 파이프라인에 needs: []를 가진 잡과 .pre 스테이지의 잡이 함께 있으면 파이프라인이 생성되는 즉시 모두 시작됩니다. needs: []를 가진 잡은 즉시 시작되고, .pre 스테이지의 잡도 즉시 시작됩니다.

---

needs:artifacts#

잡이 needs를 사용하면 이전 스테이지의 아티팩트를 전부 다운로드하지 않습니다. 기본적으로 needs를 가진 잡은 이전 스테이지가 끝나기 전에 시작될 수 있기 때문입니다. needs를 사용하면 needs 설정에 나열된 잡의 아티팩트만 다운로드할 수 있습니다.

artifacts: true(기본값) 또는 artifacts: false를 사용해 needs를 사용하는 잡에서 아티팩트가 다운로드되는 시점을 제어합니다.

키워드 유형: 잡 키워드. 잡의 일부로만 사용할 수 있습니다. needs:job과 함께 사용해야 합니다.

지원되는 값:

• true(기본값) 또는 false.

needs:artifacts 예시:

test-job1:
  stage: test
  needs:
    - job: build_job1
      artifacts: true

test-job2:
  stage: test
  needs:
    - job: build_job2
      artifacts: false

test-job3:
  needs:
    - job: build_job1
      artifacts: true
    - job: build_job2
    - build_job3

이 예시에서:

• test-job1 잡은 build_job1 아티팩트를 다운로드합니다
• test-job2 잡은 build_job2 아티팩트를 다운로드하지 않습니다.
• test-job3 잡은 세 build_jobs 모두의 아티팩트를 다운로드합니다. 세 개의 필요한 잡 전부에서 artifacts가 true 이거나 기본값인 true 이기 때문입니다.

추가 세부 정보:

• 같은 잡에서 needs와 dependencies를 함께 사용하지 않아야 합니다.

---

needs:project#

needs:project를 사용하면 다른 파이프라인의 최대 5개 잡에서 아티팩트를 다운로드할 수 있습니다. 아티팩트는 지정한 ref에 대해 지정한 잡이 마지막으로 성공한 실행에서 다운로드됩니다. 여러 잡을 지정하려면 needs 키워드 아래에 각각을 별도의 배열 항목으로 추가합니다.

해당 ref에 대해 실행 중인 파이프라인이 있어도 needs:project를 가진 잡은 파이프라인이 끝나기를 기다리지 않습니다. 대신 지정한 잡의 마지막 성공 실행에서 아티팩트를 다운로드합니다.

needs:project는 job, ref, artifacts와 함께 사용해야 합니다.

키워드 유형: 잡 키워드. 잡의 일부로만 사용할 수 있습니다.

지원되는 값:

• needs:project: 네임스페이스와 그룹을 포함한 전체 프로젝트 경로입니다.
• job: 아티팩트를 다운로드할 잡입니다.
• ref: 아티팩트를 다운로드할 ref 입니다.
• artifacts: 아티팩트를 다운로드하려면 true 여야 합니다.

needs:project 예시:

build_job:
  stage: build
  script:
    - ls -lhR
  needs:
    - project: namespace/group/project-name
      job: build-1
      ref: main
      artifacts: true
    - project: namespace/group/project-name-2
      job: build-2
      ref: main
      artifacts: true

이 예시에서 build_job은 group/project-name 및 group/project-name-2 프로젝트의 main 브랜치에서 마지막으로 성공한 build-1, build-2 잡의 아티팩트를 다운로드합니다.

needs:project에서 CI/CD 변수를 사용할 수 있습니다. 예:

build_job:
  stage: build
  script:
    - ls -lhR
  needs:
    - project: $CI_PROJECT_PATH
      job: $DEPENDENCY_JOB_NAME
      ref: $ARTIFACTS_DOWNLOAD_REF
      artifacts: true

추가 세부 정보:

• 현재 프로젝트의 다른 파이프라인에서 아티팩트를 다운로드하려면 project를 현재 프로젝트와 동일하게 설정하되, 현재 파이프라인과 다른 ref를 사용합니다. 같은 ref에서 실행되는 동시 파이프라인이 아티팩트를 덮어쓸 수 있습니다.
• 파이프라인을 실행하는 사용자는 해당 그룹 또는 프로젝트에 대해 Reporter, Developer, Maintainer, Owner 권한을 가지고 있어야 하며, 그렇지 않다면 그룹/프로젝트가 공개(public) 가시성이어야 합니다.
• trigger와 같은 잡에서 needs:project를 사용할 수 없습니다.
• needs:project로 다른 파이프라인의 아티팩트를 다운로드할 때, 잡은 필요한 잡이 끝나기를 기다리지 않습니다. needs를 사용해 잡이 끝나기를 기다리는 것은 같은 파이프라인 내의 잡으로 제한됩니다. 다른 파이프라인의 필요한 잡이 끝난 뒤에 이를 필요로 하는 잡이 아티팩트를 다운로드하도록 해야 합니다.
• parallel로 실행되는 잡에서는 아티팩트를 다운로드할 수 없습니다.
• project, job, ref에서 CI/CD 변수를 지원합니다.

관련 주제:

• 부모-자식 파이프라인 간에 아티팩트를 다운로드하려면 needs:pipeline:job을 사용합니다.

---

needs:pipeline:job#

히스토리

• optional 옵션이 GitLab 19.5에서 도입되었습니다.

자식 파이프라인은 성공적으로 끝난 잡의 아티팩트를 다운로드할 수 있습니다. 해당 잡은 부모 파이프라인이나 같은 계층에 있는 다른 자식 파이프라인에 있을 수 있습니다.

키워드 유형: 잡 키워드. 잡의 일부로만 사용할 수 있습니다.

지원되는 값:

• needs:pipeline: 파이프라인 ID 입니다. 같은 부모-자식 파이프라인 계층에 있는 파이프라인이어야 합니다.
• job: 아티팩트를 다운로드할 잡입니다.
• optional: needs:optional과 함께 사용하여, 부모 파이프라인에 때로는 존재하지 않는 잡을 needs로 지정합니다.

needs:pipeline:job 예시:

• 부모 파이프라인(.gitlab-ci.yml):

  stages:
    - build
    - test
  
  create-artifact:
    stage: build
    script: echo "sample artifact" > artifact.txt
    artifacts:
      paths: [artifact.txt]
  
  child-pipeline:
    stage: test
    trigger:
      include: child.yml
      strategy: mirror
    variables:
      PARENT_PIPELINE_ID: $CI_PIPELINE_ID
  

• 자식 파이프라인(child.yml):

  use-artifact:
    script: cat artifact.txt
    needs:
      - pipeline: $PARENT_PIPELINE_ID
        job: create-artifact
  

이 예시에서 부모 파이프라인의 create-artifact 잡은 아티팩트를 생성합니다. child-pipeline 잡은 자식 파이프라인을 트리거하고, CI_PIPELINE_ID 변수를 새로운 PARENT_PIPELINE_ID 변수로 자식 파이프라인에 전달합니다. 자식 파이프라인은 그 변수를 needs:pipeline에서 사용해 부모 파이프라인의 아티팩트를 다운로드할 수 있습니다. create-artifact 잡과 child-pipeline 잡을 연속된 스테이지에 두면 use-artifact 잡은 create-artifact가 성공적으로 끝난 뒤에만 실행됩니다.

추가 세부 정보:

• pipeline 속성은 현재 파이프라인 ID($CI_PIPELINE_ID)를 허용하지 않습니다. 현재 파이프라인의 잡에서 아티팩트를 다운로드하려면 needs:artifacts를 사용합니다.
• 트리거 잡에서 needs:pipeline:job을 사용하거나, 이를 사용해 다중 프로젝트 파이프라인에서 아티팩트를 가져올 수 없습니다. 다중 프로젝트 파이프라인에서 아티팩트를 가져오려면 needs:project를 사용합니다.
• needs:pipeline:job에 나열된 잡은 success 상태로 끝나야 하며, 그렇지 않으면 아티팩트를 가져올 수 없습니다. Issue 367229는 아티팩트가 있는 모든 잡에서 아티팩트를 가져올 수 있도록 허용하자고 제안합니다.

---

needs:optional#

파이프라인에 때로는 존재하지 않는 잡을 needs로 지정하려면 needs 설정에 optional: true를 추가합니다. 정의하지 않으면 기본값은 optional: false 입니다. needs:pipeline:job과 함께 optional: true를 사용하면 부모 파이프라인이나 다른 자식 파이프라인에 때로는 존재하지 않는 잡을 needs로 지정할 수 있습니다.

rules, only 또는 except를 사용하고 include로 추가되는 잡은 항상 파이프라인에 추가되는 것은 아닙니다. GitLab은 파이프라인을 시작하기 전에 needs 관계를 확인합니다.

• needs 항목에 optional: true가 있고 필요한 잡이 파이프라인에 있으면 잡은 시작하기 전에 그 잡이 끝나기를 기다립니다.
• 필요한 잡이 없으면, 다른 needs 요구 사항이 모두 충족될 때 잡을 시작할 수 있습니다.
• needs 섹션에 선택적(optional) 잡만 있고 그중 어느 것도 파이프라인에 추가되지 않으면 잡은(빈 needs 항목, 즉 needs: []와 마찬가지로) 즉시 시작됩니다.
• 필요한 잡이 optional: false 인데 파이프라인에 추가되지 않았다면 파이프라인은 시작에 실패하며 다음과 비슷한 오류가 발생합니다: 'job1' job needs 'job2' job, but it was not added to the pipeline.

키워드 유형: 잡 키워드. 잡의 일부로만 사용할 수 있습니다.

needs:optional 예시:

build-job:
  stage: build

test-job1:
  stage: test

test-job2:
  stage: test
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

deploy-job:
  stage: deploy
  needs:
    - job: test-job2
      optional: true
    - job: test-job1
  environment: production

review-job:
  stage: deploy
  needs:
    - job: test-job2
      optional: true
  environment: review

이 예시에서:

• build-job, test-job1, test-job2는 스테이지 순서대로 시작됩니다.
• 브랜치가 기본 브랜치이면 test-job2가 파이프라인에 추가되므로:
  • deploy-job은 test-job1과 test-job2가 모두 끝나기를 기다립니다.
  • review-job은 test-job2가 끝나기를 기다립니다.
• 브랜치가 기본 브랜치가 아니면 test-job2가 파이프라인에 추가되지 않으므로:
  • deploy-job은 test-job1 이 끝나기만 기다리고, 존재하지 않는 test-job2는 기다리지 않습니다.
  • review-job은 다른 필요한 잡이 없어 (build-job과 동시에) needs: []처럼 즉시 시작됩니다.

추가 세부 정보:

• needs:parallel:matrix와 함께 needs:optional을 사용할 수 없습니다.

---

needs:pipeline#

needs:pipeline 키워드를 사용하면 업스트림 파이프라인의 상태를 잡에 미러링할 수 있습니다. 기본 브랜치의 최신 파이프라인 상태가 잡에 복제됩니다.

키워드 유형: 잡 키워드. 잡의 일부로만 사용할 수 있습니다.

지원되는 값:

• 네임스페이스와 그룹을 포함한 전체 프로젝트 경로입니다. 프로젝트가 같은 그룹 또는 네임스페이스에 있으면 project 키워드에서 이를 생략할 수 있습니다. 예: project: group/project-name 또는 project: project-name.

needs:pipeline 예시:

upstream_status:
  stage: test
  needs:
    pipeline: other/project

추가 세부 정보:

• needs:pipeline에 job 키워드를 추가하면 잡은 더 이상 파이프라인 상태를 미러링하지 않습니다. 동작이 needs:pipeline:job으로 바뀝니다.

---

needs:parallel:matrix#

잡은 parallel:matrix를 사용해 하나의 파이프라인에서 잡을 여러 번 병렬로 실행할 수 있습니다. 잡의 각 인스턴스는 서로 다른 변수 값을 사용합니다.

needs:parallel:matrix를 사용하면 병렬화된 잡에 따라 잡을 순서와 무관하게 실행할 수 있습니다.

키워드 유형: 잡 키워드. 잡의 일부로만 사용할 수 있습니다. needs:job과 함께 사용해야 합니다.

지원되는 값: 매트릭스 식별자 해시의 배열입니다:

• 식별자와 값은 parallel:matrix 잡에 정의된 식별자와 값 중에서 선택해야 합니다.
• 매트릭스 표현식을 사용할 수 있습니다.

needs:parallel:matrix 예시:

linux:build:
  stage: build
  script: echo "Building linux..."
  parallel:
    matrix:
      - PROVIDER: aws
        STACK:
          - monitoring
          - app1
          - app2

linux:rspec:
  stage: test
  needs:
    - job: linux:build
      parallel:
        matrix:
          - PROVIDER: aws
            STACK: app1
  script: echo "Running rspec on linux..."

이전 예시는 다음 잡을 생성합니다:

linux:build: [aws, monitoring]
linux:build: [aws, app1]
linux:build: [aws, app2]
linux:rspec

linux:rspec 잡은 linux:build: [aws, app1] 잡이 끝나는 즉시 실행됩니다.

추가 세부 정보:

• needs:optional과 함께 needs:parallel:matrix를 사용할 수 없습니다.

• needs:parallel:matrix의 매트릭스 식별자 순서는 필요한 잡의 매트릭스 변수 순서와 일치해야 합니다. 예를 들어 이전 예시의 linux:rspec 잡에서 변수 순서를 바꾸면 다음과 같이 잘못된 것이 됩니다:

  linux:rspec:
    stage: test
    needs:
      - job: linux:build
        parallel:
          matrix:
            - STACK: app1        # The variable order does not match `linux:build` and is invalid.
              PROVIDER: aws
    script: echo "Running rspec on linux..."
  

관련 주제:

• needs와 여러 병렬화된 잡을 사용해 병렬화된 잡을 지정하기.
• needs:parallel:matrix의 매트릭스 표현식.

pages#

pages를 사용하여 정적 콘텐츠를 GitLab에 업로드하는 GitLab Pages 잡을 정의합니다. 이 콘텐츠는 이후 웹사이트로 게시됩니다.

다음을 수행해야 합니다.

• public이라는 이름의 디렉터리를 게시하려면 pages: true를 정의합니다.
• 다른 콘텐츠 디렉터리를 사용하려면 대신 pages.publish를 정의합니다.
• 콘텐츠 디렉터리 루트에 비어 있지 않은 index.html 파일을 둡니다.

키워드 유형: 잡 키워드 또는 잡 이름(지원 중단). 잡의 일부로만 사용할 수 있습니다.

지원되는 값:

• 불리언. true로 설정하면 기본 설정을 사용합니다.
• 설정 옵션의 해시. 자세한 내용은 다음 섹션을 참고합니다.

pages 예시:

create-pages:
  stage: deploy
  script:
    - mv my-html-content public
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production

이 예시는 my-html-content/ 디렉터리 이름을 public/로 변경합니다. 이 디렉터리는 아티팩트로 내보내져 GitLab Pages로 게시됩니다.

설정 해시를 사용하는 예시:

create-pages:
  stage: deploy
  script:
    - echo "nothing to do here"
  pages:  # specifies that this is a Pages job and publishes the default public directory
    publish: my-html-content
    expire_in: "1 week"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production

이 예시는 디렉터리를 이동하지 않고 publish 속성을 직접 사용합니다. 또한 페이지 배포가 1주일 후 게시 해제되도록 설정합니다.

추가 세부 정보:

• pages를 잡 이름으로 사용하는 것은 지원이 중단되었습니다.
• Pages 배포를 트리거하지 않고 pages를 잡 이름으로 사용하려면 pages 속성을 false로 설정합니다.

---

pages.publish#

히스토리

• GitLab 17.9에서 publish 속성에 전달할 때 변수를 허용하도록 변경되었습니다.
• GitLab 17.9에서 publish 속성이 pages 키워드 아래로 이동되었습니다.
• GitLab 17.10에서 pages.publish 경로가 artifacts:paths에 자동으로 추가되었습니다.

pages.publish를 사용하여 pages 잡의 콘텐츠 디렉터리를 설정합니다.

키워드 유형: 잡 키워드. pages 잡의 일부로만 사용할 수 있습니다.

지원되는 값: Pages 콘텐츠가 포함된 디렉터리 경로. GitLab 17.10 이상에서 지정하지 않으면 기본 public 디렉터리가 사용되며, 지정하면 이 경로가 artifacts:paths에 자동으로 추가됩니다.

pages.publish 예시:

create-pages:
  stage: deploy
  script:
    - npx @11ty/eleventy --input=path/to/eleventy/root --output=dist
  pages:
    publish: dist  # this path is automatically appended to artifacts:paths
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production

이 예시는 Eleventy를 사용하여 정적 웹사이트를 생성하고 생성된 HTML 파일을 dist/ 디렉터리에 출력합니다. 이 디렉터리는 아티팩트로 내보내져 GitLab Pages로 게시됩니다.

pages.publish 필드에서 변수를 사용할 수도 있습니다. 예를 들면 다음과 같습니다.

create-pages:
  stage: deploy
  script:
    - mkdir -p $CUSTOM_FOLDER/$CUSTOM_PATH
    - cp -r public $CUSTOM_FOLDER/$CUSTOM_SUBFOLDER
  pages:
    publish: $CUSTOM_FOLDER/$CUSTOM_SUBFOLDER  # this path is automatically appended to artifacts:paths
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  variables:
    CUSTOM_FOLDER: "custom_folder"
    CUSTOM_SUBFOLDER: "custom_subfolder"

지정한 게시 경로는 빌드 루트를 기준으로 한 상대 경로여야 합니다.

추가 세부 정보:

• 최상위 publish 키워드는 지원이 중단되었으며 이제 pages 키워드 아래에 중첩해야 합니다.

---

pages.path_prefix#

히스토리

• GitLab 16.7에서 pages_multiple_versions_setting이라는 이름의 기능 플래그와 함께 실험 기능으로 도입되었으며, 기본적으로 비활성화되어 있습니다.
• GitLab 17.4에서 GitLab.com, GitLab Self-Managed, GitLab Dedicated에서 활성화되었습니다.
• GitLab 17.8에서 마침표를 허용하도록 변경되었습니다.
• GitLab 17.9에서 일반 공급되었습니다. 기능 플래그 pages_multiple_versions_setting 이 제거되었습니다.

pages.path_prefix를 사용하여 GitLab Pages의 병렬 배포에 대한 경로 접두사를 설정합니다.

키워드 유형: 잡 키워드. pages 잡의 일부로만 사용할 수 있습니다.

지원되는 값:

• 문자열
• CI/CD 변수
• 둘의 조합

지정한 값은 소문자로 변환되고 63바이트로 축약됩니다. 영숫자와 마침표를 제외한 모든 문자는 하이픈으로 대체됩니다. 앞뒤에 하이픈이나 마침표는 허용되지 않습니다.

pages.path_prefix 예시:

create-pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}"
  pages:  # specifies that this is a Pages job and publishes the default public directory
    path_prefix: "$CI_COMMIT_BRANCH"

이 예시에서는 브랜치마다 서로 다른 페이지 배포가 생성됩니다.

---

pages.expire_in#

히스토리

• GitLab 17.4에서 도입되었습니다.
• GitLab 17.11에서 변수 지원이 도입되었습니다.

expire_in을 사용하여 배포가 만료되기 전까지 사용 가능한 기간을 지정합니다. 배포가 만료된 후에는 10분마다 실행되는 크론 잡에 의해 비활성화됩니다.

기본적으로 병렬 배포는 24시간 후 자동으로 만료됩니다. 이 동작을 비활성화하려면 값을 never로 설정합니다.

키워드 유형: 잡 키워드. pages 잡의 일부로만 사용할 수 있습니다.

지원되는 값: 만료 시간. 단위를 지정하지 않으면 초 단위로 처리됩니다. 변수도 지원됩니다. 유효한 값은 다음과 같습니다.

• '42'
• 42 seconds
• 3 mins 4 sec
• 2 hrs 20 min
• 2h20min
• 6 mos 1 day
• 47 yrs 6 mos and 4d
• 3 weeks and 2 days
• never
• $DURATION

pages.expire_in 예시:

create-pages:
  stage: deploy
  script:
    - echo "Pages accessible through ${CI_PAGES_URL}"
  pages:  # specifies that this is a Pages job and publishes the default public directory
    expire_in: 1 week

---

parallel#

parallel을 사용하여 단일 파이프라인에서 잡을 여러 번 병렬로 실행합니다.

여러 러너가 존재하거나, 단일 러너가 여러 잡을 동시에 실행하도록 설정되어 있어야 합니다.

병렬 잡은 job_name 1/N부터 job_name N/N까지 순차적으로 이름이 지정됩니다.

키워드 유형: 잡 키워드. 잡의 일부로만 사용할 수 있습니다.

지원되는 값:

• 1부터 200 까지의 숫자 값.

parallel 예시:

test:
  script: rspec
  parallel: 5

이 예시는 test 1/5부터 test 5/5까지 이름이 지정된, 병렬로 실행되는 5개의 잡을 생성합니다.

추가 세부 정보:

• 모든 병렬 잡에는 CI_NODE_INDEX 및 CI_NODE_TOTAL 사전 정의된 CI/CD 변수가 설정됩니다.
• parallel을 사용하는 잡이 있는 파이프라인은 다음과 같이 동작할 수 있습니다.
  • 사용 가능한 러너보다 더 많은 잡을 병렬로 생성합니다. 초과된 잡은 대기열에 들어가 사용 가능한 러너를 기다리는 동안 pending으로 표시됩니다.
  • 파이프라인을 생성하면 모든 활성 파이프라인의 전체 잡 수가 인스턴스 제한을 초과하게 되는 경우 job_activity_limit_exceeded 오류와 함께 실패합니다.

관련 항목:

• 대규모 잡 병렬화.

---

parallel:matrix#

parallel:matrix를 사용하여 단일 파이프라인에서 잡을 여러 번 병렬로 실행하되, 잡 인스턴스마다 서로 다른 변수 값을 사용합니다.

여러 러너가 존재하거나, 단일 러너가 여러 잡을 동시에 실행하도록 설정되어 있어야 합니다.

키워드 유형: 잡 키워드. 잡의 일부로만 사용할 수 있습니다.

지원되는 값: 변수 해시의 배열입니다.

• 변수 이름이 되는 매트릭스 식별자는 숫자, 문자, 밑줄(_)만 사용할 수 있습니다.
• 값은 문자열이거나 문자열의 배열이어야 합니다.
• 순열의 수는 200 개를 초과할 수 없습니다.

parallel:matrix 예시:

deploystacks:
  stage: deploy
  script:
    - bin/deploy
  parallel:
    matrix:
      - PROVIDER: aws
        STACK:
          - monitoring
          - app1
          - app2
      - PROVIDER: [gcp, vultr]
        STACK: [data, processing]
  environment: $PROVIDER/$STACK

이 예시는 PROVIDER와 STACK에 대해 서로 다른 값을 가진 7개의 병렬 deploystacks 잡을 생성합니다.

• deploystacks: [aws, monitoring]
• deploystacks: [aws, app1]
• deploystacks: [aws, app2]
• deploystacks: [gcp, data]
• deploystacks: [gcp, processing]
• deploystacks: [vultr, data]
• deploystacks: [vultr, processing]

추가 세부 정보:

• parallel:matrix 잡은 잡을 서로 구분하기 위해 매트릭스 값을 잡 이름에 추가합니다. 하지만 값이 길면 잡 이름이 255자 제한을 초과할 수 있습니다. 자세한 내용은 epic 11791을 참고합니다.

• 매트릭스 변수 값은 rules:if 표현식에서 CI/CD 변수로 사용할 수 있습니다. 자세한 내용은 rules:if에서 매트릭스 변수 사용을 참고합니다.

• 값은 같지만 이름이 다른 여러 매트릭스 설정을 만들 수는 없습니다. 잡 이름은 이름이 아니라 매트릭스 값으로 생성되므로, 값이 동일한 매트릭스 항목은 동일한 잡 이름을 생성하며 서로를 덮어씁니다.

  예를 들어 다음 test 설정은 동일한 잡 시리즈 두 개를 만들려고 시도하지만, OS2 버전이 OS 버전을 덮어씁니다.

  test:
    parallel:
      matrix:
        - OS: [ubuntu]
          PROVIDER: [aws, gcp]
        - OS2: [ubuntu]
          PROVIDER: [aws, gcp]
  

관련 항목:

• 1차원 매트릭스의 병렬 잡 실행.
• 병렬 트리거 잡의 매트릭스 실행.
• 매트릭스 병렬 잡마다 다른 러너 태그 선택.
• 규칙에서 매트릭스 변수 사용.
• needs:parallel:matrix의 매트릭스 표현식.

---

release#

release를 사용하여 릴리스를 생성합니다.

릴리스 잡은 glab CLI에 접근할 수 있어야 하며, glab CLI는 $PATH에 있어야 합니다.

Docker 실행기를 사용하는 경우, GitLab 컨테이너 레지스트리의 다음 이미지를 사용할 수 있습니다: registry.gitlab.com/gitlab-org/cli:latest

셸 실행기 또는 유사한 실행기를 사용하는 경우, 러너가 등록된 서버에 glab CLI를 설치합니다.

키워드 유형: 잡 키워드. 잡의 일부로만 사용할 수 있습니다.

지원되는 값: release 하위 키:

• tag_name
• tag_message (선택 사항)
• name (선택 사항)
• description
• ref (선택 사항)
• milestones (선택 사항)
• released_at (선택 사항)
• assets:links (선택 사항)

release 키워드 예시:

release_job:
  stage: release
  image: registry.gitlab.com/gitlab-org/cli:latest
  rules:
    - if: $CI_COMMIT_TAG                  # Run this job when a tag is created manually
  script:
    - echo "Running the release job."
  release:
    tag_name: $CI_COMMIT_TAG
    name: 'Release $CI_COMMIT_TAG'
    description: 'Release created using the CLI.'

이 예시는 다음의 경우 릴리스를 생성합니다.

• Git 태그를 푸시할 때.
• UI의 Code > Tags에서 Git 태그를 추가할 때.

추가 세부 정보:

• 릴리스 잡에는 script 키워드가 포함되어야 합니다. 릴리스 잡은 스크립트 명령의 출력을 사용할 수 있습니다. 스크립트가 필요하지 않다면 자리 표시자를 사용할 수 있습니다.

  script:
    - echo "release job"
  

  자세한 내용은 이 제약을 없애는 것을 목표로 하는 issue 223856을 참고합니다.

• release 섹션은 script 키워드 이후, after_script 이전에 실행됩니다.

• 릴리스는 잡의 메인 스크립트가 성공한 경우에만 생성됩니다.

• 릴리스가 이미 존재하면 업데이트되지 않으며 release 키워드가 포함된 잡은 실패합니다.

• release 키워드는 glab CLI를 사용하며 glab release create로 릴리스를 생성합니다. 릴리스는 기본적으로 CI_JOB_TOKEN으로 인증됩니다. 잡에 다음 CI/CD 변수 중 하나라도 정의되어 있으면 glab은 대신 그 토큰을 사용하며, 순서는 GITLAB_TOKEN, GITLAB_ACCESS_TOKEN, OAUTH_TOKEN 순입니다. 이 토큰들은 glab의 토큰 해석에서 CI_JOB_TOKEN보다 우선합니다. 이 토큰에 필요한 API 스코프가 없으면 릴리스가 401 Unauthorized 오류로 실패할 수 있습니다.

관련 항목:

• release 키워드의 CI/CD 예시.
• release-cli에서 glab CLI로 마이그레이션
• 단일 파이프라인에서 여러 릴리스 생성.
• 사용자 지정 SSL CA 인증 기관 사용.

---

release:tag_name#

필수 항목입니다. 릴리스에 사용할 Git 태그입니다.

프로젝트에 아직 태그가 없으면 릴리스와 동시에 생성됩니다. 새 태그는 파이프라인에 연결된 SHA를 사용합니다.

키워드 유형: 잡 키워드. 잡의 일부로만 사용할 수 있습니다.

지원되는 값:

• 태그 이름.

CI/CD 변수를 지원합니다.

release:tag_name 예시:

프로젝트에 새 태그가 추가될 때 릴리스를 생성하려면 다음과 같이 합니다.

• tag_name으로 $CI_COMMIT_TAG CI/CD 변수를 사용합니다.
• rules:if를 사용하여 새 태그에 대해서만 잡이 실행되도록 설정합니다.

job:
  script: echo "Running the release job for the new tag."
  release:
    tag_name: $CI_COMMIT_TAG
    description: 'Release description'
  rules:
    - if: $CI_COMMIT_TAG

릴리스와 새 태그를 동시에 생성하려면, rules가 새 태그에 대해서만 잡이 실행되도록 설정해서는 안 됩니다. 시맨틱 버전 관리 예시는 다음과 같습니다.

job:
  script: echo "Running the release job and creating a new tag."
  release:
    tag_name: ${MAJOR}_${MINOR}_${REVISION}
    description: 'Release description'
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"

---

release:tag_message#

태그가 존재하지 않으면, 새로 생성되는 태그에는 tag_message로 지정한 메시지가 주석으로 달립니다. 생략하면 경량 태그가 생성됩니다.

키워드 유형: 잡 키워드. 잡의 일부로만 사용할 수 있습니다.

지원되는 값:

• 텍스트 문자열.

release:tag_message 예시:

  release_job:
    stage: release
    release:
      tag_name: $CI_COMMIT_TAG
      description: 'Release description'
      tag_message: 'Annotated tag message'

---

release:name#

릴리스 이름입니다. 생략하면 release: tag_name의 값으로 채워집니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• 텍스트 문자열입니다.

release:name 예시:

  release_job:
    stage: release
    release:
      name: 'Release $CI_COMMIT_TAG'

---

release:description#

릴리스에 대한 긴 설명입니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• 긴 설명이 담긴 문자열입니다.
• 설명이 담긴 파일의 경로입니다.
  • 파일 위치는 프로젝트 디렉터리($CI_PROJECT_DIR)에 대한 상대 경로여야 합니다.
  • 파일이 심볼릭 링크인 경우 $CI_PROJECT_DIR 안에 있어야 합니다.
  • ./path/to/file와 파일명에는 공백을 포함할 수 없습니다.

release:description 예시:

job:
  release:
    tag_name: ${MAJOR}_${MINOR}_${REVISION}
    description: './path/to/CHANGELOG.md'

추가 세부 정보:

• description은 glab을 실행하는 셸에서 평가됩니다. CI/CD 변수를 사용해 설명을 정의할 수 있지만, 일부 셸은 변수를 참조하기 위해 다른 구문을 사용합니다. 또한 일부 셸에서는 특수 문자를 이스케이프해야 할 수 있습니다. 예를 들어 백틱(`)은 백슬래시(\)로 이스케이프해야 할 수 있습니다.

---

release:ref#

release: tag_name 이 아직 존재하지 않는 경우 릴리스에 사용할 ref 입니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• 커밋 SHA, 다른 태그 이름, 또는 브랜치 이름입니다.

---

release:milestones#

릴리스와 연결된 각 마일스톤의 제목입니다.

---

release:released_at#

릴리스가 준비되는 날짜와 시간입니다.

지원되는 값:

• 따옴표로 묶고 ISO 8601 형식으로 표현한 날짜입니다.

release:released_at 예시:

released_at: '2021-03-15T08:00:00Z'

추가 세부 정보:

• 정의하지 않으면 현재 날짜와 시간이 사용됩니다.

---

release:assets:links#

릴리스에 에셋 링크를 포함하려면 release:assets:links를 사용합니다.

release:assets:links 예시:

assets:
  links:
    - name: 'asset1'
      url: 'https://example.com/assets/1'
    - name: 'asset2'
      url: 'https://example.com/assets/2'
      filepath: '/pretty/url/1' # optional
      link_type: 'other' # optional

---

resource_group#

resource_group을 사용하면 동일한 프로젝트의 서로 다른 파이프라인에서 job 이 상호 배타적으로 실행되도록 보장하는 리소스 그룹을 만들 수 있습니다.

예를 들어 동일한 리소스 그룹에 속한 여러 job 이 동시에 큐에 들어가면 그중 하나의 job만 시작됩니다. 나머지 job은 resource_group 이 해제될 때까지 대기합니다.

리소스 그룹은 다른 프로그래밍 언어의 세마포어와 유사하게 동작합니다.

배포 방식에 맞게 job 동시성을 전략적으로 제어하려면 프로세스 모드를 선택할 수 있습니다. 기본 프로세스 모드는 unordered 입니다. 리소스 그룹의 프로세스 모드를 변경하려면 API를 사용해 기존 리소스 그룹을 수정하는 요청을 보냅니다.

환경마다 여러 리소스 그룹을 정의할 수 있습니다. 예를 들어 물리 장치에 배포할 때 여러 대의 물리 장치가 있을 수 있습니다. 각 장치는 배포 대상이 될 수 있지만, 특정 시점에 장치당 하나의 배포만 진행할 수 있습니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• 문자, 숫자, -, _, /, $, {, }, ., 공백만 사용할 수 있습니다. /로 시작하거나 끝날 수 없습니다. CI/CD 변수를 사용할 수 있습니다.

resource_group 예시:

deploy-to-production:
  script: deploy
  resource_group: production

이 예시에서는 서로 다른 두 파이프라인의 deploy-to-production job 두 개가 동시에 실행될 수 없습니다. 그 결과 프로덕션 환경에 동시 배포가 발생하지 않도록 보장할 수 있습니다.

관련 항목:

• 크로스 프로젝트/부모-자식 파이프라인에서의 파이프라인 수준 동시성 제어.

---

retry#

job 이 실패했을 때 재시도할 횟수를 설정하려면 retry를 사용합니다. 정의하지 않으면 기본값은 0 이며 job은 재시도되지 않습니다.

job 이 실패하면 성공하거나 최대 재시도 횟수에 도달할 때까지 최대 두 번 더 처리됩니다.

기본적으로 모든 실패 유형에서 job 이 재시도됩니다. 재시도할 실패를 선택하려면 retry:when 또는 retry:exit_codes를 사용합니다.

키워드 유형: job 키워드입니다. job의 일부로 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• 0(기본값), 1, 또는 2 입니다.

retry 예시:

test:
  script: rspec
  retry: 2

test_advanced:
  script:
    - echo "Run a script that results in exit code 137."
    - exit 137
  retry:
    max: 2
    when: runner_system_failure
    exit_codes: 137

test_advanced는 종료 코드가 137 이거나 러너 시스템 실패가 있는 경우 최대 2번 재시도됩니다.

---

retry:when#

특정 실패 상황에서만 job을 재시도하려면 retry:when을 retry:max와 함께 사용합니다. retry:max는 retry와 마찬가지로 최대 재시도 횟수이며 0, 1, 또는 2 일 수 있습니다.

키워드 유형: job 키워드입니다. job의 일부로 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• 단일 실패 유형 또는 하나 이상의 실패 유형으로 이루어진 배열입니다.

• always: 모든 실패에서 재시도합니다(기본값).
• unknown_failure: 실패 원인을 알 수 없을 때 재시도합니다.
• script_failure: 다음의 경우 재시도합니다.
  • 스크립트가 실패한 경우입니다.
  • 러너가 Docker 이미지를 pull 하지 못한 경우입니다. docker, docker+machine, kubernetes executor에 해당합니다.
  • GitLab 19.1에서 도입되어, 일부 실패는 script_failure에서 더 정확한 runner_configuration_error로 변경됩니다.
• api_failure: API 실패 시 재시도합니다.
• stuck_or_timeout_failure: job 이 멈추거나 타임아웃되었을 때 재시도합니다. GitLab 19.1에서 더 이상 사용되지 않습니다. stuck_pending_with_matching_runners, stuck_pending_no_matching_runners, no_updates_running, no_updates_canceling 중 하나에서 재시도합니다. 대신 이 값들을 사용합니다. GitLab 19.0 이상에서 이 이유는 과거 데이터용으로만 보존됩니다. 새 job은 아래에 나열된 더 구체적인 이유 중 하나를 대신 사용합니다. 이러한 경우에 job을 재시도하려면 새 이유도 함께 구성합니다.
• stuck_pending_with_matching_runners: 일치하는 러너를 사용할 수 있는데도 job이 대기 중 상태로 오래 머무는 경우 재시도합니다.
• stuck_pending_no_matching_runners: 러너가 job의 요구 사항(예: 태그 또는 보호 상태)과 일치하지 않아 job이 대기 중 상태로 머무는 경우 재시도합니다.
• no_updates_running: job이 실행 중 상태이지만 job 스크립트가 멈추거나 러너 연결이 끊기는 등의 이유로 오랫동안 활동이 없는 경우 재시도합니다.
• no_updates_canceling: job이 취소 중 상태이지만 오랫동안 활동이 없는 경우 재시도합니다.
• runner_system_failure: 러너 시스템 실패가 있는 경우(예: job 설정 실패) 재시도합니다.
  • GitLab 19.1에서 도입되어, 일부 실패는 runner_system_failure에서 더 정확한 runner_external_dependency_failure 또는 runner_interrupted로 변경됩니다.
• runner_configuration_error: 잘못된 이미지나 태그, 호환되지 않는 pull 정책, 잘못 구성된 러너 등 CI/CD 또는 러너 설정 오류로 job 이 실패한 경우 재시도합니다.
• runner_external_dependency_failure: 네트워크나 DNS 문제로 러너가 이미지 레지스트리 같은 외부 의존성에 접근하지 못한 경우 재시도합니다.
• runner_interrupted: 재시작, 종료, 호스트 회수 등으로 job 실행 중 러너가 중단된 경우 재시도합니다.
• runner_unsupported: 러너가 지원되지 않는 경우 재시도합니다.
• stale_schedule: 지연된 job을 실행할 수 없는 경우 재시도합니다.
• job_execution_timeout: 스크립트가 job에 설정된 최대 실행 시간을 초과한 경우 재시도합니다. GitLab 19.1에서 더 이상 사용되지 않습니다. server_timeout_running 또는 server_timeout_canceling에서 재시도합니다. 대신 이 값들을 사용합니다.
• server_timeout_running: 실행 중인 job이 최대 실행 시간을 초과하여 서버 측 타임아웃 적용으로 job이 중단되는 경우 재시도합니다.
• server_timeout_canceling: 취소 중인 job이 최대 실행 시간을 초과하여 서버 측 타임아웃 적용으로 취소 중에 job이 중단되는 경우 재시도합니다.
• archived_failure: job 이 보관되어 실행할 수 없는 경우 재시도합니다.
• unmet_prerequisites: job 이 선행 작업을 완료하지 못한 경우 재시도합니다.
• scheduler_failure: 스케줄러가 job을 러너에 할당하지 못한 경우 재시도합니다.
• data_integrity_failure: 알 수 없는 job 문제가 있는 경우 재시도합니다.

retry:when 예시(단일 실패 유형):

test:
  script: rspec
  retry:
    max: 2
    when: runner_system_failure

러너 시스템 실패가 아닌 다른 실패가 발생하면 job은 재시도되지 않습니다.

retry:when 예시(실패 유형 배열):

test:
  script: rspec
  retry:
    max: 2
    when:
      - runner_system_failure
      - stuck_pending_with_matching_runners
      - stuck_pending_no_matching_runners
      - no_updates_running

---

retry:exit_codes#

히스토리

• GitLab 16.10에서 ci_retry_on_exit_codes라는 이름의 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 16.11에서 GitLab.com 및 GitLab Self-Managed에서 활성화되었습니다.
• GitLab 17.5에서 일반 공급(GA)되었습니다. 기능 플래그 ci_retry_on_exit_codes가 제거되었습니다.

특정 실패 상황에서만 job을 재시도하려면 retry:exit_codes를 retry:max와 함께 사용합니다. retry:max는 retry와 마찬가지로 최대 재시도 횟수이며 0, 1, 또는 2 일 수 있습니다.

키워드 유형: job 키워드입니다. job의 일부로 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값:

• 단일 종료 코드입니다.
• 종료 코드 배열입니다.

retry:exit_codes 예시:

test_job_1:
  script:
    - echo "Run a script that results in exit code 1. This job isn't retried."
    - exit 1
  retry:
    max: 2
    exit_codes: 137

test_job_2:
  script:
    - echo "Run a script that results in exit code 137. This job will be retried."
    - exit 137
  retry:
    max: 1
    exit_codes:
      - 255
      - 137

관련 항목:

변수를 사용해 job 실행의 특정 단계에 대한 재시도 횟수를 지정할 수 있습니다.

---

rules#

파이프라인에 job을 포함하거나 제외하려면 rules를 사용합니다.

규칙은 파이프라인이 생성될 때 순서대로 평가됩니다. 일치하는 항목을 찾으면 더 이상 규칙을 확인하지 않으며, 설정에 따라 job 이 파이프라인에 포함되거나 제외됩니다. 일치하는 규칙이 없으면 job은 파이프라인에 추가되지 않습니다.

rules는 규칙의 배열을 받습니다. 각 규칙에는 다음 중 최소 하나가 있어야 합니다.

• if
• changes
• exists
• when

규칙은 다음과 선택적으로 결합할 수도 있습니다.

• allow_failure
• needs
• variables
• interruptible

복잡한 규칙을 위해 여러 키워드를 함께 결합할 수 있습니다.

다음의 경우 job 이 파이프라인에 추가됩니다.

• if, changes, exists 규칙이 일치하고 when: on_success(정의하지 않은 경우 기본값), when: delayed, when: always 중 하나로 설정된 경우입니다.
• when: on_success, when: delayed, when: always만 있는 규칙에 도달한 경우입니다.

다음의 경우 job 이 파이프라인에 추가되지 않습니다.

• 일치하는 규칙이 없는 경우입니다.
• 규칙이 일치하고 when: never 인 경우입니다.

추가 예시는 rules로 job 실행 시점 지정하기를 참고합니다.

---

rules:if#

job을 파이프라인에 추가할 시점을 지정하려면 rules:if 절을 사용합니다.

• if 문이 참이면 job을 파이프라인에 추가합니다.
• if 문이 참이지만 when: never와 결합된 경우 job을 파이프라인에 추가하지 않습니다.
• if 문이 거짓이면 다음 rules 항목을 확인합니다(더 있는 경우).

if 절은 다음과 같이 평가됩니다.

• CI/CD 변수 또는 사전 정의된 CI/CD 변수의 값을 기준으로 평가되며, 일부 예외가 있습니다.
• rules 실행 흐름에 따라 순서대로 평가됩니다.

job 간에 규칙이 일관되지 않으면 예기치 않은 동작으로 이어질 수 있지만, workflow 규칙으로 이 문제를 완화할 수 있습니다. 예를 들어 실수로 중복 파이프라인을 유발하는 job을 설정할 수 있습니다.

키워드 유형: job 전용이면서 파이프라인 전용입니다. job의 동작을 설정하기 위해 job의 일부로 사용하거나, 파이프라인 동작을 설정하기 위해 workflow와 함께 사용할 수 있습니다.

지원되는 값:

• CI/CD 변수 표현식입니다.

rules:if 예시:

job:
  script: echo "Hello, Rules!"
  rules:
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME != $CI_DEFAULT_BRANCH
      when: never
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/
      when: manual
      allow_failure: true
    - if: $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME

추가 세부 정보:

• if와 함께 중첩 변수를 사용할 수 없습니다. 자세한 내용은 이슈 327780을 참고합니다.
• 규칙이 일치하고 when 이 정의되지 않은 경우, 규칙은 job에 정의된 when을 사용하며, 정의되지 않은 경우 기본값은 on_success 입니다.
• job 수준의 when과 규칙 안의 when을 함께 사용할 수 있습니다. rules 안의 when 설정이 job 수준의 when보다 우선합니다.
• script 안의 변수와 달리 규칙 표현식 안의 변수는 항상 $VARIABLE 형식으로 작성합니다.
  • rules:if를 include와 함께 사용해 다른 설정 파일을 조건부로 포함할 수 있습니다.
• =~와 !~ 표현식의 오른쪽에 있는 CI/CD 변수는 정규 표현식으로 평가됩니다.

관련 항목:

• rules에 자주 쓰이는 if 표현식입니다.
• rules를 사용해 머지 리퀘스트 파이프라인 실행하기입니다.

---

rules:changes#

특정 파일의 변경 여부를 확인해 job을 파이프라인에 추가할 시점을 지정하려면 rules:changes를 사용합니다.

새 브랜치 파이프라인이거나 Git push 이벤트가 없는 경우 rules: changes는 항상 참으로 평가되어 job 이 항상 실행됩니다. 태그 파이프라인, 예약 파이프라인, 수동 파이프라인 같은 파이프라인에는 모두 연관된 Git push 이벤트가 없습니다. 이런 경우를 처리하려면 rules: changes: compare_to를 사용해 파이프라인 ref와 비교할 브랜치를 지정합니다.

compare_to를 사용하지 않는다면 rules: changes는 브랜치 파이프라인이나 머지 리퀘스트 파이프라인에서만 사용해야 합니다. 다만 새 브랜치를 생성할 때는 rules: changes가 여전히 참으로 평가됩니다. 다음과 함께 사용하는 경우:

• 머지 리퀘스트 파이프라인에서 rules:changes는 변경 사항을 타깃 MR 브랜치와 비교합니다.
• 브랜치 파이프라인에서 rules:changes는 변경 사항을 브랜치의 이전 커밋과 비교합니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

다음을 임의 개수만큼 포함하는 배열입니다.

• 파일 경로입니다. 파일 경로에는 CI/CD 변수를 포함할 수 있습니다.
• 다음에 대한 와일드카드 경로입니다.
  • 단일 디렉터리(예: path/to/directory/*)입니다.
  • 디렉터리와 그 모든 하위 디렉터리(예: path/to/directory/**/*)입니다.
• 동일한 확장자 또는 여러 확장자를 가진 모든 파일에 대한 와일드카드 glob 경로(예: *.md 또는 path/to/directory/*.{rb,py,sh})입니다. *로 시작하는 경로는 큰따옴표(")로 감싸야 합니다.
• 큰따옴표로 감싼, 루트 디렉터리 또는 모든 디렉터리의 파일에 대한 와일드카드 경로입니다. 예를 들어 "*.json" 또는 "**/*.json" 입니다.

rules:changes 예시:

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - Dockerfile
      when: manual
      allow_failure: true

docker build alternative:
  variables:
    DOCKERFILES_DIR: 'path/to/dockerfiles'
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - $DOCKERFILES_DIR/**/*

이 예시에서는 다음과 같습니다.

• 파이프라인이 머지 리퀘스트 파이프라인인 경우 Dockerfile과 $DOCKERFILES_DIR/**/*의 파일에 변경 사항이 있는지 확인합니다.
• Dockerfile 이 변경된 경우 job을 수동 job으로 파이프라인에 추가하며, job 이 트리거되지 않아도 파이프라인은 계속 실행됩니다(allow_failure: true).
• $DOCKERFILES_DIR/**/* 안의 파일이 변경된 경우 job을 파이프라인에 추가합니다.
• 나열된 파일 중 변경된 것이 없으면 두 job 모두 어떤 파이프라인에도 추가하지 않습니다(when: never와 동일).

추가 세부 정보:

• Glob 패턴은 Ruby의 File.fnmatch로 플래그를 사용해 해석됩니다. File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB 입니다.
• 성능상의 이유로 GitLab은 changes 패턴 또는 파일 경로에 대해 최대 50,000회까지 검사합니다. 50,000번째 검사 이후에는 패턴화된 glob 이 있는 규칙이 항상 일치하는 것으로 처리됩니다. 즉, 변경된 파일이 50,000개를 초과하거나, 변경된 파일이 50,000개 미만이더라도 changes 규칙이 50,000회를 초과해 검사되는 경우 changes 규칙은 항상 일치하는 것으로 간주합니다.
• rules:changes 섹션당 최대 50개의 패턴 또는 파일 경로를 정의할 수 있습니다.
• changes는 일치하는 파일 중 하나라도 변경되면 true로 평가됩니다(OR 연산).
• 추가 예시는 rules로 job 실행 시점 지정하기를 참고합니다.
• $ 문자는 변수와 경로 모두에 사용할 수 있습니다. 예를 들어 $VAR 변수가 존재하면 그 값이 사용됩니다. 존재하지 않으면 $는 경로의 일부로 해석됩니다.
• ./, 이중 슬래시(//), 그 밖의 상대 경로는 사용하지 않습니다. 경로는 정확한 문자열 비교로 일치시키며, 셸에서처럼 평가되지 않습니다.

관련 항목:

• rules: changes 사용 시 job 또는 파이프라인이 예기치 않게 실행되는 문제입니다.

---

rules:changes:paths#

rules:changes를 사용하면 특정 파일이 변경된 경우에만 잡을 파이프라인에 추가하도록 지정할 수 있고, 파일 지정에는 rules:changes:paths를 사용합니다.

rules:changes:paths는 하위 키 없이 rules:changes를 사용하는 것과 동일합니다. 추가 세부 사항과 관련 주제도 동일합니다.

키워드 유형: 잡 키워드입니다. 잡의 일부로만 사용할 수 있습니다.

지원되는 값:

• rules:changes와 동일합니다.

rules:changes:paths 예시:

docker-build-1:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - Dockerfile

docker-build-2:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        paths:
          - Dockerfile

이 예시에서 두 잡은 동일하게 동작합니다.

---

rules:changes:compare_to#

히스토리

• CI/CD 변수 지원이 GitLab 17.2에서 도입됐습니다.

rules:changes:compare_to를 사용해 rules:changes:paths 아래에 나열된 파일의 변경 사항을 비교할 기준 ref를 지정합니다.

키워드 유형: 잡 키워드입니다. 잡의 일부로만 사용할 수 있으며, rules:changes:paths와 함께 사용해야 합니다.

지원되는 값:

• main, branch1, refs/heads/branch1 같은 브랜치 이름입니다.
• tag1, refs/tags/tag1 같은 태그 이름입니다.
• 2fg31ga14b 같은 커밋 SHA 입니다.

CI/CD 변수가 지원됩니다.

rules:changes:compare_to 예시:

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        paths:
          - Dockerfile
        compare_to: 'refs/heads/branch1'

이 예시에서 docker build 잡은 Dockerfile 이 refs/heads/branch1을 기준으로 변경되고 파이프라인 소스가 머지 리퀘스트 이벤트인 경우에만 포함됩니다.

추가 세부 사항:

• 일부 상황에서 compare_to를 사용하면 예상치 못한 결과가 발생할 수 있습니다.
  • 병합 결과 파이프라인을 사용하는 경우, 비교 기준이 GitLab 이 생성하는 내부 커밋이기 때문입니다.
  • 포크된 프로젝트에서는 이슈 424584를 참고합니다.

관련 주제:

• rules:changes:compare_to를 사용해 브랜치가 비어 있는 경우 잡을 건너뛸 수 있습니다.

---

rules:changes:regexp#

히스토리

• GitLab 19.2에서 도입됐습니다.

rules:changes:regexp를 사용하면 glob 패턴 대신 Ruby 정규식으로 변경된 파일 경로를 매칭할 수 있습니다.

regexp:와 paths:는 상호 배타적입니다. rules:changes 블록당 하나만 사용합니다.

키워드 유형: 잡 키워드입니다. 잡의 일부로만 사용할 수 있습니다.

지원되는 값:

• Ruby 정규식 문자열입니다. 최대 길이는 255자입니다. 패턴은 변경된 각 파일 경로에 대해 매칭됩니다. 경로 하나라도 매칭되면 규칙이 충족됩니다.

CI/CD 변수가 지원됩니다. 패턴 안의 변수는 매칭 전에 확장되며, 255자 제한은 확장된 패턴에도 적용됩니다.

rules:changes:regexp 예시:

backend-tests:
  script: rspec
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        regexp: '\A(?!docs/).*'

이 예시에서 backend-tests는 변경된 파일 중 하나라도 docs/ 디렉터리 밖에 있으면 실행됩니다.

추가 세부 사항:

• 앵커를 지정하지 않으면 패턴은 경로의 어느 부분과도 매칭됩니다. 전체 경로를 매칭하려면 \A와 \z로 패턴을 앵커합니다.
• ^와 $ 대신 \A와 \z로 패턴을 앵커합니다. Git은 파일 경로에 줄바꿈을 허용하며, ^와 $는 줄바꿈 경계에서 매칭됩니다. ^(?!docs/) 같은 패턴은 docs/ 아래 파일 뒤에 줄바꿈과 다른 경로가 이어지는 등 줄바꿈을 포함하도록 조작된 경로와 매칭될 수 있습니다.
• RE2를 사용하는 rules:if와 달리, rules:changes:regexp는 Ruby 고유의 정규식 엔진을 사용합니다.
• 룩어헤드와 룩비하인드를 지원합니다.
• ReDoS 공격을 방지하기 위해 패턴에는 두 가지 타임아웃이 적용됩니다. 경로 하나당 매칭에는 50ms의 타임아웃이 적용되고, 전체 경로에 대한 평가에는 총 2초의 예산이 적용됩니다. 둘 중 하나라도 초과하면 파이프라인은 구성 오류로 실패합니다.
• 확장된 패턴이 255자를 초과하면 파이프라인은 구성 오류로 실패합니다.
• 성능상의 이유로 변경된 파일이 50,000개를 초과하면 규칙은 패턴을 실행하지 않고 true로 평가됩니다.
• regexp:와 compare_to:를 결합해 비교 기준 ref를 제어할 수 있습니다.

---

rules:exists#

히스토리

• exists 패턴 또는 파일 경로에 대한 최대 검사 횟수가 GitLab 17.7에서 10,000에서 50,000으로 증가했습니다.
• 디렉터리 경로 지원이 GitLab 18.2에서 도입됐습니다.

exists를 사용하면 리포지터리에 특정 파일이나 디렉터리가 있을 때 잡을 실행할 수 있습니다.

키워드 유형: 잡 키워드입니다. 잡의 일부로 사용하거나 include의 일부로 사용할 수 있습니다.

지원되는 값:

• 파일 또는 디렉터리 경로의 배열입니다. 경로는 프로젝트 디렉터리($CI_PROJECT_DIR)를 기준으로 하며 그 바깥을 직접 가리킬 수 없습니다. 파일 경로에는 glob 패턴과 CI/CD 변수를 사용할 수 있습니다.

rules:exists 예시:

job1:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - exists:
        - Dockerfile

job2:
  variables:
    DOCKERPATH: "**/Dockerfile"
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - exists:
        - $DOCKERPATH

이 예시에서:

• job1은 리포지터리 루트 디렉터리에 Dockerfile 이 있으면 실행됩니다.
• job2는 리포지터리 어디에든 Dockerfile 이 있으면 실행됩니다.

추가 세부 사항:

• glob 패턴은 Ruby의 File.fnmatch로 플래그 File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB와 함께 해석됩니다.
• 성능상의 이유로 GitLab은 exists 패턴이나 파일 경로에 대해 최대 50,000회까지만 검사합니다. 50,000번째 검사 이후에는 패턴화된 glob을 사용하는 규칙이 항상 매칭됩니다. 즉 exists 규칙은 파일이 50,000개를 초과하는 프로젝트에서, 또는 파일이 50,000개 미만이더라도 exists 규칙이 50,000회를 초과해 검사되는 경우 항상 매칭된다고 가정합니다.
  • 패턴화된 glob 이 여러 개면 한도는 50,000을 glob 개수로 나눈 값입니다. 예를 들어 패턴화된 glob 5개가 있는 규칙의 파일 한도는 10,000입니다.
• rules:exists 섹션당 최대 50개의 패턴 또는 파일 경로를 정의할 수 있습니다.
• exists는 나열된 파일 중 하나라도 발견되면 true로 해석됩니다(OR 연산).
• 잡 수준의 rules:exists에서 GitLab은 파이프라인을 실행하는 프로젝트와 ref에서 파일을 검색합니다. include와 rules:exists를 함께 사용하면 GitLab은 include 섹션을 포함하는 파일의 프로젝트와 ref에서 파일이나 디렉터리를 검색합니다. include 섹션을 포함하는 프로젝트는 다음을 사용할 때 파이프라인을 실행하는 프로젝트와 다를 수 있습니다.
  • 중첩된 include.
  • 컴플라이언스 파이프라인.
• rules:exists는 아티팩트의 존재 여부를 검색할 수 없습니다. rules 평가는 잡이 실행되고 아티팩트를 가져오기 전에 이뤄지기 때문입니다.
• 디렉터리의 존재 여부를 확인하려면 경로가 슬래시(/)로 끝나야 합니다.

---

rules:exists:paths#

히스토리

• GitLab 16.11에서 ci_support_rules_exists_paths_and_project라는 기능 플래그와 함께 도입됐습니다. 기본적으로 비활성화돼 있습니다.
• GitLab 17.0에서 일반 제공됐습니다. 기능 플래그 ci_support_rules_exists_paths_and_project가 제거됐습니다.

rules:exists:paths는 하위 키 없이 rules:exists를 사용하는 것과 동일합니다. 추가 세부 사항도 동일합니다.

키워드 유형: 잡 키워드입니다. 잡의 일부로 사용하거나 include의 일부로 사용할 수 있습니다.

지원되는 값:

• 파일 경로의 배열입니다.

rules:exists:paths 예시:

docker-build-1:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      exists:
        - Dockerfile

docker-build-2:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      exists:
        paths:
          - Dockerfile

이 예시에서 두 잡은 동일하게 동작합니다.

---

rules:exists:project#

히스토리

• GitLab 16.11에서 ci_support_rules_exists_paths_and_project라는 기능 플래그와 함께 도입됐습니다. 기본적으로 비활성화돼 있습니다.
• GitLab 17.0에서 일반 제공됐습니다. 기능 플래그 ci_support_rules_exists_paths_and_project가 제거됐습니다.

rules:exists:project를 사용해 rules:exists:paths 아래에 나열된 파일을 검색할 위치를 지정합니다. rules:exists:paths와 함께 사용해야 합니다.

키워드 유형: 잡 키워드입니다. 잡의 일부로 사용하거나 include의 일부로 사용할 수 있으며, rules:exists:paths와 함께 사용해야 합니다.

지원되는 값:

• exists:project: 네임스페이스와 그룹을 포함한 전체 프로젝트 경로입니다.
• exists:ref: 선택 사항입니다. 파일을 검색할 때 사용할 커밋 ref 입니다. ref는 태그, 브랜치 이름, SHA가 될 수 있습니다. 지정하지 않으면 프로젝트의 HEAD가 기본값입니다.

rules:exists:project 예시:

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - exists:
        paths:
          - Dockerfile
        project: my-group/my-project
        ref: v1.0.0

이 예시에서 docker build 잡은 Dockerfile 이 v1.0.0 태그가 지정된 커밋의 my-group/my-project 프로젝트에 있을 때만 포함됩니다.

---

rules:exists:regexp#

히스토리

• GitLab 19.2에서 도입됐습니다.

rules:exists:regexp를 사용하면 glob 패턴 대신 Ruby 정규식으로 리포지터리의 파일 경로를 매칭할 수 있습니다.

regexp:와 paths:는 상호 배타적입니다. rules:exists 블록당 하나만 사용합니다.

키워드 유형: 잡 키워드입니다. 잡의 일부로 사용하거나 include의 일부로 사용할 수 있습니다.

지원되는 값:

• Ruby 정규식 문자열입니다. 최대 길이는 255자입니다. 패턴은 리포지터리의 모든 파일 경로에 대해 매칭됩니다. 경로 하나라도 매칭되면 규칙이 충족됩니다.

CI/CD 변수가 지원됩니다. 패턴 안의 변수는 매칭 전에 확장되며, 255자 제한은 확장된 패턴에도 적용됩니다.

rules:exists:regexp 예시:

run-if-go-files-exist:
  script: go test ./...
  rules:
    - exists:
        regexp: '\.go$'

이 예시에서 잡은 리포지터리 어디에든 .go 파일이 있으면 실행됩니다.

추가 세부 사항:

• 앵커를 지정하지 않으면 패턴은 경로의 어느 부분과도 매칭됩니다. 전체 경로를 매칭하려면 \A와 \z로 패턴을 앵커합니다.
• ^와 $ 대신 \A와 \z로 패턴을 앵커합니다. Git은 파일 경로에 줄바꿈을 허용하며, ^와 $는 줄바꿈 경계에서 매칭됩니다. ^(?!docs/) 같은 패턴은 docs/ 아래 파일 뒤에 줄바꿈과 다른 경로가 이어지는 등 줄바꿈을 포함하도록 조작된 경로와 매칭될 수 있습니다.
• RE2를 사용하는 rules:if와 달리, rules:exists:regexp는 Ruby 고유의 정규식 엔진을 사용합니다.
• 룩어헤드와 룩비하인드를 지원합니다.
• ReDoS 공격을 방지하기 위해 패턴에는 두 가지 타임아웃이 적용됩니다. 경로 하나당 매칭에는 50ms의 타임아웃이 적용되고, 전체 경로에 대한 평가에는 총 2초의 예산이 적용됩니다. 둘 중 하나라도 초과하면 파이프라인은 구성 오류로 실패합니다.
• 확장된 패턴이 255자를 초과하면 파이프라인은 구성 오류로 실패합니다.
• 성능상의 이유로 리포지터리에 파일이 50,000개를 초과하면 규칙은 패턴을 실행하지 않고 true로 평가됩니다.
• regexp:를 project: 및 ref:와 결합해 다른 프로젝트에서 검색할 수 있습니다.

---

rules:when#

rules:when을 단독으로 사용하거나 다른 규칙의 일부로 사용해 잡을 파이프라인에 추가하는 조건을 제어합니다. rules:when은 when과 비슷하지만 입력 옵션이 약간 다릅니다.

rules:when 규칙이 if, changes, exists와 결합되지 않으면, 잡의 규칙을 평가할 때 도달하는 경우 항상 매칭됩니다.

키워드 유형: 잡 전용입니다. 잡의 일부로만 사용할 수 있습니다.

지원되는 값:

• on_success(기본값): 이전 스테이지의 잡이 하나도 실패하지 않은 경우에만 잡을 실행합니다.
• on_failure: 이전 스테이지의 잡이 하나라도 실패한 경우에만 잡을 실행합니다.
• never: 이전 스테이지의 잡 상태와 무관하게 잡을 실행하지 않습니다.
• always: 이전 스테이지의 잡 상태와 무관하게 잡을 실행합니다.
• manual: 잡을 수동 잡으로 파이프라인에 추가합니다. allow_failure의 기본값이 false로 바뀝니다.
• delayed: 잡을 지연된 잡으로 파이프라인에 추가합니다.

rules:when 예시:

job1:
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
    - if: $CI_COMMIT_REF_NAME =~ /feature/
      when: delayed
    - when: manual
  script:
    - echo

이 예시에서 job1은 다음과 같이 파이프라인에 추가됩니다.

• 기본 브랜치에는 when을 정의하지 않았을 때의 기본 동작인 when: on_success로 추가됩니다.
• 기능 브랜치에는 지연된 잡으로 추가됩니다.
• 그 외의 모든 경우에는 수동 잡으로 추가됩니다.

추가 세부 사항:

• on_success와 on_failure에 대한 잡 상태를 평가할 때:
  • 이전 스테이지에서 allow_failure: true 인 잡은 실패하더라도 성공한 것으로 간주됩니다.
  • 이전 스테이지에서 건너뛴 잡, 예를 들어 시작되지 않은 수동 잡은 성공한 것으로 간주됩니다.
• rules:when: manual로 수동 잡을 추가할 때:
  • allow_failure는 기본적으로 false가 됩니다. 이 기본값은 when: manual로 수동 잡을 추가할 때와 반대입니다.
  • rules 밖에서 정의한 when: manual과 동일하게 동작하게 하려면 rules: allow_failure를 true로 설정합니다.

---

rules:allow_failure#

rules에서 allow_failure: true를 사용하면 잡이 실패해도 파이프라인을 중단하지 않을 수 있습니다.

수동 잡에도 allow_failure: true를 사용할 수 있습니다. 이 경우 파이프라인은 수동 잡의 결과를 기다리지 않고 계속 실행됩니다. rules에서 when: manual과 allow_failure: false를 함께 사용하면 파이프라인은 수동 잡이 실행될 때까지 기다린 뒤 계속 진행합니다.

키워드 유형: 잡 키워드입니다. 잡의 일부로만 사용할 수 있습니다.

지원되는 값:

• true 또는 false 입니다. 정의하지 않으면 기본값은 false 입니다.

rules:allow_failure 예시:

job:
  script: echo "Hello, Rules!"
  rules:
    - if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
      when: manual
      allow_failure: true

규칙이 매칭되면 잡은 allow_failure: true 인 수동 잡이 됩니다.

추가 세부 사항:

• 규칙 수준의 rules:allow_failure는 잡 수준의 allow_failure를 재정의하며, 해당 특정 규칙이 잡을 트리거할 때만 적용됩니다.

---

rules:needs#

규칙에서 needs를 사용해 특정 조건에 대한 잡의 needs를 갱신합니다. 조건이 규칙과 매칭되면 잡의 needs 구성은 해당 규칙의 needs로 완전히 대체됩니다.

키워드 유형: 잡 전용입니다. 잡의 일부로만 사용할 수 있습니다.

지원되는 값:

• 문자열로 된 잡 이름의 배열입니다.
• 잡 이름을 포함하는 해시이며, 선택적으로 추가 속성을 포함할 수 있습니다.
• 빈 배열([])로, 특정 조건이 충족될 때 잡의 needs를 없음으로 설정합니다.

rules:needs 예시:

build-dev:
  stage: build
  rules:
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
  script: echo "Feature branch, so building dev version..."

build-prod:
  stage: build
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  script: echo "Default branch, so building prod version..."

tests:
  stage: test
  rules:
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
      needs: ['build-dev']
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      needs: ['build-prod']
  script: echo "Running dev specs by default, or prod specs when default branch..."

이 예시에서:

• 파이프라인이 기본 브랜치가 아닌 브랜치에서 실행돼 규칙이 첫 번째 조건과 매칭되면, specs 잡은 build-dev 잡을 필요로 합니다.
• 파이프라인이 기본 브랜치에서 실행돼 규칙이 두 번째 조건과 매칭되면, specs 잡은 build-prod 잡을 필요로 합니다.

추가 세부 사항:

• 규칙에서의 needs는 잡 수준에서 정의된 모든 needs를 재정의합니다. 재정의되면 동작은 잡 수준 needs와 동일합니다.
• 규칙에서의 needs는 artifacts와 optional을 받을 수 있습니다.

---

rules:variables#

특정 조건에 대한 변수를 정의하려면 rules에서 variables를 사용합니다.

키워드 유형: job 전용입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• VARIABLE-NAME: value 형식의 변수 해시.

rules:variables 예시:

job:
  variables:
    DEPLOY_VARIABLE: "default-deploy"
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      variables:                              # Override DEPLOY_VARIABLE defined
        DEPLOY_VARIABLE: "deploy-production"  # at the job level.
    - if: $CI_COMMIT_REF_NAME =~ /feature/
      variables:
        IS_A_FEATURE: "true"                  # Define a new variable.
  script:
    - echo "Run script with $DEPLOY_VARIABLE as an argument"
    - echo "Run another script if $IS_A_FEATURE exists"

---

rules:interruptible#

특정 조건에 대한 job의 interruptible 값을 갱신하려면 rules에서 interruptible을 사용합니다.

키워드 유형: job 전용입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• true 또는 false.

rules:interruptible 예시:

job:
  script: echo "Hello, Rules!"
  interruptible: true
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      interruptible: false  # Override interruptible defined at the job level.
    - when: on_success

추가 세부 정보:

• 규칙 수준의 rules:interruptible은 job 수준의 interruptible을 재정의하며, 해당 규칙이 job을 트리거할 때만 적용됩니다.

---

run#

히스토리

• GitLab 17.3에서 pipeline_run_keyword라는 이름의 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다. GitLab Runner 17.1 이상이 필요합니다.
• 기능 플래그 pipeline_run_keyword가 GitLab 17.5에서 제거되었습니다.

job에서 실행할 일련의 단계(steps)를 정의하려면 run을 사용합니다. 각 단계는 스크립트이거나 사전 정의된 단계일 수 있습니다.

환경 변수와 입력값을 선택적으로 제공할 수도 있습니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• 해시의 배열이며, 각 해시는 다음 키를 가질 수 있는 하나의 단계를 나타냅니다:
  • name: 단계의 이름을 나타내는 문자열입니다.
  • script: 실행할 셸 명령을 포함하는 문자열입니다.
  • step: 실행할 사전 정의된 단계를 식별하는 문자열입니다.
  • env: 선택 사항입니다. 이 단계에 특정한 환경 변수의 해시입니다.
  • inputs: 선택 사항입니다. 사전 정의된 단계에 대한 입력 매개변수의 해시입니다.

각 배열 항목에는 name 이 있어야 하며, script 또는 step 중 하나만 있어야 합니다(둘 다는 안 됨).

run 예시:

job:
  run:
    - name: 'hello_steps'
      script: 'echo "hello from step1"'
    - name: 'bye_steps'
      step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@main
      inputs:
        echo: 'bye steps!'
      env:
        var1: 'value 1'

이 예시에서 job에는 두 개의 단계가 있습니다:

• hello_steps는 echo 셸 명령을 실행합니다.
• bye_steps는 환경 변수와 입력 매개변수가 있는 사전 정의된 단계를 사용합니다.

추가 세부 정보:

• 단계에는 script 키 또는 step 키 중 하나만 있을 수 있으며, 둘 다 있을 수는 없습니다.
• run 설정은 기존 script, after_script, before_script 키워드와 함께 사용할 수 없습니다.
• YAML 블록 스칼라 구문을 사용하여 여러 줄로 된 스크립트를 정의할 수 있습니다.

---

script#

러너가 실행할 명령을 지정하려면 script를 사용합니다.

트리거 job을 제외한 모든 job에는 script 키워드가 필요합니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값: 다음을 포함하는 배열입니다:

• 한 줄짜리 명령.
• 여러 줄로 나눈 긴 명령.
• YAML 앵커.

CI/CD 변수를 지원합니다.

script 예시:

job1:
  script: "bundle exec rspec"

job2:
  script:
    - uname -a
    - bundle exec rspec

추가 세부 정보:

• script에서 이러한 특수 문자를 사용하는 경우 작은따옴표(') 또는 큰따옴표(")를 사용해야 합니다.

관련 주제:

• 0이 아닌 종료 코드를 무시할 수 있습니다.
• job 로그를 더 쉽게 검토할 수 있도록 script에서 색상 코드를 사용합니다.
• job 로그 출력을 단순화하려면 사용자 지정 접기 섹션을 생성합니다.

---

secrets#

다음을 위해 CI/CD 시크릿을 지정하려면 secrets를 사용합니다:

• 외부 시크릿 공급자에서 가져옵니다.
• job에서 CI/CD 변수로 사용할 수 있게 합니다 (기본적으로 file 유형).

---

secrets:vault#

HashiCorp Vault에서 제공하는 시크릿을 지정하려면 secrets:vault를 사용합니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• engine:name: 시크릿 엔진의 이름입니다. kv-v2(기본값), kv-v1, generic 중 하나일 수 있습니다.
• engine:path: 시크릿 엔진의 경로입니다.
• path: 시크릿의 경로입니다.
• field: 비밀번호가 저장된 필드의 이름입니다.

secrets:vault 예시:

모든 세부 정보를 명시적으로 지정하고 KV-V2 시크릿 엔진을 사용하려면 다음과 같이 합니다:

job:
  secrets:
    DATABASE_PASSWORD:  # Store the path to the secret in this CI/CD variable
      vault:  # Translates to secret: `ops/data/production/db`, field: `password`
        engine:
          name: kv-v2
          path: ops
        path: production/db
        field: password

이 구문을 축약할 수 있습니다. 짧은 구문에서는 engine:name과 engine:path 가 모두 기본적으로 kv-v2가 됩니다:

job:
  secrets:
    DATABASE_PASSWORD:  # Store the path to the secret in this CI/CD variable
      vault: production/db/password  # Translates to secret: `kv-v2/data/production/db`, field: `password`

짧은 구문에서 사용자 지정 시크릿 엔진 경로를 지정하려면 @로 시작하는 접미사를 추가합니다:

job:
  secrets:
    DATABASE_PASSWORD:  # Store the path to the secret in this CI/CD variable
      vault: production/db/password@ops  # Translates to secret: `ops/data/production/db`, field: `password`

---

secrets:gcp_secret_manager#

GCP Secret Manager에서 제공하는 시크릿을 지정하려면 secrets:gcp_secret_manager를 사용합니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• name: 시크릿의 이름입니다.
• version: 시크릿의 버전입니다.

secrets:gcp_secret_manager 예시:

job:
  secrets:
    DATABASE_PASSWORD:
      gcp_secret_manager:
        name: 'test'
        version: 2

관련 주제:

• GitLab CI/CD에서 GCP Secret Manager 시크릿 사용.

---

secrets:gitlab_secrets_manager#

히스토리

• GitLab 19.0에서 도입되었습니다. GitLab Runner 19.0 이상이 필요합니다.

GitLab Secrets Manager의 시크릿을 지정하려면 secrets:gitlab_secrets_manager를 사용합니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• name: 시크릿의 이름입니다.
• source: 선택 사항입니다. 시크릿의 소스입니다. 지정하지 않으면 현재 프로젝트가 기본값입니다. 그룹 시크릿의 경우 group/<full-path-to-group>을 사용합니다.

secrets:gitlab_secrets_manager 예시:

job:
  secrets:
    MY_DEPLOY_SECRET:
      gitlab_secrets_manager:
        name: deployment_token

---

secrets:azure_key_vault#

Azure Key Vault에서 제공하는 시크릿을 지정하려면 secrets:azure_key_vault를 사용합니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• name: 시크릿의 이름입니다.
• version: 시크릿의 버전입니다.

secrets:azure_key_vault 예시:

job:
  secrets:
    DATABASE_PASSWORD:
      azure_key_vault:
        name: 'test'
        version: 'test'

관련 주제:

• GitLab CI/CD에서 Azure Key Vault 시크릿 사용.

---

secrets:file#

시크릿을 file 또는 variable 유형 CI/CD 변수 로 저장하도록 설정하려면 secrets:file을 사용합니다.

기본적으로 시크릿은 file 유형 CI/CD 변수로 job에 전달됩니다. 값은 파일에 저장되며 변수에는 해당 파일의 경로가 포함됩니다.

소프트웨어가 file 유형 CI/CD 변수를 사용할 수 없는 경우, file: false를 설정하여 시크릿 값을 변수에 직접 저장합니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• true(기본값) 또는 false.

secrets:file 예시:

job:
  secrets:
    DATABASE_PASSWORD:
      vault: production/db/password@ops
      file: false

추가 세부 정보:

• file 키워드는 CI/CD 변수에 대한 설정이며, vault 섹션이 아니라 CI/CD 변수 이름 아래에 중첩되어야 합니다.

---

secrets:token#

토큰의 CI/CD 변수를 참조하여 외부 시크릿 공급자로 인증할 때 사용할 토큰을 명시적으로 선택하려면 secrets:token을 사용합니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• ID 토큰의 이름

secrets:token 예시:

job:
  id_tokens:
    AWS_TOKEN:
      aud: https://aws.example.com
    VAULT_TOKEN:
      aud: https://vault.example.com
  secrets:
    DB_PASSWORD:
      vault: gitlab/production/db
      token: $VAULT_TOKEN

추가 세부 정보:

• token 키워드가 설정되지 않고 정의된 토큰이 하나뿐인 경우, 정의된 토큰이 자동으로 사용됩니다.
• 정의된 토큰이 두 개 이상인 경우, token 키워드를 설정하여 사용할 토큰을 지정해야 합니다. 사용할 토큰을 지정하지 않으면, job 이 실행될 때마다 어떤 토큰이 사용되는지 예측할 수 없습니다.

---

services#

스크립트가 성공적으로 실행되는 데 필요한 추가 Docker 이미지를 지정하려면 services를 사용합니다. services 이미지는 image 키워드에 지정된 이미지에 연결됩니다.

job 설정과 기본(default) 설정은 함께 병합되지 않습니다. 파이프라인에 default:services가 정의되어 있고 job에도 services가 있는 경우, job 설정이 우선하며 기본 설정은 사용되지 않습니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값: 필요한 경우 레지스트리 경로를 포함한 서비스 이미지의 이름이며, 다음 형식 중 하나입니다:

• <image-name> (<image-name>에 latest 태그를 사용하는 것과 동일)
• <image-name>:<tag>
• <image-name>@<digest>

CI/CD 변수를 지원하지만, alias에는 사용할 수 없습니다. alias를 동적으로 사용자 지정하려면 대신 CI/CD 입력값을 사용합니다.

services 예시:

default:
  image:
    name: ruby:2.6
    entrypoint: ["/bin/bash"]

  services:
    - name: my-postgres:11.7
      alias: db-postgres
      entrypoint: ["/usr/local/bin/db-postgres"]
      command: ["start"]

  before_script:
    - bundle install

test:
  script:
    - bundle exec rake spec

이 예시에서 GitLab은 job에 대해 두 개의 컨테이너를 실행합니다:

• script 명령을 실행하는 Ruby 컨테이너.
• PostgreSQL 컨테이너. Ruby 컨테이너의 script 명령은 db-postgres 호스트 이름으로 PostgreSQL 데이터베이스에 연결할 수 있습니다.

추가 세부 정보:

• default 섹션이 아니라 최상위 수준에서 services를 사용하는 것은 지원 중단되었습니다.

관련 주제:

• services에 사용할 수 있는 설정.
• .gitlab-ci.yml 파일에서 services 정의.
• Docker 컨테이너에서 CI/CD job 실행.
• Docker를 사용하여 Docker 이미지 빌드.

---

services:name#

서비스에 사용할 이미지의 전체 이름입니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용하거나 default 섹션에서 사용할 수 있습니다.

지원되는 값: 필요한 경우 레지스트리 경로를 포함한 서비스 이미지의 이름이며, 다음 형식 중 하나입니다:

• <image-name> (<image-name>에 latest 태그를 사용하는 것과 동일)
• <image-name>:<tag>
• <image-name>@<digest>

CI/CD 변수를 지원합니다.

services:name 예시:

services:
  - name: postgres:11.7
  - name: registry.example.com/my-org/custom-service:latest

추가 세부 정보:

• 동일한 서비스 이미지를 여러 개 사용하거나 서비스 이미지 이름이 긴 경우, 고유한 이름 별칭(alias)을 정의하려면 alias를 사용합니다.
• entrypoint, command, variables 등 다른 서비스 옵션과 함께 사용하는 경우 name 키워드가 필요합니다.
• 자세한 내용은 서비스 액세스를 참고합니다.

---

services:alias#

히스토리

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

job의 컨테이너에서 서비스에 접근하기 위한 추가 별칭입니다.

키워드 유형: job 키워드입니다. job의 일부로 사용하거나 default 섹션에서만 사용할 수 있습니다.

지원되는 값: 공백이나 쉼표로 구분된 하나 이상의 별칭을 포함하는 문자열입니다.

services:alias의 예:

services:
  - name: postgres:11.7
    alias: db,postgres,pg
  - name: mysql:latest
    alias: mysql-1

추가 세부 정보:

• 여러 별칭은 공백이나 쉼표로 구분할 수 있습니다.
• 자세한 내용은 서비스에 접근하기와 Kubernetes executor에서 서비스 컨테이너 이름으로 별칭 사용하기를 참고합니다.

---

services:docker#

services:docker를 사용하면 GitLab Runner의 Docker executor에 옵션을 전달할 수 있습니다.

키워드 유형: job 키워드입니다. job의 일부로 사용하거나 default 섹션에서만 사용할 수 있습니다.

지원되는 값:

Docker executor에 대한 옵션의 해시이며, 다음을 포함할 수 있습니다.

• platform: 풀(pull)할 이미지의 아키텍처를 선택합니다. 지정하지 않으면 기본값은 호스트 러너와 동일한 플랫폼입니다.
• user: 컨테이너를 실행할 때 사용할 사용자 이름 또는 UID를 지정합니다.

services:docker의 예:

arm-sql-job:
  script: echo "Run sql tests in service container"
  image: ruby:2.6
  services:
    - name: super/sql:experimental
      docker:
        platform: arm64/v8
        user: dave

추가 세부 정보:

• services:docker:platform은 docker pull --platform 옵션에 매핑됩니다.
• services:docker:user는 docker run --user 옵션에 매핑됩니다.
• Docker executor에서 러너 호스트와 다른 아키텍처로 빌드된 서비스 이미지를 실행하려면, 호스트에 binfmt_misc로 등록된 에뮬레이션 지원이 있어야 합니다. 자세한 내용은 image:docker를 참고합니다.

---

services:kubernetes#

히스토리

• GitLab 18.0에서 도입되었습니다. GitLab Runner 17.11 이상이 필요합니다.
• user 입력 옵션이 GitLab Runner 17.11에서 도입되었습니다.
• user 입력 옵션이 GitLab 18.0에서 uid:gid 형식을 지원하도록 확장되었습니다.

services:kubernetes를 사용하면 GitLab Runner Kubernetes executor에 옵션을 전달할 수 있습니다.

키워드 유형: job 키워드입니다. job의 일부로 사용하거나 default 섹션에서만 사용할 수 있습니다.

지원되는 값:

Kubernetes executor에 대한 옵션의 해시이며, 다음을 포함할 수 있습니다.

• user: 컨테이너가 실행될 때 사용할 사용자 이름 또는 UID를 지정합니다. UID:GID 형식을 사용해 GID도 설정할 수 있습니다.

UID만 사용하는 services:kubernetes의 예:

arm-sql-job:
  script: echo "Run sql tests"
  image: ruby:2.6
  services:
    - name: super/sql:experimental
      kubernetes:
        user: "1001"

UID와 GID를 모두 사용하는 services:kubernetes의 예:

arm-sql-job:
  script: echo "Run sql tests"
  image: ruby:2.6
  services:
    - name: super/sql:experimental
      kubernetes:
        user: "1001:1001"

---

services:entrypoint#

컨테이너의 진입점(entrypoint)으로 실행할 명령 또는 스크립트입니다.

Docker 컨테이너가 생성될 때 entrypoint는 Docker의 --entrypoint 옵션으로 변환됩니다. 구문은 Dockerfile의 ENTRYPOINT 지시어와 유사하며, 각 셸 토큰은 배열 내 별도의 문자열로 지정됩니다.

키워드 유형: job 키워드입니다. job의 일부로 사용하거나 default 섹션에서만 사용할 수 있습니다.

지원되는 값: 진입점 명령을 나타내는 문자열 배열입니다.

services:entrypoint의 예:

services:
  - name: my-postgres:11.7
    entrypoint: ["/usr/local/bin/db-postgres"]

---

services:command#

컨테이너의 명령으로 사용할 명령 또는 스크립트입니다.

이는 이미지 이름 뒤에 Docker로 전달되는 인수로 변환됩니다. 구문은 Dockerfile의 CMD 지시어와 유사하며, 각 셸 토큰은 배열 내 별도의 문자열로 지정됩니다.

키워드 유형: job 키워드입니다. job의 일부로 사용하거나 default 섹션에서만 사용할 수 있습니다.

지원되는 값: 명령을 나타내는 문자열 배열입니다.

services:command의 예:

services:
  - name: super/sql:latest
    command: ["/usr/bin/super-sql", "run"]

---

services:variables#

서비스에만 전달되는 추가 환경 변수입니다. 서비스 변수는 서비스 컨테이너에만 전달되며 job 컨테이너에서는 사용할 수 없습니다.

구문은 job 변수와 동일합니다.

키워드 유형: job 키워드입니다. job의 일부로 사용하거나 default 섹션에서만 사용할 수 있습니다.

지원되는 값: 환경 변수 이름과 값의 해시입니다.

services:variables의 예:

services:
  - name: postgres:11.7
    alias: db
    variables:
      POSTGRES_DB: "my_custom_db"
      POSTGRES_USER: "postgres"
      POSTGRES_PASSWORD: "example"
      PGDATA: "/var/lib/postgresql/data"

추가 세부 정보:

• 서비스 변수는 자기 자신을 참조할 수 없으며, 변수 확장이나 보간을 지원하지 않습니다.
• job 또는 파이프라인 수준에서 정의된 변수는 서비스에 자동으로 전달됩니다. 자세한 내용은 서비스에 CI/CD 변수 전달하기를 참고합니다.
• 서비스 변수는 해당 변수가 정의된 특정 서비스에만 사용할 수 있습니다.

---

services:pull_policy#

러너가 Docker 이미지를 가져올 때 사용하는 풀 정책(pull policy)입니다.

키워드 유형: job 키워드입니다. job의 일부로 사용하거나 default 섹션에서만 사용할 수 있습니다.

지원되는 값:

• 단일 풀 정책 또는 배열로 지정한 여러 풀 정책입니다. always, if-not-present, never 중 하나일 수 있습니다.

services:pull_policy의 예:

job1:
  script: echo "A single pull policy."
  services:
    - name: postgres:11.6
      pull_policy: if-not-present

job2:
  script: echo "Multiple pull policies."
  services:
    - name: postgres:11.6
      pull_policy: [always, if-not-present]

추가 세부 정보:

• 러너가 정의된 풀 정책을 지원하지 않으면, job은 다음과 유사한 오류와 함께 실패합니다. ERROR: Job failed (system failure): the configured PullPolicies ([always]) are not allowed by AllowedPullPolicies ([never]).

관련 항목:

• Docker 컨테이너에서 CI/CD job 실행하기.
• 러너가 이미지를 가져오는 방식 설정하기.
• 여러 풀 정책 설정하기.

---

stage#

stage를 사용하면 job이 실행될 스테이지(stage)를 정의할 수 있습니다. 동일한 stage에 속한 job은 병렬로 실행될 수 있습니다(추가 세부 정보 참고).

stage가 정의되지 않으면, job은 기본적으로 test 스테이지를 사용합니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값: 문자열이며, 다음 중 하나일 수 있습니다.

• 기본 스테이지.
• 사용자 정의 스테이지.

stage의 예:

stages:
  - build
  - test
  - deploy

job1:
  stage: build
  script:
    - echo "This job compiles code."

job2:
  stage: test
  script:
    - echo "This job tests the compiled code. It runs when the build stage completes."

job3:
  script:
    - echo "This job also runs in the test stage."

job4:
  stage: deploy
  script:
    - echo "This job deploys the code. It runs when the test stage completes."
  environment: production

추가 세부 정보:

• 스테이지 이름은 255자 이하여야 합니다.
• job이 서로 다른 러너에서 실행되면 병렬로 실행될 수 있습니다.
• 러너가 하나뿐인 경우, 해당 러너의 concurrent 설정이 1보다 크면 job이 병렬로 실행될 수 있습니다.

---

stage: .pre#

.pre 스테이지를 사용하면 job을 파이프라인 시작 시점에 실행할 수 있습니다. 기본적으로 .pre는 파이프라인의 첫 번째 스테이지입니다. 사용자 정의 스테이지는 .pre 이후에 실행됩니다. stages에서 .pre를 정의할 필요는 없습니다.

파이프라인에 .pre 또는 .post 스테이지의 job만 있으면, 파이프라인은 실행되지 않습니다. 다른 스테이지에 최소 하나의 job이 있어야 합니다.

키워드 유형: job의 stage 키워드와 함께만 사용할 수 있습니다.

stage: .pre의 예:

stages:
  - build
  - test

job1:
  stage: build
  script:
    - echo "This job runs in the build stage."

first-job:
  stage: .pre
  script:
    - echo "This job runs in the .pre stage, before all other stages."

job2:
  stage: test
  script:
    - echo "This job runs in the test stage."

추가 세부 정보:

• 파이프라인에 needs: []가 있는 job과 .pre 스테이지의 job이 함께 있으면, 모두 파이프라인이 생성되는 즉시 시작됩니다. needs: []가 있는 job은 스테이지 설정과 무관하게 즉시 시작됩니다.
• 파이프라인 실행 정책은 .pre보다 먼저 실행되는 .pipeline-policy-pre 스테이지를 정의할 수 있습니다.

---

stage: .post#

.post 스테이지를 사용하면 job을 파이프라인 종료 시점에 실행할 수 있습니다. 기본적으로 .post는 파이프라인의 마지막 스테이지입니다. 사용자 정의 스테이지는 .post 이전에 실행됩니다. stages에서 .post를 정의할 필요는 없습니다.

파이프라인에 .pre 또는 .post 스테이지의 job만 있으면, 파이프라인은 실행되지 않습니다. 다른 스테이지에 최소 하나의 job이 있어야 합니다.

키워드 유형: job의 stage 키워드와 함께만 사용할 수 있습니다.

stage: .post의 예:

stages:
  - build
  - test

job1:
  stage: build
  script:
    - echo "This job runs in the build stage."

last-job:
  stage: .post
  script:
    - echo "This job runs in the .post stage, after all other stages."

job2:
  stage: test
  script:
    - echo "This job runs in the test stage."

추가 세부 정보:

• 파이프라인 실행 정책은 .post 이후에 실행되는 .pipeline-policy-post 스테이지를 정의할 수 있습니다.

---

tags#

tags를 사용하면 프로젝트에서 사용 가능한 모든 러너 목록 중에서 특정 러너를 선택할 수 있습니다.

러너를 등록할 때 러너의 태그를 지정할 수 있으며, 예를 들어 ruby, postgres, development 등이 있습니다. 러너가 job을 가져와 실행하려면 job에 나열된 모든 태그를 러너가 가지고 있어야 합니다.

job 설정과 기본 설정은 병합되지 않습니다. 파이프라인에 default:tags가 정의되어 있고 job에도 tags가 있으면, job 설정이 우선 적용되며 기본 설정은 사용되지 않습니다.

키워드 유형: job 키워드입니다. job의 일부로 사용하거나 default 섹션에서만 사용할 수 있습니다.

지원되는 값:

• 대소문자를 구분하는 태그 이름의 배열입니다.
• CI/CD 변수를 지원합니다.

tags의 예:

job:
  tags:
    - ruby
    - postgres

이 예시에서는 ruby와 postgres 태그를 모두 가진 러너만 이 job을 실행할 수 있습니다.

추가 세부 정보:

• 태그 수는 50개 미만이어야 합니다.

관련 항목:

• 태그를 사용해 러너가 실행할 수 있는 job 제어하기
• 병렬 매트릭스 job마다 다른 러너 태그 선택하기
• 호스팅 러너의 러너 태그:
  • Linux 호스팅 러너
  • GPU 지원 호스팅 러너
  • macOS 호스팅 러너
  • Windows 호스팅 러너

---

timeout#

timeout을 사용하면 특정 job에 대한 제한 시간을 설정할 수 있습니다. job이 제한 시간보다 오래 실행되면, 해당 job은 실패합니다.

job 수준의 제한 시간은 프로젝트 제한 시간보다 길 수 있지만, 러너의 제한 시간보다 길 수는 없습니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

지원되는 값: 자연어로 작성된 기간입니다. 예를 들어 다음은 모두 동일합니다.

• 3600 seconds
• 60 minutes
• one hour

timeout의 예:

build:
  script: build.sh
  timeout: 3 hours 30 minutes

test:
  script: rspec
  timeout: 3h 30m

추가 세부 정보:

• timeout 키워드는 default 설정에서는 지원되지 않습니다. 각 job 설정에서 개별적으로 timeout을 정의합니다. 자세한 내용은 이슈 213634를 참고합니다.

---

trigger#

trigger를 사용하면 job을 "트리거 job"으로 선언할 수 있으며, 이 job은 다음 중 하나를

다운스트림 파이프라인을 시작합니다.

• 멀티 프로젝트 파이프라인.
• 차일드 파이프라인.

트리거 job은 제한된 GitLab CI/CD 설정 키워드 집합만 사용할 수 있습니다. 트리거 job에서 사용할 수 있는 키워드는 다음과 같습니다.

• allow_failure.
• extends.
• needs, 단 needs:project는 제외.
• only 및 except.
• parallel.
• rules.
• stage.
• trigger.
• variables.
• when (on_success, on_failure, always, manual 값에서만 사용 가능).
• resource_group.
• environment.

키워드 유형: job 키워드. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• 멀티 프로젝트 파이프라인의 경우, 다운스트림 프로젝트의 경로입니다. CI/CD 변수는 지원되지만 job 전용 변수는 지원되지 않습니다. 대신 trigger:project를 사용할 수도 있습니다.
• 차일드 파이프라인의 경우, trigger:include를 사용합니다.

trigger 예시:

trigger-multi-project-pipeline:
  trigger: my-group/my-project

추가 세부 정보:

• trigger와 같은 job에서 when:manual을 사용할 수 있지만, API로 when:manual 트리거 job을 시작할 수는 없습니다. 자세한 내용은 이슈 284086을 참고합니다.
• 수동 트리거 job을 실행하기 전에는 CI/CD 변수를 수동으로 지정할 수 없습니다.
• 최상위 variables 섹션(전역)이나 트리거 job에 정의된 CI/CD 변수는 트리거 변수로 다운스트림 파이프라인에 전달됩니다.
• 파이프라인 변수는 기본적으로 다운스트림 파이프라인에 전달되지 않습니다. 이 변수를 다운스트림 파이프라인에 전달하려면 trigger:forward를 사용합니다.
• job 전용 변수는 트리거 job에서 사용할 수 없습니다.
• 러너의 config.toml에 정의된 환경 변수는 트리거 job에서 사용할 수 없으며 다운스트림 파이프라인에도 전달되지 않습니다.
• 트리거 job에서는 needs:pipeline:job을 사용할 수 없습니다.

관련 주제:

• 멀티 프로젝트 파이프라인 설정 예시.
• 특정 브랜치·태그·커밋에 대해 파이프라인을 실행하려면 트리거 토큰을 사용해 파이프라인 트리거 API로 인증할 수 있습니다. 트리거 토큰은 trigger 키워드와는 다릅니다.

---

trigger:inputs#

히스토리

• Introduced in GitLab 17.11.

다운스트림 파이프라인 설정에서 spec:inputs를 사용하는 경우, trigger:inputs를 사용해 멀티 프로젝트 파이프라인의 입력을 설정합니다.

trigger:inputs 예시:

trigger:
  - project: 'my-group/my-project'
    inputs:
      website: "My website"

---

trigger:include#

trigger:include를 사용하면 job을 "트리거 job"으로 선언할 수 있으며, 이 job은 차일드 파이프라인을 시작합니다.

키워드 유형: job 키워드. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• 차일드 파이프라인 설정 파일의 경로입니다.

경로에서의 CI/CD 변수 지원은 제한적입니다. trigger:include 경로의 변수가 비어 있거나 예상과 다른 값을 가짐을 참고합니다. 대신 inputs를 사용하는 것을 고려합니다.

trigger:include 예시:

trigger-child-pipeline:
  trigger:
    include: path/to/child-pipeline.gitlab-ci.yml

추가 세부 정보:

다음을 사용합니다.

• 동적 차일드 파이프라인을 트리거하려면 trigger:include:artifact를 사용합니다.

• 다운스트림 파이프라인 설정에서 spec:inputs를 사용하는 경우, 입력을 설정하려면 trigger:include:inputs를 사용합니다.

• 다음의 경우 차일드 파이프라인 설정 파일 경로에 trigger:include:local을 사용합니다.

  • 여러 차일드 파이프라인 설정 파일을 결합하는 경우.

  • trigger:include:inputs와 결합해 차일드 파이프라인에 입력을 전달하는 경우. 예를 들면 다음과 같습니다.

    staging-job:
      trigger:
        include:
          - local: path/to/child-pipeline.yml
            inputs:
              environment: staging
    

• 다른 프로젝트의 설정 파일로 차일드 파이프라인을 트리거하려면 trigger:include:project를 사용합니다. 해당 파일에 추가 include 항목이 있으면, GitLab은 파일을 호스팅하는 프로젝트가 아니라 파이프라인을 실행하는 프로젝트에서 파일을 찾습니다.

• CI/CD 템플릿으로 차일드 파이프라인을 트리거하려면 trigger:include:template를 사용합니다.

관련 주제:

• 차일드 파이프라인 설정 예시.

---

trigger:include:inputs#

히스토리

• Introduced in GitLab 17.11.

다운스트림 파이프라인 설정에서 spec:inputs를 사용하는 경우, trigger:include:inputs를 사용해 차일드 파이프라인의 입력을 설정합니다.

trigger:inputs 예시:

trigger-job:
  trigger:
    include:
      - local: path/to/child-pipeline.yml
        inputs:
          website: "My website"

---

trigger:project#

trigger:project를 사용하면 job을 "트리거 job"으로 선언할 수 있으며, 이 job은 멀티 프로젝트 파이프라인을 시작합니다.

기본적으로 멀티 프로젝트 파이프라인은 기본 브랜치에 대해 트리거됩니다. 다른 브랜치를 지정하려면 trigger:branch를 사용합니다.

키워드 유형: job 키워드. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• 다운스트림 프로젝트의 경로입니다. CI/CD 변수는 지원되지만 job 전용 변수는 지원되지 않습니다.

trigger:project 예시:

trigger-multi-project-pipeline:
  trigger:
    project: my-group/my-project

다른 브랜치에 대한 trigger:project 예시:

trigger-multi-project-pipeline:
  trigger:
    project: my-group/my-project
    branch: development

관련 주제:

• 멀티 프로젝트 파이프라인 설정 예시.
• 특정 브랜치·태그·커밋에 대해 파이프라인을 실행하려면 트리거 토큰을 사용해 파이프라인 트리거 API로 인증할 수도 있습니다. 트리거 토큰은 trigger 키워드와는 다릅니다.

---

trigger:strategy#

히스토리

• strategy:mirror option introduced in GitLab 18.2.

trigger:strategy를 사용하면 trigger job이 success로 표시되기 전에 다운스트림 파이프라인이 완료될 때까지 강제로 기다리게 할 수 있습니다.

이 동작은 다운스트림 파이프라인이 생성되는 즉시 trigger job이 success로 표시되는 기본 동작과는 다릅니다.

이 설정을 사용하면 파이프라인 실행이 병렬이 아니라 순차적으로 이루어집니다.

지원되는 값:

• mirror: 다운스트림 파이프라인의 상태를 그대로 반영합니다.
• depend: 권장하지 않으며 대신 mirror를 사용합니다. 트리거 job 상태는 다운스트림 파이프라인 상태에 따라 failed, success, running 중 하나로 표시됩니다. 추가 세부 정보를 참고합니다.

trigger:strategy 예시:

trigger_job:
  trigger:
    include: path/to/child-pipeline.yml
    strategy: mirror

이 예시에서 후속 stage의 job은 트리거된 파이프라인이 성공적으로 완료될 때까지 기다린 후 시작합니다.

추가 세부 정보:

• 다운스트림 파이프라인의 선택적 수동 job은 다운스트림 파이프라인이나 업스트림 트리거 job의 상태에 영향을 주지 않습니다. 다운스트림 파이프라인은 선택적 수동 job을 실행하지 않고도 성공적으로 완료될 수 있습니다.
• 기본적으로 이후 stage의 job은 트리거 job이 완료될 때까지 시작되지 않습니다.
• 다운스트림 파이프라인의 차단 수동 job은 트리거 job이 성공 또는 실패로 표시되기 전에 실행되어야 합니다.
• strategy:depend를 사용하는 경우(더 이상 권장하지 않으며 대신 strategy:mirror를 사용합니다):
  • 다운스트림 파이프라인 상태가 수동 job으로 인해 waiting for manual action([status_manual])이면 트리거 job은 running([status_running])으로 표시됩니다.
  • 다운스트림 파이프라인에 실패한 job이 있더라도 해당 job이 allow_failure: true를 사용하면 다운스트림 파이프라인은 성공한 것으로 간주되며 트리거 job은 success로 표시됩니다.

---

trigger:forward#

trigger:forward를 사용하면 다운스트림 파이프라인에 전달할 항목을 지정할 수 있습니다. 부모-자식 파이프라인과 멀티 프로젝트 파이프라인 양쪽 모두에 전달되는 항목을 제어할 수 있습니다.

전달된 변수는 중첩된 다운스트림 트리거 job도 trigger:forward를 사용하지 않는 한, 기본적으로 중첩된 다운스트림 파이프라인에 다시 전달되지 않습니다.

지원되는 값:

• yaml_variables: true(기본값) 또는 false. true 이면 트리거 job에 정의된 변수가 다운스트림 파이프라인에 전달됩니다. 여기에는 job이 상속하는 기본 변수와 트리거 job의 variables 블록에 직접 정의된 변수가 모두 포함됩니다.
• pipeline_variables: true 또는 false(기본값). true 이면 파이프라인 변수가 다운스트림 파이프라인에 전달됩니다. 여기에는 수동 파이프라인 실행, 예약된 파이프라인의 변수와 needs에 나열된 job의 dotenv 변수가 포함됩니다.

trigger:forward 예시:

CI/CD 변수 MYVAR = my value로 이 파이프라인을 수동으로 실행합니다.

variables: # default variables for each job
  VAR: value

---

# Default behavior:
---

# - VAR is passed to the child
---

# - MYVAR is not passed to the child
child1:
  trigger:
    include: .child-pipeline.yml

---

# Forward pipeline variables:
---

# - VAR is passed to the child
---

# - MYVAR is passed to the child
child2:
  trigger:
    include: .child-pipeline.yml
    forward:
      pipeline_variables: true

---

# Do not forward YAML variables:
---

# - VAR is not passed to the child
---

# - MYVAR is not passed to the child
child3:
  trigger:
    include: .child-pipeline.yml
    forward:
      yaml_variables: false

추가 세부 정보:

• trigger:forward로 다운스트림 파이프라인에 전달된 CI/CD 변수는 우선순위가 높은 파이프라인 변수입니다. 다운스트림 파이프라인에 동일한 이름의 변수가 정의되어 있으면 일반적으로 해당 변수는 전달된 변수로 덮어써집니다.
• forward:yaml_variables는 trigger:include 경로의 CI/CD 변수에도 영향을 줍니다. 자세한 내용은 trigger:include 경로의 변수가 비어 있거나 예상과 다른 값을 가짐을 참고합니다.

---

when#

when을 사용하면 job이 실행되는 조건을 설정할 수 있습니다. job에 정의되지 않은 경우 기본값은 when: on_success 입니다.

키워드 유형: job 키워드. job의 일부로 사용할 수 있습니다. when: always와 when: never는 workflow:rules에서도 사용할 수 있습니다.

지원되는 값:

• on_success(기본값): 이전 stage의 job이 하나도 실패하지 않은 경우에만 job을 실행합니다.
• on_failure: 이전 stage의 job이 하나라도 실패한 경우에만 job을 실행합니다.
• never: 이전 stage의 job 상태와 관계없이 job을 실행하지 않습니다. rules 섹션이나 workflow: rules에서만 사용할 수 있습니다.
• always: 이전 stage의 job 상태와 관계없이 job을 실행합니다.
• manual: job을 수동 job으로 파이프라인에 추가합니다.
• delayed: job을 지연된 job으로 파이프라인에 추가합니다.

when 예시:

stages:
  - build
  - cleanup_build
  - test
  - deploy
  - cleanup

build_job:
  stage: build
  script:
    - make build

cleanup_build_job:
  stage: cleanup_build
  script:
    - cleanup build when failed
  when: on_failure

test_job:
  stage: test
  script:
    - make test

deploy_job:
  stage: deploy
  script:
    - make deploy
  when: manual
  environment: production

cleanup_job:
  stage: cleanup
  script:
    - cleanup after jobs
  when: always

이 예시에서 스크립트는 다음과 같이 동작합니다.

1. build_job 이 실패한 경우에만 cleanup_build_job을 실행합니다.
2. 성공 또는 실패 여부와 관계없이 파이프라인의 마지막 단계로 cleanup_job을 항상 실행합니다.
3. GitLab UI에서 수동으로 실행하면 deploy_job을 실행합니다.

추가 세부 정보:

• on_success와 on_failure에 대해 job의 상태를 평가할 때:
  • 이전 stage에서 allow_failure: true인 job은 실패했더라도 성공한 것으로 간주됩니다.
  • 이전 stage에서 건너뛴 job, 예를 들어 시작되지 않은 수동 job은 성공한 것으로 간주됩니다.
• allow_failure의 기본값은 when: manual에서는 true 입니다. rules:when: manual에서는 기본값이 false로 바뀝니다.

관련 주제:

• 보다 동적인 job 제어를 위해 when을 rules와 함께 사용할 수 있습니다.
• 파이프라인 시작 시점을 제어하기 위해 when을 workflow와 함께 사용할 수 있습니다.

---

manual_confirmation#

히스토리

• Introduced in GitLab 17.1.
• Support for environment stop jobs introduced in GitLab 18.3.

manual_confirmation을 when: manual과 함께 사용하면 수동 job에 대한 사용자 지정 확인 메시지를 정의할 수 있습니다. when: manual로 정의된 수동 job이 없으면 이 키워드는 아무런 효과가 없습니다.

수동 확인은 environment:action: stop을 사용하는 환경 중지 job을 포함해 모든 수동 job에서 동작합니다.

키워드 유형: job 키워드. job의 일부로만 사용할 수 있습니다.

지원되는 값:

• 확인 메시지 문자열입니다.

manual_confirmation 예시:

delete_job:
  stage: post-deployment
  script:
    - make delete
  when: manual
  manual_confirmation: 'Are you sure you want to delete this environment?'

stop_production:
  stage: cleanup
  script:
    - echo "Stopping production environment"
  environment:
    name: production
    action: stop
  when: manual
  manual_confirmation: "Are you sure you want to stop the production environment?"

---

start_in#

start_in을 사용하면 job 이 생성된 후 지정된 기간만큼 job 실행을 지연할 수 있습니다. 해당 job에 when: delayed를 설정해야 합니다.

키워드 유형: job 키워드입니다. job의 일부로만 사용할 수 있습니다.

가능한 입력값: 초, 분, 시간 단위의 기간입니다. 1주 이하여야 합니다. 유효한 값의 예시입니다.

• '5'(5초)
• '10 seconds'
• '30 minutes'
• '1 hour'
• '1 day'

start_in 예시:

deploy_production:
  stage: deploy
  script:
    - echo "Deploying to production"
  when: delayed
  start_in: 30 minutes

이 예시에서 deploy_production job은 이전 스테이지가 완료된 후 30분 뒤에 시작합니다.

추가 세부 정보:

• 타이머는 이전 job 이 끝날 때가 아니라 해당 job의 스테이지가 시작될 때 시작됩니다.
• 지연된 job을 수동으로 즉시 시작하려면 파이프라인 화면에서 Play([play])를 선택합니다.
• 최소 지연 기간은 1초이고 최대 지연 기간은 1주입니다.
• start_in은 when 이 delayed로 설정된 경우에만 동작합니다. when에 다른 값을 사용하면 설정이 유효하지 않습니다. job 이 rules를 사용하는 경우 start_in과 when은 job 레벨이 아니라 rules 안에 정의해야 합니다. 그렇지 않으면 config key may not be used with 'rules': start_in이라는 검증 오류가 발생합니다.
• start_in은 workflow:rules와 함께 지원되지 않지만 구문 위반을 일으키지는 않습니다.

관련 항목:

• 지연 후 job 실행

---

variables#

variables를 사용하면 CI/CD 변수를 정의할 수 있습니다.

변수는 CI/CD job 안에서 정의하거나, 최상위(전역) 키워드로 정의해 모든 job에 대한 기본 CI/CD 변수로 정의할 수 있습니다.

추가 세부 정보:

• YAML로 정의된 모든 변수는 연결된 Docker 서비스 컨테이너에도 설정됩니다.
• YAML로 정의된 변수는 민감하지 않은 프로젝트 설정을 위한 것입니다. 민감한 정보는 보호된 변수 또는 CI/CD 시크릿에 저장합니다.
• 수동 파이프라인 변수와 예약된 파이프라인 변수는 기본적으로 다운스트림 파이프라인에 전달되지 않습니다. 이러한 변수를 다운스트림 파이프라인에 전달하려면 trigger:forward를 사용합니다.

관련 항목:

• 사전 정의된 변수는 러너가 자동으로 생성해 job에서 사용할 수 있게 하는 변수입니다.
• 변수로 러너 동작을 설정할 수 있습니다.

---

Job variables#

job 변수는 해당 job의 script, before_script, after_script 섹션의 명령에서 사용할 수 있으며, 일부 job 키워드에서도 사용할 수 있습니다. 변수 지원 여부는 각 job 키워드의 지원되는 값 섹션을 확인합니다.

include와 같은 전역 키워드의 값으로는 job 변수를 사용할 수 없습니다.

지원되는 값: 변수 이름과 값의 쌍입니다.

• 이름에는 숫자, 문자, 밑줄(_)만 사용할 수 있습니다. 일부 셸에서는 첫 글자가 문자여야 합니다.
• 값은 문자열이어야 합니다.

CI/CD 변수가 지원됩니다.

job variables 예시:

review_job:
  variables:
    DEPLOY_SITE: "https://dev.example.com/"
    REVIEW_PATH: "/review"
  script:
    - deploy-review-script --url $DEPLOY_SITE --path $REVIEW_PATH

이 예시에서는 다음과 같습니다.

• review_job에는 DEPLOY_SITE와 REVIEW_PATH job 변수가 정의되어 있습니다. 두 job 변수 모두 script 섹션에서 사용할 수 있습니다.

---

Default variables#

최상위 variables 섹션에 정의된 변수는 모든 job에 대한 기본 변수 역할을 합니다.

각 기본 변수는 job에 동일한 이름의 변수가 이미 정의되어 있는 경우를 제외하고 파이프라인의 모든 job에서 사용할 수 있습니다. job에 정의된 변수가 우선 적용되므로, 동일한 이름의 기본 변수 값은 해당 job에서 사용할 수 없습니다.

job 변수와 마찬가지로 기본 변수도 다른 전역 키워드의 값으로는 사용할 수 없습니다. 예를 들면 include가 있습니다.

지원되는 값: 변수 이름과 값의 쌍입니다.

• 이름에는 숫자, 문자, 밑줄(_)만 사용할 수 있습니다. 일부 셸에서는 첫 글자가 문자여야 합니다.
• 값은 문자열이어야 합니다.

CI/CD 변수가 지원됩니다.

variables 예시:

variables:
  DEPLOY_SITE: "https://example.com/"

deploy_job:
  stage: deploy
  script:
    - deploy-script --url $DEPLOY_SITE --path "/"
  environment: production

deploy_review_job:
  stage: deploy
  variables:
    DEPLOY_SITE: "https://dev.example.com/"
    REVIEW_PATH: "/review"
  script:
    - deploy-review-script --url $DEPLOY_SITE --path $REVIEW_PATH
  environment: production

이 예시에서는 다음과 같습니다.

• deploy_job에는 정의된 변수가 없습니다. 기본 DEPLOY_SITE 변수가 해당 job에 복사되어 script 섹션에서 사용할 수 있습니다.
• deploy_review_job에는 이미 DEPLOY_SITE 변수가 정의되어 있으므로 기본 DEPLOY_SITE는 해당 job에 복사되지 않습니다. 이 job에는 REVIEW_PATH job 변수도 정의되어 있습니다. 두 job 변수 모두 script 섹션에서 사용할 수 있습니다.

---

variables:description#

description 키워드를 사용하면 기본 변수에 대한 설명을 정의할 수 있습니다. 이 설명은 파이프라인을 수동으로 실행할 때 미리 채워지는 변수 이름과 함께 표시됩니다.

키워드 유형: 이 키워드는 job variables가 아니라 기본 variables 에만 사용할 수 있습니다.

지원되는 값:

• 문자열입니다. Markdown을 사용할 수 있습니다.

variables:description 예시:

variables:
  DEPLOY_NOTE:
    description: "The deployment note. Explain the reason for this deployment."

추가 세부 정보:

• value 없이 사용하면 이 변수는 수동으로 트리거되지 않은 파이프라인에도 존재하며, 기본값은 빈 문자열('')입니다.

---

variables:value#

value 키워드를 사용하면 파이프라인 레벨(기본) 변수의 값을 정의할 수 있습니다. 이 키워드를 variables: description과 함께 사용하면 파이프라인을 수동으로 실행할 때 변수 값이 미리 채워집니다.

키워드 유형: 이 키워드는 job variables가 아니라 기본 variables 에만 사용할 수 있습니다.

지원되는 값:

• 문자열입니다.

variables:value 예시:

variables:
  DEPLOY_ENVIRONMENT:
    value: "staging"
    description: "The deployment target. Change this variable to 'canary' or 'production' if needed."

추가 세부 정보:

• variables: description 없이 사용하면 동작은 variables와 동일합니다.

---

variables:options#

variables:options를 사용하면 파이프라인을 수동으로 실행할 때 UI에서 선택할 수 있는 값 배열을 정의할 수 있습니다.

variables: value와 함께 사용해야 하며, value에 정의된 문자열은 다음을 만족해야 합니다.

• options 배열에 있는 문자열 중 하나여야 합니다.
• 기본 선택값입니다.

description이 없으면 이 키워드는 효과가 없습니다.

키워드 유형: 이 키워드는 job variables가 아니라 기본 variables 에만 사용할 수 있습니다.

지원되는 값:

• 문자열 배열입니다.

variables:options 예시:

variables:
  DEPLOY_ENVIRONMENT:
    value: "staging"
    options:
      - "production"
      - "staging"
      - "canary"
    description: "The deployment target. Set to 'staging' by default."

---

variables:expand#

expand 키워드를 사용하면 변수를 확장 가능하게 할지 여부를 설정할 수 있습니다.

키워드 유형: 이 키워드는 기본 variables와 job variables 모두에 사용할 수 있습니다.

지원되는 값:

• true(기본값): 변수가 확장 가능합니다.
• false: 변수가 확장 가능하지 않습니다.

variables:expand 예시:

variables:
  VAR1: value1
  VAR2: value2 $VAR1
  VAR3:
    value: value3 $VAR1
    expand: false

• VAR2의 결과는 value2 value1 입니다.
• VAR3의 결과는 value3 $VAR1 입니다.

추가 세부 정보:

• expand 키워드는 기본 및 job variables 키워드에만 사용할 수 있습니다. rules:variables 또는 workflow:rules:variables와 함께는 사용할 수 없습니다.