새 파이프라인이 시작되기 전에 GitLab은 파이프라인 구성을 확인하여 해당 파이프라인에서 실행할 수 있는 job을 결정합니다. rules를 사용하여 변수 값이나 파이프라인 유형과 같은 조건에 따라 실행되도록 job을 구성할 수 있습니다. job 규칙을 사용할 때는 중복 파이프라인을 피하는 방법을 알아보세요. 파이프라인 생성을 제어하려면 workflow:rules를 사용하세요.

수동으로 실행해야 하는 Job 생성#

사용자가 시작하지 않으면 job이 실행되지 않도록 요구할 수 있습니다. 이를 수동 job이라고 합니다. 프로덕션에 배포하는 것과 같은 작업에 수동 job을 사용할 수 있습니다.

job을 수동으로 지정하려면 .gitlab-ci.yml 파일의 job에 when: manual을 추가합니다.

기본적으로 수동 job은 파이프라인이 시작될 때 건너뜀으로 표시됩니다.

보호된 브랜치를 사용하여 인가되지 않은 사용자가 수동 배포를 실행하지 못하도록 더 엄격하게 보호할 수 있습니다.

보관된 수동 job은 실행되지 않습니다.

수동 Job 유형#

수동 job은 선택 사항이거나 차단 방식일 수 있습니다.

선택적 수동 job에서:

• allow_failure는 true이며, 이는 rules 외부에서 when: manual이 정의된 job의 기본 설정입니다.
• 상태는 전체 파이프라인 상태에 기여하지 않습니다. 모든 수동 job이 실패해도 파이프라인은 성공할 수 있습니다.

차단 수동 job에서:

• allow_failure는 false이며, 이는 rules 내부에서 when: manual이 정의된 job의 기본 설정입니다.
• 파이프라인은 job이 정의된 Stage에서 멈춥니다. 파이프라인이 계속 실행되도록 하려면 수동 job을 실행합니다.
• 파이프라인이 성공해야 함이 활성화된 프로젝트의 머지 리퀘스트는 차단된 파이프라인으로 머지할 수 없습니다.
• 파이프라인에 차단됨 상태가 표시됩니다.

다운스트림 파이프라인에서 trigger:strategy가 있는 수동 job을 사용할 때, 수동 job의 유형은 파이프라인이 실행되는 동안 트리거 job의 상태에 영향을 줄 수 있습니다.

수동 Job 실행#

수동 job을 실행하려면 할당된 브랜치에 머지할 수 있는 권한이 있어야 합니다:

1. 파이프라인, job, 환경, 또는 배포 뷰로 이동합니다.
2. 수동 job 옆에서 실행([play])을 선택합니다.

수동 Job 실행 시 변수 지정#

수동 job을 실행할 때 추가적인 job 특정 CI/CD 변수를 제공할 수 있습니다. CI/CD 변수를 사용하는 job의 실행을 변경하려는 경우 여기에서 변수를 지정합니다.

수동 job 실행 및 재시도 시 모두 재정의할 수 있는 유형이 있고 검증된 파라미터는 job 입력을 사용하세요.

수동 job을 실행하고 추가 변수를 지정하려면:

• 파이프라인 뷰에서 실행([play])이 아닌 수동 job의 이름을 선택합니다.
• 양식에서 변수 키-값 쌍을 추가합니다.
• Job 실행을 선택합니다.

CI/CD 설정 또는 .gitlab-ci.yml 파일에 이미 정의된 변수를 추가하면, 변수가 새 값으로 재정의됩니다. 이 프로세스를 사용하여 재정의된 변수는 확장되며 마스킹되지 않습니다.

업데이트된 변수로 수동 Job 재시도#

히스토리

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

수동으로 지정된 변수로 이전에 실행된 수동 job을 재시도할 때, 변수를 업데이트하거나 동일한 변수를 사용할 수 있습니다.

유형이 있고 검증된 파라미터로 수동 job을 재시도하려면 job 입력을 사용하세요.

이전에 지정된 변수로 수동 job을 재시도하려면:

• 동일한 변수로:
  • job 세부 정보 페이지에서 재시도([retry])를 선택합니다.
• 업데이트된 변수로:
  • job 세부 정보 페이지의 드롭다운에서 수정된 값으로 job 재시도를 선택합니다.
  • 이전 실행에서 지정된 변수가 양식에 미리 입력됩니다. 이 양식에서 CI/CD 변수를 추가, 수정 또는 삭제할 수 있습니다.
  • Job 다시 실행을 선택합니다.

수동 Job에 대한 확인 요구#

