rules로 잡이 실행되는 시점 정하기

rules 키워드를 사용하면 잡을 파이프라인에 포함하거나 제외할 수 있어요. 규칙은 먼저 매칭되는 항목이 나올 때까지 순서대로 평가되고, 매칭된 규칙의 설정에 따라 잡이 파이프라인에 포함되거나 제외됩니다.

잡 스크립트에서 만든 dotenv 변수는 rules에 쓸 수 없어요. 규칙은 어떤 잡도 실행되기 전에 평가되기 때문이에요.

출처: 문서

본문

rules 예시

아래 예시는 if를 사용해 잡이 정확히 두 가지 경우에만 실행되도록 정의해요.

job:
  script: echo "Hello, Rules!"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: manual
      allow_failure: true
    - if: $CI_PIPELINE_SOURCE == "schedule"

파이프라인이 merge request용이면 첫 번째 규칙이 매칭되고, 해당 잡이 다음 속성과 함께 merge request 파이프라인에 추가돼요.
- when: manual (수동 잡)
- allow_failure: true (수동 잡을 실행하지 않아도 파이프라인이 계속 진행됨)
파이프라인이 merge request용이 아니면 첫 번째 규칙이 매칭되지 않아서 두 번째 규칙이 평가돼요.
파이프라인이 예약 파이프라인이면 두 번째 규칙이 매칭되고 잡이 예약 파이프라인에 추가돼요. 속성이 정의되지 않았으므로 다음 기본값과 함께 추가됩니다.
- when: on_success (기본값)
- allow_failure: false (기본값)
그 외 모든 경우에는 매칭되는 규칙이 없으므로 잡은 어떤 다른 파이프라인에도 추가되지 않아요.

반대로, 몇 가지 경우에는 잡을 제외하고 그 외 모든 경우에 실행하도록 규칙 집합을 정의할 수도 있어요.

job:
  script: echo "Hello, Rules!"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: never
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: never
    - when: on_success

파이프라인이 merge request용이면 잡이 추가되지 않아요.
파이프라인이 예약 파이프라인이면 잡이 추가되지 않아요.
그 외 모든 경우에는 when: on_success로 잡이 파이프라인에 추가돼요.

마지막 규칙으로 (when: never가 아닌) when 절을 사용하면 두 파이프라인이 동시에 시작될 수 있어요. 푸시 파이프라인과 merge request 파이프라인 둘 다 같은 이벤트(열려 있는 merge request의 소스 브랜치로의 푸시)로 트리거될 수 있거든요. 자세한 내용은 중복 파이프라인 방지를 참고하세요.

예약 파이프라인에서만 잡 실행하기

파이프라인이 예약된 경우에만 잡이 실행되도록 설정할 수 있어요. 예를 들면:

job:on-schedule:
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
  script:
    - make world

job:
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"
  script:
    - make build

이 예시에서 make world는 예약 파이프라인에서, make build는 브랜치·태그 파이프라인에서 실행돼요.

브랜치가 비어 있으면 잡 건너뛰기

rules:changes:compare_to를 사용하면 브랜치가 비어 있을 때 잡을 건너뛰어 CI/CD 리소스를 아낄 수 있어요. 이 설정은 브랜치를 기본 브랜치와 비교하는데, 브랜치에:

변경된 파일이 없으면 잡이 실행되지 않아요.
변경된 파일이 있으면 잡이 실행돼요.

예를 들어 기본 브랜치가 main인 프로젝트에서:

job:
  script:
    - echo "This job only runs for branches that are not empty"
  rules:
    - if: $CI_COMMIT_BRANCH
      changes:
        compare_to: 'refs/heads/main'
        paths:
          - '**/*'

