다운스트림 파이프라인

다운스트림 파이프라인 (Downstream pipelines)

다운스트림 파이프라인은 다른 파이프라인에 의해 트리거되는 GitLab CI/CD 파이프라인이에요. 다운스트림 파이프라인은 이를 트리거한 업스트림 파이프라인과 독립적으로, 그리고 동시에 실행됩니다. 파이프라인을 여러 조각으로 나눠 관리하고 싶거나, 다른 프로젝트의 파이프라인을 연결하고 싶을 때 유용한 개념이에요.

출처: 문서

본문

다운스트림 파이프라인은 다른 파이프라인에 의해 트리거되는 모든 GitLab CI/CD 파이프라인입니다. 다운스트림 파이프라인은 이를 트리거한 업스트림 파이프라인과 독립적이고 동시에 실행돼요.

부모-자식 파이프라인은 첫 번째 파이프라인과 같은 프로젝트에서 트리거되는 다운스트림 파이프라인입니다.
멀티-프로젝트 파이프라인은 첫 번째 파이프라인과 다른 프로젝트에서 트리거되는 다운스트림 파이프라인입니다.

부모-자식 파이프라인과 멀티-프로젝트 파이프라인을 비슷한 목적으로 사용할 수 있지만, 핵심 차이점이 있습니다.

파이프라인 계층은 기본적으로 최대 1000개의 다운스트림 파이프라인을 포함할 수 있습니다. 이 제한과 변경 방법에 대한 자세한 내용은 파이프라인 계층 크기 제한을 참고하세요.

부모-자식 파이프라인

부모 파이프라인은 같은 프로젝트에서 다운스트림 파이프라인을 트리거하는 파이프라인입니다. 다운스트림 파이프라인을 자식 파이프라인이라고 해요.

자식 파이프라인:

부모 파이프라인과 같은 프로젝트, ref, 커밋 SHA 아래에서 실행됩니다.
파이프라인이 실행되는 ref의 전체 상태에 직접 영향을 주지 않습니다. 예를 들어 main 브랜치의 파이프라인이 실패하면 "main이 깨졌다"고 말하는 게 일반적이에요. 자식 파이프라인의 상태는 trigger:strategy로 트리거된 경우에만 ref의 상태에 영향을 줍니다.
같은 ref에 대해 새 파이프라인이 만들어지면 interruptible로 구성된 파이프라인은 자동으로 취소됩니다.
프로젝트의 파이프라인 목록에는 표시되지 않습니다. 자식 파이프라인은 부모 파이프라인의 세부 정보 페이지에서만 볼 수 있어요.

중첩된 자식 파이프라인

부모와 자식 파이프라인은 자식 파이프라인 두 단계 이하의 최대 깊이를 가집니다.

부모 파이프라인은 많은 자식 파이프라인을 트리거할 수 있고, 이 자식 파이프라인들은 자신의 자식 파이프라인을 트리거할 수 있습니다. 그 이상의 자식 파이프라인 단계는 트리거할 수 없어요.

개요는 중첩된 동적 파이프라인 영상을 참고하세요.

멀티-프로젝트 파이프라인

한 프로젝트의 파이프라인이 다른 프로젝트의 다운스트림 파이프라인을 트리거할 수 있는데, 이를 멀티-프로젝트 파이프라인이라고 합니다. 업스트림 파이프라인을 트리거하는 사용자는 다운스트림 프로젝트에서 파이프라인을 시작할 권한이 있어야 합니다. 그렇지 않으면 다운스트림 파이프라인 시작에 실패합니다.

멀티-프로젝트 파이프라인:

다른 프로젝트의 파이프라인에서 트리거되지만, 업스트림(트리거하는) 파이프라인은 다운스트림(트리거된) 파이프라인에 대해 많은 제어 권한이 없습니다. 하지만 다운스트림 파이프라인의 ref를 선택하고 CI/CD 변수를 전달할 수 있어요.
자신이 실행되는 프로젝트의 ref 전체 상태에 영향을 주지만, trigger:strategy로 트리거되지 않았다면 트리거한 파이프라인의 ref 상태에는 영향을 주지 않습니다.
업스트림 파이프라인에서 같은 ref에 대해 새 파이프라인이 실행되어도 interruptible 사용 시 다운스트림 프로젝트에서 자동으로 취소되지 않습니다. 다운스트림 프로젝트에서 같은 ref에 대해 새 파이프라인이 트리거되면 자동으로 취소될 수 있어요.
다운스트림 프로젝트의 파이프라인 목록에서 볼 수 있습니다.
독립적이므로 중첩 제한이 없습니다.