민감한 job(예: 프로덕션에 배포하는 job)에 대한 실수로 인한 배포 또는 삭제를 방지하려면 when: manual과 함께 manual_confirmation을 사용하여 수동 job에 대한 확인을 요구합니다.

job을 실행하면 실행되기 전에 작업을 확인해야 합니다.

수동 Job 보호#

보호된 환경을 사용하여 수동 job을 실행할 권한이 있는 사용자 목록을 정의합니다. 보호된 환경과 연관된 사용자만 수동 job을 실행할 수 있도록 권한을 부여할 수 있습니다. 이를 통해:

• 환경에 배포할 수 있는 사람을 더 정확하게 제한할 수 있습니다.
• 승인된 사용자가 "승인"할 때까지 파이프라인을 차단할 수 있습니다.

수동 job을 보호하려면:

1. job에 environment를 추가합니다. 예시:

   deploy_prod:
     stage: deploy
     script:
       - echo "Deploy to production server"
     environment:
       name: production
       url: https://example.com
     when: manual
     rules:
       - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
   

2. 보호된 환경 설정에서 환경(이 예시에서는 production)을 선택하고 수동 job을 실행할 권한이 있는 사용자, 권한 또는 그룹을 배포 허용 목록에 추가합니다. 이 목록에 있는 사람과 항상 보호된 환경을 사용할 수 있는 GitLab 관리자만 이 수동 job을 실행할 수 있습니다.

차단 수동 job과 함께 보호된 환경을 사용하여 이후 파이프라인 Stage를 승인할 수 있는 사용자 목록을 가질 수 있습니다. 보호된 수동 job에 allow_failure: false를 추가하면 인가된 사용자가 수동 job을 실행한 후에만 파이프라인의 다음 Stage가 실행됩니다.

지연 후 Job 실행#

대기 기간 후 스크립트를 실행하거나, job이 즉시 pending 상태로 진입하는 것을 피하려면 when: delayed를 사용합니다.

start_in 키워드로 기간을 설정할 수 있습니다. start_in의 값은 단위가 제공되지 않는 한 초 단위의 경과 시간입니다. 최소값은 1초이고 최대값은 1주일입니다. 유효한 값의 예시:

• '5' (단위 없는 값은 작은따옴표로 묶어야 함)
• 5 seconds
• 30 minutes
• 1 day
• 1 week

Stage에 지연된 job이 포함된 경우, 파이프라인은 지연된 job이 완료될 때까지 진행하지 않습니다. 이 키워드를 사용하여 여러 Stage 사이에 지연을 삽입할 수 있습니다.

지연된 job의 타이머는 이전 Stage가 완료된 직후 시작됩니다. 다른 유형의 job과 마찬가지로 이전 Stage가 성공하지 않으면 지연된 job의 타이머가 시작되지 않습니다.

다음 예시는 이전 Stage가 완료된 후 30분 후에 실행되는 timed rollout 10%라는 job을 생성합니다:

timed rollout 10%:
  stage: deploy
  script: echo 'Rolling out 10% ...'
  when: delayed
  start_in: 30 minutes
  environment: production

지연된 job의 활성 타이머를 멈추려면 일정 취소([time-out])를 선택합니다. 이 job은 더 이상 자동으로 실행되도록 예약할 수 없습니다. 하지만 수동으로 job을 실행할 수 있습니다.

지연된 job을 수동으로 시작하려면 일정 취소([time-out])를 선택하여 지연 타이머를 멈춘 다음 실행([play])을 선택합니다. 곧 GitLab Runner가 job을 시작합니다.

보관된 지연된 job은 실행되지 않습니다.

대규모 Job 병렬화#

대규모 job을 병렬로 실행되는 여러 소규모 job으로 분할하려면 .gitlab-ci.yml 파일에서 parallel 키워드를 사용합니다.

언어와 테스트 스위트마다 병렬화를 활성화하는 방법이 다릅니다. 예를 들어 Semaphore Test Boosters와 RSpec을 사용하여 Ruby 테스트를 병렬로 실행합니다:

# Gemfile
source 'https://rubygems.org'

gem 'rspec'
gem 'semaphore_test_boosters'

test:
  parallel: 3
  script:
    - bundle
    - bundle exec rspec_booster --job $CI_NODE_INDEX/$CI_NODE_TOTAL

새 파이프라인 빌드의 Jobs 탭으로 이동하면 RSpec job이 세 개의 개별 job으로 분할된 것을 볼 수 있습니다.

1차원 병렬 job 매트릭스 실행#

단일 파이프라인에서 동일한 job을 병렬로 여러 번 실행하되 job의 각 인스턴스에 다른 값을 사용하려면 parallel:matrix 키워드를 사용합니다:

deploystacks:
  stage: deploy
  script:
    - bin/deploy
  parallel:
    matrix:
      - PROVIDER: [aws, ovh, gcp, vultr]
  environment: production/$PROVIDER

이 예시에서는 4개의 deploystacks job이 생성되며 PROVIDER는 각각에서 다른 값을 갖는 CI/CD 변수가 됩니다:

• deploystacks: [aws]
• deploystacks: [ovh]
• deploystacks: [gcp]
• deploystacks: [vultr]

병렬 트리거 job 매트릭스 실행#

단일 파이프라인에서 트리거 job을 병렬로 여러 번 실행하되 job의 각 인스턴스에 다른 변수를 사용할 수 있습니다.

예시:

deploystacks:
  stage: deploy
  trigger:
    include: path/to/child-pipeline.yml
  parallel:
    matrix:
      - PROVIDER: aws
        STACK: [monitoring, app1]
      - PROVIDER: ovh
        STACK: [monitoring, backup]
      - PROVIDER: [gcp, vultr]
        STACK: [data]

이 예시는 PROVIDER와 STACK에 대해 각각 다른 값을 가진 6개의 병렬 deploystacks 트리거 job을 생성하고, 해당 변수로 6개의 다른 하위 파이프라인을 생성합니다.

deploystacks: [aws, monitoring]
deploystacks: [aws, app1]
deploystacks: [ovh, monitoring]
deploystacks: [ovh, backup]
deploystacks: [gcp, data]
deploystacks: [vultr, data]

각 병렬 매트릭스 Job에 대해 다른 러너 태그 선택#

동적 러너 선택을 위해 parallel: matrix에 정의된 값을 tags 키워드와 함께 사용할 수 있습니다:

deploystacks:
  stage: deploy
  script:
    - bin/deploy
  parallel:
    matrix:
      - PROVIDER: aws
        STACK: [monitoring, app1]
      - PROVIDER: gcp
        STACK: [data]
  tags:
    - ${PROVIDER}-${STACK}
  environment: $PROVIDER/$STACK

rules에서 매트릭스 변수 사용#

GitLab은 해당 job의 변수 값을 사용하여 각 개별 매트릭스 job에 대해 별도로 rules를 평가합니다.

rules:if에서 매트릭스 변수 사용#

변수 값에 따라 개별 매트릭스 job을 포함하거나 제외하기 위해 rules:if 표현식에 매트릭스 변수를 사용하세요.

예를 들어 매트릭스 변수 SKIP이 "true"로 설정된 경우 job을 건너뛰려면:

test:
  script: echo "Building $ARCH"
  parallel:
    matrix:
      - ARCH: [amd64, arm64]
        SKIP: ["false", "true"]
  rules:
    - if: $SKIP == "true"
      when: never
    - when: on_success

SKIP이 "false"인 job만 파이프라인에 포함됩니다.

rules:changes에서 매트릭스 변수 사용#

해당 job과 관련된 파일이 변경된 경우에만 매트릭스 job을 포함하기 위해 rules:changes 경로에 매트릭스 변수를 사용하세요. 이 패턴은 각 매트릭스 값이 자체 디렉토리가 있는 컴포넌트 또는 서비스에 해당하는 모노레포에서 유용합니다.

예를 들어 해당 job의 파일이 변경된 경우에만 테스트 job을 실행하려면:

test:
  script: echo "Testing $COMPONENT"
  parallel:
    matrix:
      - COMPONENT: [frontend, backend, database]
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"
      changes:
        - components/$COMPONENT/**/*

이 예시에서:

• 각 COMPONENT 값에 대해 하나씩 총 세 개의 test job이 평가됩니다.
• 각 job은 경로에 자체 $COMPONENT 값이 대입된 rules:changes를 확인합니다.
• 일치하는 파일이 변경된 job만 파이프라인에 추가됩니다.

예를 들어 components/frontend/npm.lock만 변경된 경우 frontend job만 실행됩니다.

동일한 경로에 여러 매트릭스 변수를 사용할 수 있습니다:

test:
  script: echo "Testing $SERVICE in $ENV"
  parallel:
    matrix:
      - SERVICE: [api, web]
        ENV: [dev, prod]
  rules:
    - changes:
        - config/$SERVICE/$ENV/**/*

rules:exists에서 매트릭스 변수 사용#

특정 파일이 존재할 때만 매트릭스 job을 포함하기 위해 rules:exists 경로에 매트릭스 변수를 사용하세요.

예를 들어:

test:
  script: echo "Testing $TYPE"
  parallel:
    matrix:
      - TYPE: [go, ruby, python]
  rules:
    - exists:
        - "**/*.$TYPE"

parallel:matrix Job에서 아티팩트 가져오기#