이 잡의 규칙은 현재 브랜치의 모든 파일과 경로를 재귀적으로(**/*) main 브랜치와 비교해요. 브랜치 안 파일에 변경이 있을 때만 규칙이 매칭되고 잡이 실행돼요.

parallel:matrix 잡에서는 rules의 changes 경로에 matrix 변수를 사용해서 해당 matrix 값과 관련된 파일이 변경된 경우에만 각 잡 인스턴스를 실행할 수 있어요.

특정 파일이 없을 때 잡 실행하기

rules: exists를 사용하면 특정 파일이 존재하지 않을 때만 잡이 실행되도록 설정할 수 있어요.

예를 들어 merge request 파이프라인에서 example.yml 파일이 존재하지 않을 때 잡을 실행하려면:

job:
  script: echo "Hello, Rules!"
  rules:
    - exists:
      - "example_dir/example.yml"
      when: never
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

이 예시에서 브랜치에 example_dir/example.yml 파일이 있으면 잡이 실행되지 않아요. 파일이 없다면 merge request 파이프라인에서 잡이 실행될 수 있죠.

parallel:matrix 잡에서 rules:exists 경로에 matrix 변수를 사용하면 특정 파일이 존재할 때만 해당 잡 인스턴스를 포함시킬 수 있어요.

사전 정의 변수와 함께 쓰는 흔한 if 절

rules:if 절은 보통 사전 정의된 CI/CD 변수, 특히 CI_PIPELINE_SOURCE와 함께 사용해요.

아래 예시는 예약 파이프라인이나 (브랜치·태그 대상) 푸시 파이프라인에서 when: on_success(기본값)로 잡을 실행해요. 다른 파이프라인 유형에는 잡이 추가되지 않아요.

job:
  script: echo "Hello, Rules!"
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: manual
      allow_failure: true
    - if: $CI_PIPELINE_SOURCE == "push"

다음 예시는 merge request 파이프라인과 예약 파이프라인에서 when: on_success 잡으로 실행돼요. 다른 파이프라인 유형에서는 실행되지 않아요.

job:
  script: echo "Hello, Rules!"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_PIPELINE_SOURCE == "schedule"

자주 쓰는 다른 if 절은 다음과 같아요.

if: $CI_COMMIT_TAG: 태그에 변경이 푸시된 경우
if: $CI_COMMIT_BRANCH: 어떤 브랜치에든 변경이 푸시된 경우
if: $CI_COMMIT_BRANCH == "main": main에 변경이 푸시된 경우
if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH: 기본 브랜치에 변경이 푸시된 경우
if: $CI_COMMIT_BRANCH =~ /regex-expression/: 커밋 브랜치가 정규 표현식과 매칭되는 경우
if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_COMMIT_TITLE =~ /Merge branch.*/: 커밋 브랜치가 기본 브랜치이고 커밋 메시지 제목이 정규 표현식과 매칭되는 경우
if: $CUSTOM_VARIABLE == "value1": 사용자 변수 CUSTOM_VARIABLE이 정확히 value1인 경우

특정 파이프라인 유형에서만 잡 실행하기

사전 정의된 CI/CD 변수를 rules와 함께 사용하면 잡이 어떤 파이프라인 유형에서 실행될지 고를 수 있어요.

아래 표는 사용할 수 있는 변수들과 해당 변수가 제어하는 파이프라인 유형을 보여줘요.

새 커밋이나 태그처럼 브랜치로의 Git 푸시 이벤트에 실행되는 브랜치 파이프라인
브랜치에 새 Git 태그가 푸시될 때만 실행되는 태그 파이프라인
새 커밋 추가, merge request의 pipelines 탭에서 Run pipeline 선택처럼 merge request 변경에 실행되는 merge request 파이프라인
예약 파이프라인

| 변수 | Branch | Tag | Merge request | Scheduled | | CI_COMMIT_BRANCH | 예 | | | 예 | | CI_COMMIT_TAG | | 예 | | 예(예약 파이프라인이 태그에서 실행되도록 설정된 경우) | | CI_PIPELINE_SOURCE = push | 예 | 예 | | | | CI_PIPELINE_SOURCE = schedule | | | | 예 | | CI_PIPELINE_SOURCE = merge_request_event | | | 예 | | | CI_MERGE_REQUEST_IID | | | 예 | |

예를 들어 merge request 파이프라인과 예약 파이프라인에서는 실행되지만 브랜치·태그 파이프라인에서는 실행되지 않도록 잡을 설정하려면:

job1:
  script:
    - echo
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_PIPELINE_SOURCE == "schedule"
    - if: $CI_PIPELINE_SOURCE == "push"
      when: never

CI_PIPELINE_SOURCE 사전 정의 변수

CI_PIPELINE_SOURCE 변수로 다음 파이프라인 유형의 잡 추가 시점을 제어할 수 있어요.

이 값들은 pipelines API 엔드포인트를 쓸 때 source 파라미터로 반환되는 값과 같아요.

복잡한 규칙

if, changes, exists 같은 모든 rules 키워드를 같은 규칙 안에 사용할 수 있어요. 포함된 모든 키워드가 참일 때만 그 규칙이 참으로 평가돼요.

예를 들면:

docker build:
  script: docker build -t my-image:$CI_COMMIT_REF_SLUG .
  rules:
    - if: $VAR == "string value"
      changes:  # 아래 경로 중 하나가 수정된 파일과 매칭되면 잡을 포함하고 when:manual로 설정
        - Dockerfile
        - docker/scripts/**/*
      when: manual
      allow_failure: true

Dockerfile 파일이나 /docker/scripts 안의 아무 파일이 변경됐고 $VAR == "string value"라면, 잡이 수동으로 실행되고 실패가 허용돼요.

&&와 ||에 괄호를 조합해서 더 복잡한 변수 표현식을 만들 수도 있어요.

job1:
  script:
    - echo This rule uses parentheses.
  rules:
    - if: ($CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH || $CI_COMMIT_BRANCH == "develop") && $MY_VARIABLE

중복 파이프라인 방지

잡이 rules를 사용하면 브랜치로 커밋을 푸시하는 같은 동작이 여러 파이프라인을 트리거할 수 있어요. 여러 파이프라인 유형에 규칙을 명시적으로 설정하지 않아도 실수로 트리거될 수 있죠.

예를 들면:

job:
  script: echo "This job creates double pipelines!"
  rules:
    - if: $CUSTOM_VARIABLE == "false"
      when: never
    - when: always

이 잡은 $CUSTOM_VARIABLE이 false일 때는 실행되지 않지만, 푸시(브랜치) 파이프라인과 merge request 파이프라인을 포함한 다른 모든 파이프라인에서는 실행돼요. 이 설정에서 열려 있는 merge request의 소스 브랜치로 푸시할 때마다 중복 파이프라인이 생기죠.

중복 파이프라인을 피하려면 다음을 할 수 있어요.

workflow를 사용해 어떤 유형의 파이프라인이 실행될 수 있는지 지정한다.
잡이 아주 특정한 경우에만 실행되도록 규칙을 다시 작성하고, 마지막 when 규칙은 피한다:

job:
  script: echo "This job does NOT create double pipelines!"
  rules:
    - if: $CUSTOM_VARIABLE == "true" && $CI_PIPELINE_SOURCE == "merge_request_event"

잡 규칙을 바꿔 푸시(브랜치) 파이프라인이나 merge request 파이프라인 중 하나를 피해도 중복 파이프라인을 막을 수 있어요. 하지만 workflow: rules 없이 - when: always 규칙을 쓰면 GitLab이 파이프라인 경고를 표시해요.

예를 들어 아래 코드는 중복 파이프라인을 만들진 않지만 workflow: rules 없이는 권장되지 않아요.

job:
  script: echo "This job does NOT create double pipelines!"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"
      when: never
    - when: always

같은 잡에 중복 파이프라인을 막는 workflow:rules 없이 푸시 파이프라인과 merge request 파이프라인을 함께 포함하면 안 돼요.

job:
  script: echo "This job creates double pipelines!"
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

또한 같은 파이프라인에서 only/except 잡과 rules 잡을 섞지 마세요. YAML 오류가 생기진 않지만, only/except와 rules의 기본 동작이 달라서 디버깅이 어려운 문제가 생길 수 있어요.

job-with-no-rules:
  script: echo "This job runs in branch pipelines."

job-with-rules:
  script: echo "This job runs in merge request pipelines."
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

열려 있는 merge request이 있는 브랜치로 변경을 푸시할 때마다 중복 파이프라인이 실행돼요. 하나는 job-with-no-rules라는 단일 잡을 실행하는 브랜치 파이프라인이고, 다른 하나는 job-with-rules라는 잡을 실행하는 merge request 파이프라인이에요. 규칙이 없는 잡은 기본적으로 except: merge_requests와 같아서(잘못된 기본값 참고), job-with-no-rules는 merge request를 제외한 모든 경우에 실행돼요.

여러 잡에서 rules 재사용

!reference 태그를 사용하면 여러 잡에서 rules를 재사용할 수 있어요. job에 정의된 rules와 !reference 규칙을 조합할 수도 있어요. 예를 들면:

.default_rules:
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: never
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

job1:
  rules:
    - !reference [.default_rules, rules]
  script:
    - echo "This job runs for the default branch, but not schedules."

job2:
  rules:
    - !reference [.default_rules, rules]
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - echo "This job runs for the default branch, but not schedules."
    - echo "It also runs for merge requests."

CI/CD 변수 표현식

rules:if와 변수 표현식을 사용해 잡을 언제 파이프라인에 추가할지 제어할 수 있어요.

동치 연산자 ==와 !=로 변수를 문자열과 비교할 수 있어요. 작은따옴표와 큰따옴표 모두 유효하고, 변수는 비교의 왼쪽에 와야 해요. 예를 들면:

if: $VARIABLE == "some value"
if: $VARIABLE != "some value"

두 변수의 값을 비교할 수도 있어요. 예:

if: $VARIABLE_1 == $VARIABLE_2
if: $VARIABLE_1 != $VARIABLE_2

변수를 null 키워드와 비교해서 정의되어 있는지 확인할 수 있어요. 예:

if: $VARIABLE == null
if: $VARIABLE != null

변수가 정의됐지만 비어 있는지도 확인할 수 있어요. 예:

if: $VARIABLE == ""
if: $VARIABLE != ""

표현식에 변수 이름만 써서 변수가 정의되고 비어 있지 않은지 확인할 수 있어요. 예:

if: $VARIABLE

또한 다음도 할 수 있어요.

변수를 정규 표현식과 비교하기

=~와 !~ 연산자로 변수 값에 정규 표현식 매칭을 할 수 있어요.

다음 경우에 표현식이 참으로 평가돼요.

=~를 쓸 때 매칭이 발견된 경우
!~를 쓸 때 매칭이 발견되지 않은 경우

예를 들면:

if: $VARIABLE =~ /^content.*/
if: $VARIABLE !~ /^content.*/

추가로 알아두면 좋은 점:

/./처럼 단일 문자 정규 표현식은 지원되지 않고, 잘못된 표현식 구문 오류가 발생해요.
패턴 매칭은 기본적으로 대소문자를 구분해요. 패턴을 대소문자 구분 없이 쓰려면 i 플래그를 사용하세요. 예: /pattern/i
정규 표현식으로 매칭할 수 있는 건 태그나 브랜치 이름뿐이에요. 저장소 경로가 주어지면 항상 글자 그대로 매칭돼요.
전체 패턴을 /로 감싸야 해요. 예를 들어 issue-/.*/처럼 쓰면 issue-로 시작하는 모든 태그·브랜치 이름을 매칭할 수 없지만, /issue-.*/는 가능해요.
@ 기호는 ref의 저장소 경로 시작을 나타내요. 정규 표현식에서 @ 문자가 포함된 ref 이름을 매칭하려면 16진수 문자 코드 매칭 \x40을 사용해야 해요.
태그·브랜치 이름의 하위 문자열만 매칭되지 않도록 앵커 ^와 $를 사용하세요. 예를 들어 /^issue-.*$/는 /^issue-/와 동일하고, /issue/는 severe-issues라는 브랜치까지 매칭할 수 있어요.
정규 표현식을 이용한 변수 패턴 매칭은 RE2 정규 표현식 문법을 사용해요.

변수에 정규 표현식 저장하기

=~와 !~ 표현식의 오른쪽에 있는 변수는 정규 표현식으로 평가돼요. 정규 표현식은 앞뒤 슬래시(/)로 감싸야 해요. 예를 들면:

variables:
  pattern: '/^ab.*/'

regex-job1:
  variables:
    teststring: 'abcde'
  script: echo "This job will run, because 'abcde' matches the /^ab.*/ pattern."
  rules:
    - if: '$teststring =~ $pattern'

regex-job2:
  variables:
    teststring: 'fghij'
  script: echo "This job will not run, because 'fghi' does not match the /^ab.*/ pattern."
  rules:
    - if: '$teststring =~ $pattern'

정규 표현식 안의 변수는 확장되지 않아요. 예를 들면:

variables:
  string1: 'regex-job1'
  string2: 'regex-job2'
  pattern: '/$string2/'

regex-job1:
  script: echo "This job will NOT run, because the 'string1' variable inside the regex pattern is not expanded."
  rules:
    - if: '$CI_JOB_NAME =~ /$string1/'

regex-job2:
  script: echo "This job will NOT run, because the 'string2' variable inside the 'pattern' variable is not expanded."
  rules:
    - if: '$CI_JOB_NAME =~ $pattern'

변수 표현식 이어 붙이기

&&(그리고)나 ||(또는)로 여러 표현식을 이어 붙일 수 있어요. 예:

$VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"
$VARIABLE1 =~ /^content.*/ && $VARIABLE2 =~ /thing$/ && $VARIABLE3
$VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/ && $VARIABLE3

괄호로 표현식을 묶을 수 있어요. 괄호는 &&·||보다 우선순위가 높아서 괄호 안의 표현식이 먼저 평가되고, 그 결과가 나머지 표현식에 사용돼요. 연산자 우선순위는 &&가 ||보다 먼저 평가돼요.

괄호를 중첩해서 복잡한 조건을 만들 수 있고, 가장 안쪽의 괄호 표현식이 먼저 평가돼요. 예:

($VARIABLE1 =~ /^content.*/ || $VARIABLE2) && ($VARIABLE3 =~ /thing$/ || $VARIABLE4)
($VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/) && $VARIABLE3
$CI_COMMIT_BRANCH == "my-branch" || (($VARIABLE1 == "thing" || $VARIABLE2 == "thing") && $VARIABLE3)

표현식 부정하기

이력

도입: GitLab 18.11

! 연산자로 표현식 전체나 일부를 부정할 수 있어요. 예를 들면:

if: "!$VAR1": 변수가 비어 있거나 정의되지 않았을 때 참
if: !($VAR1 == "my variable"): 변수 값이 my variable과 일치하지 않을 때 참
if: $VAR1 && !$VAR2: VAR1이 존재하고 비어 있지 않고 VAR2가 존재하지 않거나 비어 있을 때 참
if: !($VAR1 || $VAR2): 두 변수 모두 존재하지 않거나 비어 있을 때만 참
if: !($VAR1 && $VAR2): 두 변수 중 하나가 존재하지 않거나 비어 있을 때 참

! 연산자는 변수가 비어 있는지 또는 정의되지 않았는지를 확인하지, 값이 false나 0인지는 확인하지 않아요. 예:

!"false"는 false로 평가돼요. 문자열 "false"가 비어 있지 않기 때문이에요(빈 문자열이 아닌 값은 truthy).
!"0"도 문자열이 비어 있지 않아서 false로 평가돼요.
!""는 참으로 평가돼요. 문자열이 비어 있기 때문이에요(빈 문자열은 falsy).

특정 값을 확인하려면 !($VAR == "false")나 !($VAR == "0")처럼 비교 연산자를 사용하세요.

only 또는 except에서 rules로 마이그레이션하기

rules와 CI/CD 변수 표현식을 사용하면 더 이상 쓰지 않는 only·except 키워드의 동작을 그대로 재현할 수 있어요.

예를 들어 이렇게 사용 중단된 설정으로 시작해 볼게요.

job1:
  script: echo
  only:
    - main
    - /^stable-branch.*$/
    - schedules

job2:
  script: echo
  except:
    - main
    - /^issue-.*$/
    - merge_requests

이 예시에서:

job1은 only를 사용해 다음 경우에 파이프라인에서 실행돼요.
- 브랜치가 기본 브랜치(main)일 때
- 브랜치 이름이 /^stable-branch.*$/ 패턴과 매칭될 때
- 파이프라인이 예약 일정으로 실행될 때
job2는 except를 사용해 다음 경우에 파이프라인에서 건너뛰어요.
- 브랜치가 기본 브랜치(main)일 때
- 브랜치 이름이 /^issue-.*$/ 패턴과 매칭될 때
- 파이프라인이 merge request 파이프라인일 때

rules로 비슷한 파이프라인 설정을 만들려면 CI/CD 변수 표현식을 사용하세요. only·except에서 rules로 직접 옮기는 예:

job1:
  script: echo
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - if: $CI_COMMIT_BRANCH =~ /^stable-branch.*$/
    - if: $CI_PIPELINE_SOURCE == "schedule"

job2:
  script: echo
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: never
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      when: never
    - if: $CI_COMMIT_BRANCH =~ /^issue-.*$/
      when: never
    - when: on_success

두 잡 모두 rules를 썼을 때만·except와 똑같이 동작해요. 다만 job2는 when: never 규칙을 없애서 더 단순화할 수 있어요.

job2가 실행될 때(실행되지 않을 때가 아니라) 규칙을 정의하세요. 예를 들어 job2가 기본 브랜치를 제외한 모든 브랜치와 태그에서 실행되어야 한다면:

job2:
  script: echo
  rules:
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
    - if: $CI_COMMIT_TAG

이 예시에서 job2는 브랜치가 기본 브랜치가 아닐 때, 그리고 새 Git 태그가 생성될 때 실행돼요. 그 외에는 잡이 실행되지 않아요.

문제 해결

`=~` 정규 표현식 매칭의 예상치 못한 동작

=~ 문자를 쓸 때는 비교의 오른쪽이 항상 유효한 정규 표현식인지 확인하세요.

오른쪽이 /로 감싼 유효한 정규 표현식이 아니면 표현식이 예상치 않게 평가돼요. 그 경우 비교는 왼쪽 값이 오른쪽 값의 하위 문자열인지 확인해요. 예를 들어 "23" =~ "1234"는 참으로 평가되지만, "23" =~ /1234/는 거짓으로 평가돼요(정반대 결과).

파이프라인이 이 동작에 의존하도록 설정하면 안 돼요.

더 알아보기

rules를 제대로 다루는 방법을 더 익히고 싶다면 rules 키워드 레퍼런스와 CI/CD 변수 문서를 함께 참고해 보세요. 파이프라인 유형별 트리거를 제어하는 데 사전 정의 변수인 CI_PIPELINE_SOURCE를 잘 활용하면 훨씬 깔끔한 설정을 만들 수 있답니다.

rules로 잡이 실행되는 시점 정하기