공개 프로젝트를 사용해 프라이빗 프로젝트의 다운스트림 파이프라인을 트리거한다면 기밀성 문제가 없는지 확인하세요. 업스트림 프로젝트의 파이프라인 페이지는 항상 다음을 표시합니다.

다운스트림 프로젝트의 이름.
파이프라인의 상태.

`.gitlab-ci.yml` 파일의 잡에서 다운스트림 파이프라인 트리거

.gitlab-ci.yml 파일에서 trigger 키워드를 사용해 다운스트림 파이프라인을 트리거하는 잡을 만들 수 있습니다. 이 잡을 트리거 잡(trigger job)이라고 합니다.

예를 들어:

trigger_job:
  trigger:
    include:
      - local: path/to/child-pipeline.yml

trigger_job:
  trigger:
    project: project-group/my-downstream-project

트리거 잡이 시작되면, GitLab이 다운스트림 파이프라인을 만들려고 하는 동안 잡의 초기 상태는 pending입니다. 트리거 잡은 다운스트림 파이프라인이 성공적으로 생성되면 passed를, 그렇지 않으면 failed를 표시해요. 대신 트리거 잡에 다운스트림 파이프라인의 상태를 표시하도록 설정할 수도 있습니다.

트리거 잡은 러너를 사용하지 않으므로, 오래 실행되는 pending 트리거 잡은 보통 GitLab이 다운스트림 파이프라인을 만들 수 없었다는 뜻입니다. 문제 해결 단계는 다운스트림 파이프라인 문제 해결을 참고하세요.

`rules`로 다운스트림 파이프라인 잡 제어

CI/CD 변수나 rules 키워드를 사용해 다운스트림 파이프라인의 잡 동작을 제어할 수 있습니다.

trigger 키워드로 다운스트림 파이프라인을 트리거할 때 모든 잡의 $CI_PIPELINE_SOURCE 사전 정의 변수 값은:

멀티-프로젝트 파이프라인의 경우 pipeline.
부모-자식 파이프라인의 경우 parent_pipeline.

예를 들어 머지 리퀘스트 파이프라인도 실행하는 프로젝트에서 멀티-프로젝트 파이프라인의 잡을 제어하려면:

job1:
  rules:
    - if: $CI_PIPELINE_SOURCE == "pipeline"
  script: echo "This job runs in multi-project pipelines only"

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

job3:
  rules:
    - if: $CI_PIPELINE_SOURCE == "pipeline"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script: echo "This job runs in both multi-project and merge request pipelines"

다른 프로젝트에서 자식 파이프라인 구성 파일 사용

트리거 잡에서 include:project을 사용해 다른 프로젝트의 구성 파일로 자식 파이프라인을 트리거할 수 있어요.

microservice_a:
  trigger:
    include:
      - project: 'my-group/my-pipeline-library'
        ref: 'main'
        file: '/path/to/child-pipeline.yml'

여러 자식 파이프라인 구성 파일 결합

자식 파이프라인을 정의할 때 최대 세 개의 구성 파일을 포함할 수 있습니다. 자식 파이프라인의 구성은 모든 구성 파일을 병합해 만들어져요.

microservice_a:
  trigger:
    include:
      - local: path/to/microservice_a.yml
      - template: Jobs/SAST.gitlab-ci.yml
      - project: 'my-group/my-pipeline-library'
        ref: 'main'
        file: '/path/to/child-pipeline.yml'

동적 자식 파이프라인

프로젝트에 저장된 정적 파일 대신, 잡에서 생성한 YAML 파일로 자식 파이프라인을 트리거할 수 있어요. 이 기법은 변경된 콘텐츠를 대상으로 하는 파이프라인을 만들거나 대상과 아키텍처의 매트릭스를 구성하는 데 매우 강력합니다.

생성된 YAML 파일을 담은 아티팩트는 인스턴스 제한 내에 있어야 합니다.

개요는 동적으로 생성된 구성으로 자식 파이프라인 만들기 영상을 참고하세요.

동적 자식 파이프라인을 생성하는 예시 프로젝트는 Jsonnet으로 동적 자식 파이프라인을 참고하세요. 이 프로젝트는 데이터 템플릿 언어를 사용해 런타임에 .gitlab-ci.yml을 생성하는 방법을 보여줍니다. Dhall이나 ytt 같은 다른 템플릿 언어에도 유사한 프로세스를 사용할 수 있어요.

