API를 사용하여 파이프라인 트리거하기

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

특정 브랜치 또는 태그로 파이프라인을 트리거하려면 API 호출을 사용할 수 있습니다. pipeline triggers API endpoint을(를) 사용하세요.

만약 GitLab CI/CD로 마이그레이션 중이라면, 다른 제공자의 작업에서 API 엔드포인트를 호출하여 GitLab CI/CD 파이프라인을 트리거할 수 있습니다. 예를 들어, Jenkins 또는 CircleCI에서의 마이그레이션의 일환으로.

API와 인증할 때 다음을 사용할 수 있습니다:

파이프라인 트리거 토큰 생성

파이프라인 트리거 토큰을 생성하고 이를 사용하여 브랜치 또는 태그에 대한 파이프라인을 트리거할 수 있습니다. 이 토큰은 사용자의 프로젝트 액세스 및 권한을 가장합니다.

사전 요구 사항:

  • 프로젝트의 유지자 역할을 적어도 가져야 합니다.

트리거 토큰을 만들려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > CI/CD를 선택합니다.
  3. 파이프라인 트리거 토큰을 확장합니다.
  4. 새 토큰 추가를 선택합니다.
  5. 설명을 입력하고 파이프라인 트리거 토큰 생성을 선택합니다.
    • 생성한 모든 트리거에 대한 전체 토큰을 볼 수도 복사할 수도 있습니다.
    • 다른 프로젝트 구성원이 만든 토큰의 처음 4자만 볼 수 있습니다.
caution
공개 프로젝트에 텍스트로 된 토큰을 저장하거나, 악의적 사용자가 액세스할 수 있는 방식으로 저장하는 것은 보안 위험입니다. 유출된 트리거 토큰은 예정되지 않은 배포를 강제하거나 CI/CD 변수에 액세스를 시도하거나 다른 악의적인 용도에 사용될 수 있습니다. 마스크 처리된 CI/CD 변수들을 사용하여 트리거 토큰의 보안성을 높일 수 있습니다. 토큰을 안전하게 보관하는 데 관련 정보는 보안 고려 사항을 참조하세요.

파이프라인 트리거하기

파이프라인 트리거 토큰을 생성한 후, 이를 사용하여 API에 액세스할 수 있는 도구나 웹훅을 사용하여 파이프라인을 트리거할 수 있습니다.

cURL 사용

cURL을 사용하여 파이프라인을 트리거할 수 있습니다. 예를 들어 다음처럼 멀티라인 cURL 명령을 사용합니다: 

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

또는 쿼리 문자열에 <token>와 <ref_name>을 전달하는 cURL을 사용할 수 있습니다. 

  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>는 123456과 같은 프로젝트 ID로 대체합니다. 프로젝트 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 "https://gitlab.example.com/api/v4/projects/123456/trigger/pipeline"'
  rules:
    - if: $CI_COMMIT_TAG
  environment: production

이 예에서:

웹훅 사용

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

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

다음으로 대체하세요:

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

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

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

트리거 API 호출에서 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 변수는 각 작업 페이지에 표시되지만, 소유자 및 유지 관리자 역할을 가진 사용자만 해당 값들을 볼 수 있습니다.

UI에서 작업 변수

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

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

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > CI/CD를 선택합니다.
  3. 파이프라인 트리거를 확장합니다.
  4. 취소하려는 트리거 토큰 왼쪽에서 취소를 선택합니다 ().

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

트리거된 파이프라인에서 CI/CD 작업 구성

트리거된 파이프라인에서 작업을 실행할 때 작업을 실행하는 시기를 구성하려면 다음을 수행할 수 있습니다:

  • $CI_PIPELINE_SOURCE 미리 정의된 CI/CD 변수와 함께 rules를 사용합니다.
  • only/except 키워드를 사용합니다. rules 키워드를 사용하는 것이 좋습니다.
$CI_PIPELINE_SOURCE 값 only/except 키워드 트리거 방법
trigger triggers 파이프라인 트리거 API를 사용하여 트리거된 파이프라인에서 트리거 토큰을 사용하여 트리거됨.
pipeline pipelines 파이프라인 트리거 API를 사용하여 트리거된 다중 프로젝트 파이프라인에서 $CI_JOB_TOKEN을 사용하거나, CI/CD 구성 파일에서 trigger 키워드를 사용하여 트리거됨.

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

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

작업이 실행되도록 한 파이프라인 트리거 토큰을 확인하려면, 해당 단일 작업 페이지를 방문하여 확인할 수 있습니다. 작업 세부 정보 아래 페이지 오른쪽에 트리거 토큰의 일부가 표시됩니다:

단일 작업 페이지에서 트리거 표시

트리거 토큰을 사용하여 트리거된 파이프라인에서 작업은 빌드 > 작업에서 트리거됨으로 표시됩니다.

문제 해결

웹훅을 사용하여 파이프라인을 트리거했을 때 403 금지됨

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

파이프라인을 트리거할 때 404 찾을 수 없음

파이프라인을 트리거하고 {"message":"404 Not Found"} 응답을 받으면 개인 액세스 토큰 대신에 파이프라인 트리거 토큰을 사용한 것일 수 있습니다. 새로운 트리거 토큰을 생성하고 개인 액세스 토큰 대신 사용하세요.

파이프라인을 트리거시 요청한 URL에서 오류 반환: 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을 검토하세요.