특정 브랜치 또는 태그에 대한 파이프라인을 트리거하려면 파이프라인 트리거 API 엔드포인트에 대한 API 호출을 사용할 수 있습니다.

trigger 키워드를 사용하여 CI/CD 잡에서 다운스트림 파이프라인을 트리거할 수도 있습니다.

GitLab CI/CD로 마이그레이션하는 경우, 다른 공급자의 잡에서 API 엔드포인트를 호출하여 GitLab CI/CD 파이프라인을 트리거할 수 있습니다. 예를 들어 Jenkins 또는 CircleCI에서의 마이그레이션의 일부로 사용할 수 있습니다.

API를 사용하여 인증할 때 다음을 사용할 수 있습니다:

• 파이프라인 트리거 API 엔드포인트를 사용하여 브랜치 또는 태그 파이프라인을 트리거하는 파이프라인 트리거 토큰.
• 멀티 프로젝트 파이프라인을 트리거하기 위한 CI/CD 잡 토큰.
• 프로젝트 파이프라인 API 엔드포인트를 사용하여 새 파이프라인을 만들기 위한 API 접근 권한이 있는 다른 토큰.

파이프라인 트리거 토큰 만들기#

파이프라인 트리거 토큰을 생성하고 API 호출을 인증하는 데 사용하여 브랜치 또는 태그에 대한 파이프라인을 트리거할 수 있습니다. 토큰은 사용자의 프로젝트 접근 및 권한을 위임합니다.

사전 요구사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

트리거 토큰을 만들려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Pipeline trigger tokens를 확장합니다.
4. Add new token을 선택합니다.
5. 설명을 입력하고 Create pipeline trigger token을 선택합니다.
   • 직접 만든 모든 트리거의 전체 토큰을 볼 수 있고 복사할 수 있습니다.
   • 다른 프로젝트 멤버가 만든 토큰의 경우 처음 4자만 볼 수 있습니다.

파이프라인 트리거#

파이프라인 트리거 토큰을 만든 후 API에 접근할 수 있는 도구 또는 웹훅으로 파이프라인을 트리거하는 데 사용할 수 있습니다.

cURL 사용#

cURL을 사용하여 파이프라인 트리거 API 엔드포인트로 파이프라인을 트리거할 수 있습니다. 예를 들어:

• 여러 줄 cURL 명령 사용:

  curl --request POST \
       --form token=<token> \
       --form ref=<ref_name> \
       "https://gitlab.example.com/api/v4/projects/<project_id>/trigger/pipeline"
  

• cURL을 사용하고 쿼리 문자열에 <token>과 <ref_name> 전달:

  curl --request POST \
       "https://gitlab.example.com/api/v4/projects/<project_id>/trigger/pipeline?token=<token>&ref=<ref_name>"
  

각 예시에서 다음을 교체합니다:

• URL을 https://gitlab.com 또는 인스턴스 URL로.
• <token>을 트리거 토큰으로.
• <ref_name>을 main과 같은 브랜치 또는 태그 이름으로.
• <project_id>를 프로젝트 ID(예: 123456)로. 프로젝트 ID는 프로젝트 개요 페이지에 표시됩니다.

CI/CD 잡 사용#

파이프라인 트리거 토큰이 있는 CI/CD 잡을 사용하여 다른 파이프라인이 실행될 때 파이프라인을 트리거할 수 있습니다.

예를 들어, project-A에서 태그가 만들어질 때 project-B의 main 브랜치에서 파이프라인을 트리거하려면 project A의 .gitlab-ci.yml 파일에 다음 잡을 추가합니다:

trigger_pipeline:
  stage: deploy
  script:
    - 'curl --fail --request POST --form token=$MY_TRIGGER_TOKEN --form ref=main "${CI_API_V4_URL}/projects/123456/trigger/pipeline"'
  rules:
    - if: $CI_COMMIT_TAG
  environment: production

이 예시에서:

• 1234는 project-B의 프로젝트 ID입니다. 프로젝트 ID는 프로젝트 개요 페이지에 표시됩니다.
• rules로 인해 태그가 project-A에 추가될 때마다 잡이 실행됩니다.
• MY_TRIGGER_TOKEN은 트리거 토큰을 포함하는 마스킹된 CI/CD 변수입니다.

웹훅 사용#

다른 프로젝트의 웹훅에서 파이프라인을 트리거하려면 푸시 및 태그 이벤트에 대해 다음과 같은 웹훅 URL을 사용합니다:

https://gitlab.example.com/api/v4/projects/<project_id>/ref/<ref_name>/trigger/pipeline?token=<token>

다음을 교체합니다:

• URL을 https://gitlab.com 또는 인스턴스 URL로.
• <project_id>를 프로젝트 ID(예: 123456)로. 프로젝트 ID는 프로젝트 개요 페이지에 표시됩니다.
• <ref_name>을 main과 같은 브랜치 또는 태그 이름으로. 이 값은 웹훅 페이로드의 ref_name보다 우선합니다. 페이로드의 ref는 소스 리포지터리에서 트리거를 발생시킨 브랜치입니다. <ref_name>에 슬래시가 포함된 경우 URL 인코딩을 해야 합니다.
• <token>을 파이프라인 트리거 토큰으로.

웹훅 페이로드 접근#