동적 자식 파이프라인 트리거

동적으로 생성된 구성 파일에서 자식 파이프라인을 트리거하려면:

잡에서 구성 파일을 생성하고 아티팩트로 저장합니다.

generate-config:
  stage: build
  script: generate-ci-config > generated-config.yml
  artifacts:
    paths:
      - generated-config.yml

구성 파일을 생성한 잡 이후에 트리거 잡이 실행되도록 구성합니다. include: artifact를 생성된 아티팩트로, include: job을 아티팩트를 만든 잡으로 설정합니다.

child-pipeline:
  stage: test
  trigger:
    include:
      - artifact: generated-config.yml
        job: generate-config

이 예시에서 GitLab은 generated-config.yml을 가져와 그 파일의 CI/CD 구성으로 자식 파이프라인을 트리거합니다.

아티팩트 경로는 러너가 아니라 GitLab이 파싱하므로, 경로가 GitLab을 실행하는 OS의 문법과 일치해야 합니다. GitLab이 Linux에서 실행되는데 테스트에 Windows 러너를 사용한다면, 트리거 잡의 경로 구분자는 /입니다. Windows 러너를 사용하는 잡의 다른 CI/CD 구성(예: 스크립트)은 \를 사용합니다.

동적 자식 파이프라인의 구성에서는 include 섹션에 CI/CD 변수를 사용할 수 없습니다.

머지 리퀘스트 파이프라인으로 자식 파이프라인 실행

파이프라인은 자식 파이프라인을 포함해 rules이나 workflow:rules을 사용하지 않으면 기본적으로 브랜치 파이프라인으로 실행됩니다. 머지 리퀘스트(부모) 파이프라인에서 트리거될 때 자식 파이프라인이 실행되도록 구성하려면 rules 또는 workflow:rules을 사용하세요. 예를 들어 rules를 사용하려면:

부모 파이프라인의 트리거 잡이 머지 리퀘스트에서 실행되도록 설정합니다.

trigger-child-pipeline-job:
  trigger:
    include: path/to/child-pipeline-configuration.yml
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

rules로 자식 파이프라인 잡이 부모 파이프라인에 의해 트리거될 때 실행되도록 구성합니다.

job1:
  script: echo "This child pipeline job runs any time the parent pipeline triggers it."
  rules:
    - if: $CI_PIPELINE_SOURCE == "parent_pipeline"

job2:
  script: echo "This child pipeline job runs only when the parent pipeline is a merge request pipeline"
  rules:
    - if: $CI_MERGE_REQUEST_ID

자식 파이프라인에서 $CI_PIPELINE_SOURCE는 항상 parent_pipeline 값을 가지므로:

if: $CI_PIPELINE_SOURCE == "parent_pipeline"을 사용해 자식 파이프라인 잡이 항상 실행되게 할 수 있습니다.
if: $CI_PIPELINE_SOURCE == "merge_request_event"로 자식 파이프라인 잡을 머지 리퀘스트 파이프라인용으로 구성할 수는 없습니다. 대신 if: $CI_MERGE_REQUEST_ID를 사용해 부모 파이프라인이 머지 리퀘스트 파이프라인일 때만 자식 파이프라인 잡이 실행되도록 설정하세요. 부모 파이프라인의 CI_MERGE_REQUEST_* 사전 정의 변수는 자식 파이프라인 잡에 전달됩니다.

멀티-프로젝트 파이프라인의 브랜치 지정

멀티-프로젝트 파이프라인을 트리거할 때 사용할 브랜치를 지정할 수 있습니다. GitLab은 브랜치 헤드의 커밋으로 다운스트림 파이프라인을 만듭니다. 예를 들어:

staging:
  stage: deploy
  trigger:
    project: my/deployment
    branch: stable-11-2

사용법:

project 키워드로 다운스트림 프로젝트의 전체 경로를 지정합니다. 변수 확장을 사용할 수 있어요.
branch 키워드로 project가 지정한 프로젝트의 브랜치 또는 태그 이름을 지정합니다. 변수 확장을 사용할 수 있어요.

API로 멀티-프로젝트 파이프라인 트리거

