`workflow` 키워드

`workflow` 키워드 (The `workflow` keyword)

.gitlab-ci.yml 파일의 workflow 키워드로 파이프라인이 언제 생성되는지를 제어할 수 있어요. workflow는 job보다 먼저 평가됩니다. 예를 들어 어떤 job이 태그용으로 설정되어 있어도, workflow가 태그 파이프라인을 막는다면 그 job은 절대 실행되지 않아요.

출처: 문서

본문

`workflow: rules`의 공통 `if` 절

workflow: rules에 쓸 수 있는 몇 가지 if 절 예시를 볼게요.

예시 규칙	설명
`if: '$CI_PIPELINE_SOURCE == "merge_request_event"'`	MR 파이프라인이 언제 실행될지 제어.
`if: '$CI_PIPELINE_SOURCE == "push"'`	브랜치 파이프라인과 태그 파이프라인이 언제 실행될지 제어.
`if: $CI_COMMIT_TAG`	태그 파이프라인이 언제 실행될지 제어.
`if: $CI_COMMIT_BRANCH`	브랜치 파이프라인이 언제 실행될지 제어.

더 많은 예시는 공통 if 절 문서를 참고하세요.

`workflow: rules` 예시

다음 예시에서:

모든 push 이벤트(브랜치 변경과 새 태그)에 대해 파이프라인이 실행돼요.
커밋 메시지가 -draft로 끝나는 push 이벤트의 파이프라인은 when: never로 설정되어 실행되지 않아요.
schedule이나 MR용 파이프라인도 실행되지 않아요. true로 평가되는 규칙이 없기 때문입니다.

workflow:
  rules:
    - if: $CI_COMMIT_MESSAGE =~ /-draft$/
      when: never
    - if: $CI_PIPELINE_SOURCE == "push"

이 예시는 규칙이 엄격해서 다른 어떤 경우에도 파이프라인이 실행되지 않아요.

또는 모든 규칙을 when: never로 두고 마지막에 when: always 규칙을 둘 수도 있어요. when: never 규칙에 걸리는 파이프라인은 실행되지 않고, 그 외의 모든 파이프라인 유형은 실행됩니다. 예를 들면 이렇습니다.

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: never
    - if: $CI_PIPELINE_SOURCE == "push"
      when: never
    - when: always

이 예시는 schedule과 push(브랜치·태그) 파이프라인을 막아요. 마지막 when: always 규칙이 MR 파이프라인을 포함한 다른 모든 파이프라인 유형을 실행합니다.

브랜치 파이프라인과 MR 파이프라인 사이 전환 (Switch between branch pipelines and merge request pipelines)

MR이 생성된 뒤 파이프라인이 브랜치 파이프라인에서 MR 파이프라인으로 전환되게 하려면 .gitlab-ci.yml 파일에 workflow: rules 섹션을 추가하면 돼요. 두 파이프라인 유형을 동시에 쓰면 중복 파이프라인이 동시에 실행될 수 있어요. 중복 파이프라인을 막으려면 CI_OPEN_MERGE_REQUESTS 변수를 사용하세요.

다음 예시는 브랜치 파이프라인과 MR 파이프라인만 실행하고 다른 경우에는 파이프라인을 실행하지 않는 프로젝트를 위한 것이에요. 이렇게 실행됩니다.

브랜치에 열린 MR이 없으면 브랜치 파이프라인 실행.
브랜치에 열린 MR이 있으면 MR 파이프라인 실행.

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
      when: never
    - if: $CI_COMMIT_BRANCH

GitLab이 트리거를 시도하는 경우:

MR 파이프라인이면 파이프라인을 시작합니다. 예를 들어 열린 MR이 연결된 브랜치로의 push로 MR 파이프라인이 트리거될 수 있어요.
브랜치 파이프라인이지만 해당 브랜치에 열린 MR이 있다면 브랜치 파이프라인을 실행하지 않습니다. 예를 들어 브랜치 변경, API 호출, 예약 파이프라인으로 브랜치 파이프라인이 트리거될 수 있어요.
브랜치 파이프라인이지만 해당 브랜치에 열린 MR이 없다면 브랜치 파이프라인을 실행합니다.