웹훅을 사용하여 파이프라인을 트리거하는 경우 TRIGGER_PAYLOAD 사전 정의된 CI/CD 변수로 웹훅 페이로드에 접근할 수 있습니다. 페이로드는 파일 유형 변수로 노출되므로 cat $TRIGGER_PAYLOAD 또는 유사한 명령으로 데이터에 접근할 수 있습니다.

API 호출에 CI/CD 변수 전달#

트리거 API 호출에서 여러 CI/CD 변수를 전달할 수 있지만, 파이프라인 인풋을 사용하여 파이프라인 동작을 제어하는 것이 CI/CD 변수보다 향상된 보안과 유연성을 제공합니다.

이러한 변수는 가장 높은 우선순위를 가지며, 동일한 이름의 모든 변수를 재정의합니다.

매개변수 형식은 variables[key]=value이며, 예를 들어:

curl --request POST \
     --form token=TOKEN \
     --form ref=main \
     --form "variables[UPLOAD_TO_S3]=true" \
     "https://gitlab.example.com/api/v4/projects/123456/trigger/pipeline"

트리거된 파이프라인의 CI/CD 변수는 각 잡의 페이지에 표시되지만 Owner 및 Maintainer 권한이 있는 사용자만 값을 볼 수 있습니다.

파이프라인 동작을 제어하기 위한 인풋 사용은 CI/CD 변수보다 향상된 보안과 유연성을 제공합니다.

API 호출에 파이프라인 인풋 전달#

트리거 API 호출에서 파이프라인 인풋을 전달할 수 있습니다. 인풋은 내장된 유효성 검사 및 문서화를 통해 파이프라인을 매개변수화하는 구조화된 방법을 제공합니다.

매개변수 형식은 inputs[name]=value이며, 예를 들어:

curl --request POST \
     --form token=TOKEN \
     --form ref=main \
     --form "inputs[environment]=production" \
     "https://gitlab.example.com/api/v4/projects/123456/trigger/pipeline"

인풋 값은 파이프라인의 spec:inputs 섹션에 정의된 유형 및 제약 조건에 따라 유효성이 검사됩니다:

spec:
  inputs:
    environment:
      type: string
      description: "Deployment environment"
      options: [dev, staging, production]
      default: dev

파이프라인 트리거 토큰 취소#

파이프라인 트리거 토큰을 취소하려면:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Pipeline trigger tokens를 확장합니다.
4. 취소할 트리거 토큰 왼쪽에서 Revoke ([remove])를 선택합니다.

취소된 트리거 토큰은 다시 추가할 수 없습니다.

트리거된 파이프라인에서 실행할 CI/CD 잡 구성#

트리거된 파이프라인에서 잡을 실행할 시점을 구성하려면 다음을 수행할 수 있습니다:

• $CI_PIPELINE_SOURCE 사전 정의된 CI/CD 변수를 사용하여 rules를 사용합니다.
• only/except 키워드를 사용하지만 rules가 선호하는 키워드입니다.

또한 $CI_PIPELINE_TRIGGERED 사전 정의된 CI/CD 변수는 파이프라인 트리거 토큰으로 트리거된 파이프라인에서 true로 설정됩니다.

사용된 파이프라인 트리거 토큰 확인#

단일 잡 페이지를 방문하여 잡이 실행되도록 만든 파이프라인 트리거 토큰을 확인할 수 있습니다. 트리거 토큰의 일부가 Job details 아래의 오른쪽 사이드바에 표시됩니다.

트리거 토큰으로 트리거된 파이프라인에서 잡은 Build > Jobs에서 triggered로 표시됩니다.

문제 해결#

웹훅으로 파이프라인을 트리거할 때 403 Forbidden#

웹훅으로 파이프라인을 트리거하면 API가 {"message":"403 Forbidden"} 응답을 반환할 수 있습니다. 트리거 루프를 방지하려면 파이프라인 이벤트를 사용하여 파이프라인을 트리거하지 마세요.

파이프라인을 트리거할 때 404 Not Found#

파이프라인을 트리거할 때 {"message":"404 Not Found"} 응답은 파이프라인 트리거 토큰 대신 개인 접근 토큰을 사용하는 경우 발생할 수 있습니다. 새 트리거 토큰을 만들고 개인 접근 토큰 대신 사용합니다.

파이프라인을 트리거할 때 {"message":"404 Not Found"} 응답은 GET 요청을 사용하는 경우에도 발생할 수 있습니다. 파이프라인은 POST 요청을 사용해서만 트리거할 수 있습니다.

파이프라인을 트리거할 때 The requested URL returned error: 400#

존재하지 않는 브랜치 이름인 ref를 사용하여 파이프라인을 트리거하려고 하면 GitLab은 The requested URL returned error: 400을 반환합니다.

예를 들어, 기본 브랜치에 다른 이름을 사용하는 프로젝트에서 브랜치 이름으로 실수로 main을 사용할 수 있습니다.

이 오류의 또 다른 가능한 원인은 CI_PIPELINE_SOURCE 값이 trigger일 때 파이프라인 생성을 방지하는 규칙입니다. 예를 들어:

rules:
  - if: $CI_PIPELINE_SOURCE == "trigger"
    when: never

CI_PIPELINE_SOURCE 값이 trigger일 때 파이프라인이 만들어질 수 있는지 확인하기 위해 workflow:rules를 검토합니다.