CI/CD 잡 토큰(CI_JOB_TOKEN)을 파이프라인 트리거 토큰 API 엔드포인트와 함께 사용해 CI/CD 잡 내부에서 멀티-프로젝트 파이프라인을 트리거할 수 있어요. GitLab은 잡 토큰으로 트리거된 파이프라인을, API 호출을 만든 잡이 포함된 파이프라인의 다운스트림 파이프라인으로 설정합니다.

예를 들어:

trigger_pipeline:
  stage: deploy
  script:
    - |
      curl --request POST \
        --form "token=$CI_JOB_TOKEN" \
        --form ref=main \
        --url "https://gitlab.example.com/api/v4/projects/9/trigger/pipeline"
  rules:
    - if: $CI_COMMIT_TAG
  environment: production

다운스트림 파이프라인 보기

파이프라인 세부 정보 페이지에서 다운스트림 파이프라인은 그래프 오른쪽의 카드 목록으로 표시됩니다. 이 뷰에서:

트리거 잡을 선택해 트리거된 다운스트림 파이프라인의 잡을 볼 수 있어요.
파이프라인 카드에서 Expand jobs chevron-lg-right을 선택해 다운스트림 파이프라인의 잡으로 뷰를 펼칠 수 있습니다. 한 번에 하나의 다운스트림 파이프라인을 볼 수 있어요.
파이프라인 카드 위에 마우스를 올리면 다운스트림 파이프라인을 트리거한 잡이 강조 표시됩니다.

다운스트림 파이프라인의 실패·취소된 잡 재시도

실패·취소된 잡을 재시도하려면 Retry(재시도)를 선택하세요.

다운스트림 파이프라인의 세부 정보 페이지에서.
파이프라인 그래프 뷰의 파이프라인 카드에서.

다운스트림 파이프라인 재생성

해당 트리거 잡을 재시도하면 다운스트림 파이프라인을 재생성할 수 있습니다. 새로 생성된 다운스트림 파이프라인이 파이프라인 그래프의 현재 다운스트림 파이프라인을 대체합니다.

다운스트림 파이프라인을 재생성하려면:

파이프라인 그래프 뷰의 트리거 잡 카드에서 Run again(재시도)을 선택하세요.

다운스트림 파이프라인 취소

아직 실행 중인 다운스트림 파이프라인을 취소하려면 Cancel(취소)을 선택하세요.

다운스트림 파이프라인의 세부 정보 페이지에서.
파이프라인 그래프 뷰의 파이프라인 카드에서.

다운스트림 파이프라인에서 부모 파이프라인 자동 취소

자식 파이프라인의 잡 중 하나가 실패하자마자 자동 취소되도록 구성할 수 있습니다.

부모 파이프라인은 다음 경우에만 자식 파이프라인의 잡이 실패할 때 자동 취소됩니다.

부모 파이프라인도 잡 실패 시 자동 취소하도록 설정됨.
트리거 잡이 strategy: mirror로 구성됨.

예를 들어:

.gitlab-ci.yml 내용:

workflow:
  auto_cancel:
    on_job_failure: all

trigger_job:
  trigger:
    include: child-pipeline.yml
    strategy: mirror

job3:
  script:
    - sleep 120

child-pipeline.yml 내용:

# Contents of child-pipeline.yml
workflow:
  auto_cancel:
    on_job_failure: all

job1:
  script: sleep 60

job2:
  script:
    - sleep 30
    - exit 1

이 예시에서:

부모 파이프라인이 자식 파이프라인과 job3을 동시에 트리거합니다.
자식 파이프라인의 job2가 실패하고 자식 파이프라인이 취소되며 job1도 멈춥니다.
자식 파이프라인이 취소됐으므로 부모 파이프라인도 자동 취소됩니다.

트리거 잡에 다운스트림 파이프라인의 상태 미러링

trigger: strategy를 사용해 트리거 잡에 다운스트림 파이프라인의 상태를 미러링할 수 있습니다.

strategy: mirror를 사용하면 트리거 잡이 항상 다운스트림 파이프라인과 같은 상태를 가집니다.

trigger_job:
  trigger:
    include:
      - local: path/to/child-pipeline.yml
    strategy: mirror

trigger_job:
  trigger:
    project: my/project
    strategy: mirror

strategy: depend는 트리거 잡의 상태가 다운스트림 파이프라인의 상태와 항상 일치하지 않으므로 권장되지 않습니다. trigger:strategy 참조의 추가 세부 사항을 참고하세요.

파이프라인 그래프에서 멀티-프로젝트 파이프라인 보기