기존 workflow 섹션에 규칙을 추가해서 MR이 생성될 때 브랜치 파이프라인에서 MR 파이프라인으로 전환되게 할 수도 있어요. 이 규칙을 workflow 섹션 맨 위에 추가하고, 그 뒤에 이미 있던 규칙들을 이어서 배치합니다.

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"
      when: never
    - # Previously defined workflow rules here

브랜치에서 실행되는 트리거 파이프라인은 $CI_COMMIT_BRANCH가 설정되어 비슷한 규칙에 막힐 수 있어요. 트리거 파이프라인의 파이프라인 소스는 trigger 또는 pipeline이므로, && $CI_PIPELINE_SOURCE == "push"가 트리거 파이프라인을 막지 않도록 보장합니다.

MR 파이프라인과 함께 쓰는 Git Flow (Git Flow with merge request pipelines)

workflow: rules를 MR 파이프라인과 함께 쓸 수 있어요. 이 규칙으로 MR 파이프라인 기능을 피처 브랜치에서 쓰면서, 소프트웨어의 여러 버전을 지원하는 장기 브랜치를 유지할 수 있습니다. 예를 들어 MR, 태그, 보호된 브랜치에만 파이프라인을 실행하려면 이렇게 해요.

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_TAG
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - if: $CI_COMMIT_REF_PROTECTED == "true"

이 예시는 기본 브랜치나 다른 장기 브랜치가 보호(protected)되어 있다고 가정해요.

초안(draft) MR 파이프라인 건너뛰기 (Skip pipelines for draft merge requests)

workflow: rules로 초안(draft) MR용 파이프라인을 건너뛸 수 있어요. 이렇게 하면 개발이 완료될 때까지 컴퓨팅 리소스를 아낄 수 있습니다. MR이 초안 상태인지 확인하려면 CI_MERGE_REQUEST_DRAFT 변수를 사용하세요. 이 변수는 GitLab이 지원하는 모든 초안 형식을 자동으로 감지합니다.

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_DRAFT == "true"
      when: never
    - when: always

stages:
  - build

build-job:
  stage: build
  script:
    - echo "Testing"

[!NOTE] CI_MERGE_REQUEST_DRAFT 변수는 GitLab 17.10에서 도입되었어요. 이전 버전에서는 정규 표현식과 함께 CI_MERGE_REQUEST_TITLE을 사용하세요.

트러블슈팅 (Troubleshooting)

`Checking pipeline status.` 메시지로 멈춘 MR (Merge request stuck with `Checking pipeline status.` message)

MR이 Checking pipeline status.를 표시하는데 메시지가 사라지지 않고(스피너가 계속 돌고), 이는 workflow:rules 때문일 수 있어요. 프로젝트에 Pipelines must succeed가 활성화되어 있는데 workflow:rules가 그 MR의 파이프라인 실행을 막는 경우 발생할 수 있습니다. 예를 들어 다음 workflow에서는 실행될 파이프라인이 없어서 MR을 병합할 수 없어요.

workflow:
  rules:
    - changes:
        - .gitlab/**/**.md
      when: never

더 알아보기

workflow: rules는 '어떤 상황에서도 파이프라인을 만들 것인지'를 파이프라인 수준에서 정하는 것이 핵심이에요. 초안 MR 건너뛰기, 브랜치·MR 전환, 태그·보호 브랜치만 실행 같은 패턴을 조합하면 컴퓨팅 비용과 중복 파이프라인을 줄일 수 있습니다. job 단위의 rules와 함께 쓰면 파이프라인과 job 모두를 원하는 대로 제어할 수 있어요.

`workflow` 키워드