dependencies 키워드를 사용하여 parallel:matrix로 생성된 job에서 아티팩트를 가져올 수 있습니다. dependencies의 값으로 job 이름을 다음 형식의 문자열로 사용합니다:

<job_name> [<matrix argument 1>, <matrix argument 2>, ... <matrix argument N>]

예를 들어 RUBY_VERSION이 2.7이고 PROVIDER가 aws인 job에서 아티팩트를 가져오려면:

ruby:
  image: ruby:${RUBY_VERSION}
  parallel:
    matrix:
      - RUBY_VERSION: ["2.5", "2.6", "2.7", "3.0", "3.1"]
        PROVIDER: [aws, gcp]
  script: bundle install

deploy:
  image: ruby:2.7
  stage: deploy
  dependencies:
    - "ruby: [2.7, aws]"
  script: echo hello
  environment: production

dependencies 항목 주위의 따옴표는 필수입니다.

여러 병렬화된 Job에서 needs를 사용하여 병렬화된 Job 지정#

히스토리

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

needs:parallel:matrix를 사용하여 여러 병렬화된 job 간의 종속성을 생성할 수 있습니다. 구성을 위한 두 가지 기법을 사용할 수 있습니다:

• matrix. 표현식을 사용하여 자동으로
• 아래에 설명된 것처럼 수동으로

예시:

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

mac:build:
  stage: build
  script: echo "Building mac..."
  parallel:
    matrix:
      - PROVIDER: [gcp, vultr]
        STACK: [data, processing]

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

mac:rspec:
  stage: test
  needs:
    - job: mac:build
      parallel:
        matrix:
          - PROVIDER: [gcp, vultr]
            STACK: [data]
  script: echo "Running rspec on mac..."

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

이 예시는 여러 job을 생성합니다. 병렬 job은 PROVIDER와 STACK에 대해 각각 다른 값을 가집니다.

• 3개의 병렬 linux:build job:
  • linux:build: [aws, monitoring]
  • linux:build: [aws, app1]
  • linux:build: [aws, app2]
• 4개의 병렬 mac:build job:
  • mac:build: [gcp, data]
  • mac:build: [gcp, processing]
  • mac:build: [vultr, data]
  • mac:build: [vultr, processing]
• linux:rspec job
• production job

job에는 세 가지 실행 경로가 있습니다:

• Linux 경로: linux:rspec job은 mac:build가 완료될 때까지 기다리지 않고 linux:build: [aws, app1] job이 완료되는 즉시 실행됩니다.
• macOS 경로: mac:rspec job은 linux:build가 완료될 때까지 기다리지 않고 mac:build: [gcp, data]와 mac:build: [vultr, data] job이 완료되는 즉시 실행됩니다.
• production job은 이전 모든 job이 완료된 후 실행됩니다.

병렬화된 job 간의 needs 지정#

needs:parallel:matrix를 사용하여 각 병렬 매트릭스 job의 순서를 추가로 정의할 수 있습니다.

예시:

build_job:
  stage: build
  script:
    # ensure that other parallel job other than build_job [1, A] runs longer
    - '[[ "$VERSION" == "1" && "$MODE" == "A" ]] || sleep 30'
    - echo build $VERSION $MODE
  parallel:
    matrix:
      - VERSION: [1,2]
        MODE: [A, B]

deploy_job:
  stage: deploy
  script: echo deploy $VERSION $MODE
  parallel:
    matrix:
      - VERSION: [3,4]
        MODE: [C, D]

'deploy_job: [3, D]':
  stage: deploy
  script: echo something
  needs:
  - 'build_job: [1, A]'

이 예시는 여러 job을 생성합니다. 병렬 job은 VERSION과 MODE에 대해 각각 다른 값을 가집니다.

• 4개의 병렬 build_job job:
  • build_job: [1, A]
  • build_job: [1, B]
  • build_job: [2, A]
  • build_job: [2, B]
• 4개의 병렬 deploy_job job:
  • deploy_job: [3, C]
  • deploy_job: [3, D]
  • deploy_job: [4, C]
  • deploy_job: [4, D]

deploy_job: [3, D] job은 다른 build_job job이 완료될 때까지 기다리지 않고 build_job: [1, A] job이 완료되는 즉시 실행됩니다.

문제 해결#

수동 Job 실행 시 사용자 할당 불일치#

일부 엣지 케이스에서, 수동 job을 실행하는 사용자가 수동 job에 의존하는 이후 job의 사용자로 할당되지 않습니다.

수동 job에 의존하는 job에 할당된 사용자에 대해 엄격한 보안이 필요한 경우, 수동 job을 보호해야 합니다.