멀티-프로젝트 파이프라인을 트리거한 후, 다운스트림 파이프라인은 파이프라인 그래프 오른쪽에 표시됩니다.

파이프라인 미니 그래프에서 다운스트림 파이프라인은 미니 그래프 오른쪽에 표시됩니다.

머지 리퀘스트에서 자식 파이프라인 보고서 보기

GitLab 18.6에서 도입되었습니다.
자식 파이프라인의 보안 보고서가 GitLab 18.9에서 도입되었습니다.

머지 리퀘스트 위젯에서 자식 파이프라인의 보고서를 보고 다운로드할 수 있습니다. 이는 여러 파이프라인을 수동으로 탐색해 실패와 취약점을 찾지 않고도 파이프라인 계층 전체에 걸친 테스트 결과와 품질 검사를 통합된 뷰로 제공합니다.

자식 파이프라인의 다음 보고서 유형이 지원됩니다.

단위 테스트 보고서(JUnit)
코드 품질 보고서
Terraform 보고서
지표 보고서
보안 보고서(SAST, 시크릿 감지, 의존성 스캐닝, 컨테이너 스캐닝, DAST, API 퍼징)

보안 보고서는 같은 프로젝트의 자식 파이프라인, 동적으로 생성된 자식 파이프라인, 파이프라인 실행 정책이 만든 파이프라인과 함께 동작합니다. 스캔 실행 정책의 보고서는 지원되지 않습니다.

자식 파이프라인의 테스트 결과와 보안 검색 결과는 부모 파이프라인의 Tests 및 Security 탭에도 나타납니다.

자식 파이프라인의 보안 검색 결과는 머지 리퀘스트 승인 정책을 트리거할 수 있습니다. 자식 파이프라인이 취약점을 감지하면 머지 전에 추가 승인이 필요할 수 있어요.

아티팩트 보고서를 생성하는 자식 파이프라인의 보고서가 머지 리퀘스트 위젯에 나타나게 하려면 strategy: depend 또는 strategy: mirror을 사용하세요. 예를 들어:

test-backend:
  trigger:
    include: backend-tests.yml
    strategy: depend

test-frontend:
  trigger:
    include: frontend-tests.yml
    strategy: depend

이 전략이 없으면 부모 파이프라인이 자식 파이프라인보다 먼저 완료되므로, 그 보고서가 머지 리퀘스트에 나타나지 않습니다.

업스트림 파이프라인에서 아티팩트 가져오기

needs:pipeline:job을 사용해 업스트림 파이프라인에서 아티팩트를 가져옵니다.

업스트림 파이프라인에서 artifacts 키워드로 잡에 아티팩트를 저장한 후 트리거 잡으로 다운스트림 파이프라인을 트리거합니다.

build_artifacts:
  stage: build
  script:
    - echo "This is a test artifact!" >> artifact.txt
  artifacts:
    paths:
      - artifact.txt

deploy:
  stage: deploy
  trigger:
    include:
      - local: path/to/child-pipeline.yml
  variables:
    PARENT_PIPELINE_ID: $CI_PIPELINE_ID

다운스트림 파이프라인의 잡에서 needs:pipeline:job을 사용해 성공한 잡의 아티팩트를 가져옵니다.

test:
  stage: test
  script:
    - cat artifact.txt
  needs:
    - pipeline: $PARENT_PIPELINE_ID
      job: build_artifacts

job을 업스트림 파이프라인에서 아티팩트를 만든 잡으로 설정하세요.

전제 조건:

다운스트림 프로젝트가 업스트림 프로젝트의 잡 토큰 범위 허용 목록에 추가됨.
다운스트림 파이프라인을 트리거하는 사용자가 업스트림 프로젝트에서 최소 Reporter 역할. 허용 목록에 프로젝트를 추가하는 것은 이 접근을 부여하지 않습니다.

업스트림 파이프라인에서 아티팩트를 가져오려면 needs:project을 사용합니다.

업스트림 파이프라인에서 artifacts 키워드로 잡에 아티팩트를 저장한 후 트리거 잡으로 다운스트림 파이프라인을 트리거합니다.

build_artifacts:
  stage: build
  script:
    - echo "This is a test artifact!" >> artifact.txt
  artifacts:
    paths:
      - artifact.txt

deploy:
  stage: deploy
  trigger: my/downstream_project   # Path to the project to trigger a pipeline in

다운스트림 파이프라인의 잡에서 needs:project을 사용해 성공한 잡의 아티팩트를 가져옵니다.

