• 상하위 파이프라인
  • 중첩 자식 파이프라인
  • rules를 사용하여 하류 파이프라인 작업 제어
  • 다른 프로젝트의 자식 파이프라인 구성 파일 사용
  • 여러 자식 파이프라인 구성 파일 결합
  • 동적 자식 파이프라인
    • 동적 자식 파이프라인 트리거
  • Merge Request 파이프라인에서 자식 파이프라인 실행
  • 다중 프로젝트 파이프라인을 위한 브랜치 지정
• API를 사용하여 다중 프로젝트 파이프라인 트리거
• 다운스트림 파이프라인 보기
  • 다운스트림 파이프라인에서 실패한 작업 재시도 및 취소
  • 다운스트림 파이프라인 재생성
  • 다운스트림 파이프라인 취소
  • 다운스트림 파이프라인에서 부모 파이프라인 자동 취소
  • 트리거 작업에서 다운스트림 파이프라인의 상태를 미러링
  • 다중 프로젝트 파이프라인 보기를 파이프라인 그래프에서 확인
• 상위 파이프라인에서 아티팩트 가져오기
  • 상위 Merge Request 파이프라인에서 아티팩트 가져오기
• CI/CD 변수를 다운스트림 파이프라인에 전달하기
  • YAML로 정의된 CI/CD 변수 전달
    • 전역 변수가 전달되지 않도록 하기
  • 미리 정의된 변수 전달
  • 작업에서 생성된 dotenv 변수 전달
  • 하류 파이프라인으로 전달할 변수 유형 제어
• 배포를 위한 하류 파이프라인
  • 고급 예제
• 문제 해결
  • 트리거 작업이 실패하고 다중 프로젝트 파이프라인이 생성되지 않음
  • 자식 파이프라인의 작업이 실행되지 않을 때
  • Ref is ambiguous
  • 상류 파이프라인에서 작업 아티팩트를 다운로드할 때 403 Forbidden 오류

하류 파이프라인

하류 파이프라인은 다른 파이프라인에 의해 트리거된 GitLab CI/CD 파이프라인입니다. 하류 파이프라인은 트리거한 상류 파이프라인과 독립적으로 동시에 실행됩니다.

• 상하위 파이프라인은 첫 번째 파이프라인과 동일한 프로젝트에서 트리거된 하류 파이프라인입니다.
• 다중 프로젝트 파이프라인은 첫 번째 파이프라인과 다른 프로젝트에서 트리거된 하류 파이프라인입니다.

가끔 상하위 파이프라인과 다중 프로젝트 파이프라인을 유사한 목적으로 사용할 수 있지만, 중요한 차이점이 있습니다.

상하위 파이프라인

부모 파이프라인은 동일한 프로젝트에서 하류 파이프라인을 트리거하는 파이프라인입니다. 하류 파이프라인은 자식 파이프라인이라고 불립니다.

자식 파이프라인:

• 부모 파이프라인과 동일한 프로젝트, ref 및 커밋 SHA에서 실행됩니다.
• 파이프라인이 실행 중인 ref의 전체 상태에 직접적인 영향을 미치지 않습니다. 예를 들어, 메인 브랜치의 파이프라인이 실패하면 “메인이 망가졌다”고 말하는 것이 일반적입니다. 자식 파이프라인의 상태는 자식 파이프라인이 strategy:depend로 트리거되었을 때만 ref의 상태에 영향을 줍니다.
• 새로운 파이프라인이 동일한 ref에 대해 생성될 때 자동으로 취소됩니다.(interruptible가 설정된 경우)
• 프로젝트의 파이프라인 디렉터리에 표시되지 않습니다. 자식 파이프라인은 부모 파이프라인의 세부정보 페이지에서만 볼 수 있습니다.

중첩 자식 파이프라인

상위 및 하위 파이프라인은 최대 두 수준의 자식 파이프라인을 가질 수 있습니다.

부모 파이프라인은 많은 자식 파이프라인을 트리거할 수 있으며, 이러한 자식 파이프라인은 자신의 자식 파이프라인을 트리거할 수 있습니다. 또한 더 이상의 자식 파이프라인을 트리거할 수 없습니다.

관련_작업:
  트리거:
    include:
      - local: path/to/child-pipeline.yml

관련_작업:
  트리거:
    프로젝트: project-group/my-downstream-project

트리거 작업이 시작되면, GitLab은 하류 파이프라인을 만들려고 시도하는 동안 작업의 초기 상태가 보류로 표시됩니다. 하류 파이프라인이 성공적으로 생성되면 트리거 작업은 통과로 표시되며, 그렇지 않으면 실패로 표시됩니다. 또는 트리거 작업을 사용하여 하류 파이프라인의 상태를 표시할 수도 있습니다.