test:
  stage: test
  script:
    - cat artifact.txt
  needs:
    - project: my/upstream_project
      job: build_artifacts
      ref: main
      artifacts: true

설정: job은 업스트림 파이프라인에서 아티팩트를 만든 잡, ref는 브랜치, artifacts는 true.

다운스트림 잡이 시작되기 전에 업스트림 잡이 끝나도록 하세요. 그렇지 않으면 아티팩트를 가져올 수 없습니다. needs를 사용해 다운스트림 잡이 업스트림 잡을 기다리게 하세요. 자세한 내용은 이슈 356016을 참고하세요.

업스트림 머지 리퀘스트 파이프라인에서 아티팩트 가져오기

needs:project로 다운스트림 파이프라인에 아티팩트를 전달할 때 ref 값은 보통 main이나 development 같은 브랜치 이름입니다.

머지 리퀘스트 파이프라인의 ref 값은 refs/merge-requests/<id>/head 형식이며, 여기서 id는 머지 리퀘스트 ID입니다. 이 ref는 CI_MERGE_REQUEST_REF_PATH CI/CD 변수로 가져올 수 있어요. 머지 리퀘스트 파이프라인에서 ref로 브랜치 이름을 사용하면 안 됩니다. 다운스트림 파이프라인이 최신 브랜치 파이프라인에서 아티팩트를 가져오려 하기 때문입니다.

전제 조건:

다운스트림 프로젝트가 업스트림 프로젝트의 잡 토큰 범위 허용 목록에 추가됨.
다운스트림 파이프라인을 트리거하는 사용자가 업스트림 프로젝트에서 최소 Reporter 역할. 허용 목록에 프로젝트를 추가하는 것은 이 접근을 부여하지 않습니다.

branch 파이프라인 대신 업스트림 merge request 파이프라인에서 아티팩트를 가져오려면 변수 상속을 사용해 CI_MERGE_REQUEST_REF_PATH을 다운스트림 파이프라인에 전달합니다.

업스트림 파이프라인의 잡에서 artifacts 키워드로 아티팩트를 저장합니다.
다운스트림 파이프라인을 트리거하는 잡에서 $CI_MERGE_REQUEST_REF_PATH 변수를 전달합니다.

build_artifacts:
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
  stage: build
  script:
    - echo "This is a test artifact!" >> artifact.txt
  artifacts:
    paths:
      - artifact.txt

upstream_job:
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
  variables:
    UPSTREAM_REF: $CI_MERGE_REQUEST_REF_PATH
  trigger:
    project: my/downstream_project
    branch: my-branch

다운스트림 파이프라인의 잡에서 needs:project과 전달된 변수를 ref로 사용해 업스트림 파이프라인의 아티팩트를 가져옵니다.

test:
  stage: test
  script:
    - cat artifact.txt
  needs:
    - project: my/upstream_project
      job: build_artifacts
      ref: $UPSTREAM_REF
      artifacts: true

이 방법으로 업스트림 머지 리퀘스트 파이프라인에서 아티팩트를 가져올 수 있지만, 머지 결과 파이프라인에서는 그럴 수 없습니다.

다운스트림 파이프라인에 입력 전달

inputs 키워드로 다운스트림 파이프라인에 입력 값을 전달할 수 있어요. 입력은 변수보다 유형 검사, 옵션을 통한 검증, 설명, 기본값 같은 장점을 제공합니다.

먼저 대상 구성 파일에서 spec:inputs로 입력 파라미터를 정의합니다.

# Target pipeline configuration
spec:
  inputs:
    environment:
      description: "Deployment environment"
      options: [staging, production]
    version:
      type: string
      description: "Application version"

그런 다음 파이프라인을 트리거할 때 값을 제공합니다.

staging:
  trigger:
    include:
      - local: path/to/child-pipeline.yml
        inputs:
          environment: staging
          version: "1.0.0"

staging:
  trigger:
    project: my-group/my-deployment-project
    inputs:
      environment: staging
      version: "1.0.0"

다운스트림 파이프라인에 CI/CD 변수 전달

변수가 생성되거나 정의된 위치에 따라 몇 가지 다른 방법으로 CI/CD 변수를 다운스트림 파이프라인에 전달할 수 있어요.

YAML로 정의된 CI/CD 변수 전달

변수보다는 파이프라인 구성에 입력(inputs)이 권장됩니다. 더 나은 보안과 유연성을 제공하기 때문입니다.

variables 키워드로 CI/CD 변수를 다운스트림 파이프라인에 전달할 수 있습니다. 이 변수들은 변수 우선순위에서 파이프라인 변수입니다.

예를 들어:

variables:
  VERSION: "1.0.0"

staging:
  variables:
    ENVIRONMENT: staging
  stage: deploy
  trigger:
    include:
      - local: path/to/child-pipeline.yml

variables:
  VERSION: "1.0.0"

staging:
  variables:
    ENVIRONMENT: staging
  stage: deploy
  trigger: my-group/my-deployment-project

ENVIRONMENT 변수는 다운스트림 파이프라인에 정의된 모든 잡에서 사용할 수 있습니다.

VERSION 기본 변수도 다운스트림 파이프라인에서 사용할 수 있어요. 트리거 잡을 포함한 파이프라인의 모든 잡이 기본 variables을 상속하기 때문입니다.

기본 변수가 전달되지 않게 방지

기본 CI/CD 변수가 다운스트림 파이프라인에 도달하지 못하게 inherit:variables으로 막을 수 있습니다. 상속할 특정 변수를 나열하거나 모든 기본 변수를 차단할 수 있어요.

예를 들어:

variables:
  DEFAULT_VAR: value

trigger-job:
  inherit:
    variables: false
  variables:
    JOB_VAR: value
  trigger:
    include:
      - local: path/to/child-pipeline.yml

variables:
  DEFAULT_VAR: value

trigger-job:
  inherit:
    variables: false
  variables:
    JOB_VAR: value
  trigger: my-group/my-project

트리거된 파이프라인에서는 DEFAULT_VAR 변수를 사용할 수 없지만 JOB_VAR은 사용할 수 있습니다.

사전 정의 변수 전달

사전 정의 CI/CD 변수로 업스트림 파이프라인에 대한 정보를 전달하려면 보간(interpolation)을 사용합니다. 사전 정의 변수를 트리거 잡의 새 잡 변수로 저장하면, 그 변수가 다운스트림 파이프라인에 전달됩니다. 예를 들어:

trigger-job:
  variables:
    PARENT_BRANCH: $CI_COMMIT_REF_NAME
  trigger:
    include:
      - local: path/to/child-pipeline.yml

trigger-job:
  variables:
    UPSTREAM_BRANCH: $CI_COMMIT_REF_NAME
  trigger: my-group/my-project

업스트림 파이프라인의 $CI_COMMIT_REF_NAME 사전 정의 CI/CD 변수 값을 담은 UPSTREAM_BRANCH 변수가 다운스트림 파이프라인에서 사용할 수 있습니다.

이 방법으로 마스킹된 변수를 멀티-프로젝트 파이프라인에 전달하면 안 됩니다. CI/CD 마스킹 구성은 다운스트림 파이프라인에 전달되지 않아 변수가 다운스트림 프로젝트의 잡 로그에서 마스킹되지 않을 수 있어요.

트리거 잡에서 사용할 수 없으므로 이 방법으로 잡 전용 변수를 다운스트림 파이프라인에 전달할 수는 없습니다.

업스트림 파이프라인이 다운스트림보다 우선합니다. 업스트림과 다운스트림 프로젝트 모두에 정의된 같은 이름의 변수가 두 개 있으면 업스트림 프로젝트에 정의된 것이 우선해요.

잡에서 만든 dotenv 변수 전달

dotenv 변수 상속으로 다운스트림 파이프라인에 변수를 전달할 수 있습니다.

자세한 내용은 다운스트림 파이프라인에 변수 전달을 참고하세요.

다운스트림 파이프라인으로 전달할 변수의 유형 제어

trigger:forward 키워드로 다운스트림 파이프라인에 전달할 변수 유형을 지정합니다. 전달된 변수는 트리거 변수로 간주되며, 가장 높은 우선순위를 가집니다.

배포를 위한 다운스트림 파이프라인

trigger와 함께 environment 키워드를 사용할 수 있습니다. 배포 프로젝트와 애플리케이션 프로젝트를 별도로 관리한다면 트리거 잡에서 environment를 사용하고 싶을 수 있어요.

deploy:
  trigger:
    project: project-group/my-downstream-project
  environment: production

다운스트림 파이프라인은 인프라를 프로비저닝하고, 지정된 환경에 배포하며, 배포 상태를 업스트림 프로젝트로 반환할 수 있습니다.