rules를 사용하여 하류 파이프라인 작업 제어

CI/CD 변수 또는 rules 키워드를 사용하여 하류 파이프라인 작업 동작을 제어할 수 있습니다.

trigger 키워드를 사용하여 하류 파이프라인을 트리거하면 모든 작업의 [$CI_PIPELINE_SOURCE 사전 정의 변수의 값이 다음과 같습니다.

• 다중 프로젝트 파이프라인의 경우 pipeline.
• 상하위 파이프라인의 경우 parent_pipeline.

예를 들어, 다음과 같이 프로젝트의 머지 요청 파이프라인을 실행하는 프로젝트에서 다중 프로젝트 파이프라인의 작업을 제어하려면:

작업1:
  Rules:
    - if: $CI_PIPELINE_SOURCE == "pipeline"
  스크립트: echo "이 작업은 다중 프로젝트 파이프라인에서만 실행됩니다"

작업2:
  Rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  스크립트: echo "이 작업은 머지 요청 파이프라인에서만 실행됩니다"

작업3:
  Rules:
    - if: $CI_PIPELINE_SOURCE == "pipeline"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  스크립트: echo "이 작업은 다중 프로젝트와 머지 요청 파이프라인에서 실행됩니다"

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

include:project를 사용하여 다른 프로젝트의 구성 파일로 자식 파이프라인을 트리거할 수 있습니다.

마이크로서비스_A:
  트리거:
    include:
      - project: 'my-group/my-pipeline-library'
        ref: 'main'
        file: '/path/to/child-pipeline.yml'

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

최대 세 개의 구성 파일을 포함하여 자식 파이프라인을 정의할 수 있습니다. 자식 파이프라인의 설정은 모든 구성 파일이 Merge된 구성으로 구성됩니다.

마이크로서비스_A:
  트리거:
    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 파일을 포함하는 아티팩트는 5 MB보다 크지 않아야합니다.

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

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

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

trigger_job:
  trigger:
    project: my/project
    strategy: depend

다중 프로젝트 파이프라인 보기를 파이프라인 그래프에서 확인

• 이동함 GitLab 16.8에서 GitLab Premium에서 GitLab Free로.

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

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

상위 파이프라인에서 아티팩트 가져오기

상위 Merge Request 파이프라인에서 아티팩트 가져오기

상위 파이프라인에서 needs:project를 사용하여 다운스트림 파이프라인에 아티팩트를 전달할 때, ref 값은 일반적으로 main 또는 development과 같은 브랜치 이름입니다.

Merge Request 파이프라인의 경우, ref 값은 refs/merge-requests/<id>/head 형식으로 되어 있으며, 여기서 id는 Merge Request ID입니다. 브랜치 파이프라인의 경우와는 달리 ref로 브랜치 이름을 사용하지 마세요, 왜냐하면 다운스트림 파이프라인이 가장 최신 브랜치 파이프라인에서 아티팩트를 가져오려고 시도하기 때문입니다.

브랜치 파이프라인이 아닌 상위 Merge Request 파이프라인에서 아티팩트를 가져오려면, 변수 상속을 사용하여 $CI_MERGE_REQUEST_REF_PATH를 다운스트림 파이프라인으로 전달하세요:

1. GitLab 15.9 이상에서는 상위 프로젝트의 작업 토큰 범위 허용 디렉터리에 다운스트림 프로젝트를 추가하세요.
2. 상위 파이프라인의 작업에서 artifacts 키워드를 사용하여 아티팩트를 저장하세요.

3. 다운스트림 파이프라인을 트리거하는 작업에서 $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
   

4. 다운스트림 파이프라인의 작업에서 needs:project 및 전달된 변수를 ref로 사용하여 상위 파이프라인에서 아티팩트를 가져옵니다:

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

이 방법을 사용하여 상위 Merge Request 파이프라인에서 아티팩트를 가져올 수 있지만, 머지 결과 파이프라인에서는 가져올 수 없습니다.

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

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

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

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 변수는 다운스트림 파이프라인에서 정의된 모든 작업에서 사용할 수 있습니다.

모든 파이프라인 작업, 트리거 작업을 포함한 모든 작업은 전역 variables을 상속하므로, VERSION 전역 변수도 다운스트림 파이프라인에서 사용할 수 있습니다.

전역 변수가 전달되지 않도록 하기

전역 CI/CD 변수를 다운스트림 파이프라인에 전달하지 않도록 하려면 inherit:variables:false을 사용할 수 있습니다.

예를 들어:

variables:
  GLOBAL_VAR: value

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

variables:
  GLOBAL_VAR: value

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

GLOBAL_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 변수 상속을 사용하여 하류 파이프라인으로 변수를 전달할 수 있습니다.

예를 들어, 다중 프로젝트 파이프라인에서:

1. 변수를 .env 파일에 저장합니다.
2. .env 파일을 dotenv 보고서로 저장합니다.

3. 하류 파이프라인을 트리거합니다.

   build_vars:
     stage: build
     script:
       - echo "BUILD_VERSION=hello" >> build.env
     artifacts:
       reports:
         dotenv: build.env
      
   deploy:
     stage: deploy
     trigger: my/downstream_project
   

4. 하류 파이프라인의 test 작업을 needs로 상위 프로젝트의 build_vars 작업에서 변수를 상속하도록 설정합니다. test 작업은 dotenv 보고서의 변수를 상속하며, 스크립트에서 BUILD_VERSION에 액세스할 수 있습니다.

   test:
     stage: test
     script:
       - echo $BUILD_VERSION
     needs:
       - project: my/upstream_project
         job: build_vars
         ref: master
         artifacts: true
   

하류 파이프라인으로 전달할 변수 유형 제어

trigger:forward 키워드를 사용하여 하류 파이프라인으로 전달할 변수 유형을 지정할 수 있습니다. 전달된 변수는 가장 높은 우선순위를 갖는 트리거 변수로 간주됩니다.

배포를 위한 하류 파이프라인

• GitLab 16.4에서 도입됨.

environment 키워드를 trigger와 함께 사용할 수 있습니다. 배포 및 애플리케이션 프로젝트를 별도로 관리하는 경우 트리거 작업에서 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: depend

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"

문제 해결

트리거 작업이 실패하고 다중 프로젝트 파이프라인이 생성되지 않음

다중 프로젝트 파이프라인에서 다음과 같은 경우 트리거 작업이 실패하고 하류 파이프라인이 생성되지 않습니다:

• 하류 프로젝트가 찾을 수 없는 경우.
• 상위 파이프라인을 만드는 사용자에게 허가 권한이 없을 경우.
• 하류 파이프라인이 보호된 브랜치를 대상으로 하며 사용자가 해당 보호된 브랜치에 대한 파이프라인을 실행할 권한이 없는 경우. 자세한 내용은 보호된 브랜치에서의 파이프라인 보안을 참조하십시오.

하류 프로젝트에서 권한 문제를 겪고 있는 사용자를 식별하려면 다음 명령을 사용하여 트리거 작업을 확인하고 user_id 속성을 살펴보십시오.

Ci::Bridge.find(<job_id>)

자식 파이프라인의 작업이 실행되지 않을 때

부모 파이프라인이 Merge Request 파이프라인인 경우, 자식 파이프라인은 작업이 실행되도록 하려면 workflow:rules 또는 rules를 사용해야 합니다.

자식 파이프라인의 모든 작업이 누락되거나 잘못된 rules 구성으로 인해 실행되지 못한 경우:

• 자식 파이프라인은 시작하지 못합니다.
• 부모 파이프라인의 트리거 작업은 하류 파이프라인을 만들 수 없음, 선택한 트리거에 대해 파이프라인을 실행할 수 없음. 구성된 rules로 인해 파이프라인에 작업이 추가되지 않았습니다.라는 오류가 표시됩니다.

Ref is ambiguous

태그와 동일한 이름의 브랜치가 있을 때 태그로 다중 프로젝트 파이프라인을 트리거할 수 없습니다. 이로 인해 다음과 같은 오류가 발생하여 하류 파이프라인을 생성할 수 없습니다: downstream pipeline can not be created, Ref is ambiguous.

태그 이름과 일치하는 브랜치 이름이 없는 경우에만 다중 프로젝트 파이프라인을 트리거할 수 있습니다.

상류 파이프라인에서 작업 아티팩트를 다운로드할 때 403 Forbidden 오류

GitLab 15.9 이후로, CI/CD 작업 토큰은 해당 파이프라인을 실행하는 프로젝트에 대해 범위가 지정됩니다. 따라서 하류 파이프라인의 작업 토큰은 기본적으로 상류 프로젝트에 액세스할 수 없습니다.

이 문제를 해결하려면 하류 프로젝트를 작업 토큰 범위 허용 디렉터리에 추가합니다.