업스트림 프로젝트에서 환경과 배포를 볼 수 있습니다.

고급 예시

이 예시 구성은 다음 동작을 가집니다.

업스트림 프로젝트가 브랜치 이름을 기반으로 환경 이름을 동적으로 구성합니다.
업스트림 프로젝트가 UPSTREAM_* 변수로 배포의 컨텍스트를 다운스트림 프로젝트에 전달합니다.

업스트림 프로젝트의 .gitlab-ci.yml:

stages:
  - deploy
  - cleanup

.downstream-deployment-pipeline:
  variables:
    UPSTREAM_PROJECT_ID: $CI_PROJECT_ID
    UPSTREAM_ENVIRONMENT_NAME: $CI_ENVIRONMENT_NAME
    UPSTREAM_ENVIRONMENT_ACTION: $CI_ENVIRONMENT_ACTION
  trigger:
    project: project-group/deployment-project
    branch: main
    strategy: mirror

deploy-review:
  stage: deploy
  extends: .downstream-deployment-pipeline
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    on_stop: stop-review

stop-review:
  stage: cleanup
  extends: .downstream-deployment-pipeline
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  when: manual

다운스트림 프로젝트의 .gitlab-ci.yml:

deploy:
  script: echo "Deploy to ${UPSTREAM_ENVIRONMENT_NAME} for ${UPSTREAM_PROJECT_ID}"
  rules:
    - if: $CI_PIPELINE_SOURCE == "pipeline" && $UPSTREAM_ENVIRONMENT_ACTION == "start"

stop:
  script: echo "Stop ${UPSTREAM_ENVIRONMENT_NAME} for ${UPSTREAM_PROJECT_ID}"
  rules:
    - if: $CI_PIPELINE_SOURCE == "pipeline" && $UPSTREAM_ENVIRONMENT_ACTION == "stop"

더 알아보기

다운스트림 파이프라인은 크게 부모-자식과 멀티-프로젝트 두 갈래로 나뉘어요. 부모-자식은 같은 프로젝트 안에서 잡을 독립적으로 쪼갤 때, 멀티-프로젝트는 서로 다른 프로젝트의 배포·테스트 파이프라인을 연결할 때 씁니다. 변수·입력 전달과 strategy: mirror/depend의 차이, 아티팩트 전달을 이해하면 파이프라인을 모듈화하는 데 큰 도움이 됩니다. 다음으로는 파이프라인 아키텍처와 머지 리퀘스트 파이프라인 문서를 이어서 보는 걸 추천해요.

다운스트림 파이프라인

다운스트림 파이프라인 (Downstream pipelines)

본문

부모-자식 파이프라인

중첩된 자식 파이프라인

멀티-프로젝트 파이프라인

.gitlab-ci.yml 파일의 잡에서 다운스트림 파이프라인 트리거

rules로 다운스트림 파이프라인 잡 제어

다른 프로젝트에서 자식 파이프라인 구성 파일 사용

여러 자식 파이프라인 구성 파일 결합

동적 자식 파이프라인

동적 자식 파이프라인 트리거

머지 리퀘스트 파이프라인으로 자식 파이프라인 실행

멀티-프로젝트 파이프라인의 브랜치 지정

API로 멀티-프로젝트 파이프라인 트리거

다운스트림 파이프라인 보기

다운스트림 파이프라인의 실패·취소된 잡 재시도

다운스트림 파이프라인 재생성

다운스트림 파이프라인 취소

다운스트림 파이프라인에서 부모 파이프라인 자동 취소

트리거 잡에 다운스트림 파이프라인의 상태 미러링

파이프라인 그래프에서 멀티-프로젝트 파이프라인 보기

머지 리퀘스트에서 자식 파이프라인 보고서 보기

업스트림 파이프라인에서 아티팩트 가져오기

업스트림 머지 리퀘스트 파이프라인에서 아티팩트 가져오기

다운스트림 파이프라인에 입력 전달

다운스트림 파이프라인에 CI/CD 변수 전달

YAML로 정의된 CI/CD 변수 전달

기본 변수가 전달되지 않게 방지

사전 정의 변수 전달

잡에서 만든 dotenv 변수 전달

다운스트림 파이프라인으로 전달할 변수의 유형 제어

배포를 위한 다운스트림 파이프라인

고급 예시

더 알아보기

`.gitlab-ci.yml` 파일의 잡에서 다운스트림 파이프라인 트리거

`rules`로 다운스트림 파이프라인 잡 제어