API로 파이프라인 트리거하기

파이프라인을 꼭 웹 UI에서만 눌러서 실행할 수 있는 건 아니에요. API 호출로 특정 브랜치나 태그의 파이프라인을 언제든 트리거할 수 있죠. 외부 도구나 웹훅에서 GitLab 파이프라인을 실행하고 싶을 때 특히 유용한 기능입니다. 이 글에서는 파이프라인 트리거 토큰을 만들고, cURL·CI/CD job·웹훅으로 파이프라인을 트리거하는 방법과 자주 겪는 오류를 설명할게요.

출처: 문서

본문

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

파이프라인 트리거 API 엔드포인트에 API 호출을 보내 특정 브랜치나 태그의 파이프라인을 트리거할 수 있어요.

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

GitLab CI/CD로 마이그레이션하는 경우라면, 다른 제공자(Jenkins나 CircleCI 같은)의 job에서 API 엔드포인트를 호출해 GitLab CI/CD 파이프라인을 트리거할 수 있어요. 예를 들어 Jenkins나 CircleCI에서 마이그레이션하는 경우가 그렇죠.

API로 인증할 때 다음을 사용할 수 있습니다.

파이프라인 트리거 토큰 — 파이프라인 트리거 API 엔드포인트로 브랜치 또는 태그 파이프라인을 트리거할 때 사용해요.
CI/CD job 토큰 — 멀티 프로젝트 파이프라인을 트리거할 때 사용해요.
API 접근 권한이 있는 다른 토큰 — 프로젝트 파이프라인 API 엔드포인트로 새 파이프라인을 만들 때 사용해요.

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

파이프라인 트리거 토큰을 생성하고 이를 이용해 API 호출을 인증하면 브랜치 또는 태그의 파이프라인을 트리거할 수 있어요. 이 토큰은 사용자의 프로젝트 접근 권한과 권한을 대신(impersonate)합니다.

전제 조건:

프로젝트에 대해 Maintainer 또는 Owner 역할이 있어야 해요.

트리거 토큰을 만들려면:

상단 바에서 Search or go to를 선택해 프로젝트를 찾으세요.
왼쪽 사이드바에서 Settings > CI/CD를 선택하세요.
Pipeline trigger tokens를 펼치세요.
Add new token을 선택하세요.
설명을 입력하고 Create pipeline trigger token을 선택하세요.
자신이 만든 모든 트리거의 전체 토큰을 보고 복사할 수 있어요.
다른 프로젝트 멤버가 만든 토큰은 처음 4자만 볼 수 있어요.

공개 프로젝트에 토큰을 평문으로 저장하거나 악의적인 사용자가 접근할 수 있는 방식으로 저장하는 것은 보안 위험입니다. 트리거 토큰이 유출되면 예정에 없는 배포를 강제하거나 CI/CD 변수에 접근을 시도하는 등 악용될 수 있어요. 마스킹된 CI/CD 변수는 트리거 토큰의 보안을 높이는 데 도움이 됩니다. 토큰을 안전하게 보관하는 방법에 대한 자세한 내용은 보안 고려 사항을 참고하세요.

파이프라인 트리거하기

파이프라인 트리거 토큰을 만든 뒤, API에 접근할 수 있는 도구나 웹훅으로 파이프라인을 트리거할 수 있어요.

cURL 사용

파이프라인 트리거 API 엔드포인트에 cURL로 파이프라인을 트리거할 수 있어요. 예를 들어:

멀티라인 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>를 123456 같은 프로젝트 ID로 — 프로젝트 ID는 프로젝트 개요 페이지에 표시돼요.

CI/CD job 사용

파이프라인 트리거 토큰이 있는 CI/CD job을 사용하면 다른 파이프라인이 실행될 때 파이프라인을 트리거할 수 있어요.

예를 들어 프로젝트-A에 태그가 생성되면 프로젝트-B의 main 브랜치에서 파이프라인을 트리거하려면, 프로젝트 A의 .gitlab-ci.yml 파일에 다음 job을 추가하세요.

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는 프로젝트-B의 프로젝트 ID예요. 프로젝트 ID는 프로젝트 개요 페이지에 표시됩니다.
rules는 프로젝트-A에 태그가 추가될 때마다 job이 실행되게 해요.
MY_TRIGGER_TOKEN은 트리거 토큰을 담고 있는 마스킹된 CI/CD 변수예요.

웹훅 사용

다른 프로젝트의 웹훅에서 파이프라인을 트리거하려면 push 및 tag 이벤트에 대해 다음과 같은 웹훅 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로 — 프로젝트 개요 페이지에 표시돼요.
<ref_name>을 main 같은 브랜치 또는 태그 이름으로 — 이 값은 웹훅 페이로드의 ref_name보다 우선해요. 페이로드의 ref는 소스 저장소에서 트리거를 발생시킨 브랜치죠. ref_name에 슬래시가 포함된 경우 URL 인코딩해야 합니다.
<token>을 파이프라인 트리거 토큰으로

웹훅 페이로드 접근

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

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

트리거 API 호출에서 원하는 만큼 CI/CD 변수를 전달할 수 있어요. 다만 입력(inputs)으로 파이프라인 동작 제어를 사용하는 것이 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 변수는 각 job 페이지에 표시되지만, 값을 볼 수 있는 사용자는 Owner와 Maintainer 역할뿐입니다.

입력(inputs)으로 파이프라인 동작을 제어하는 것이 CI/CD 변수보다 보안과 유연성에서 더 좋습니다.

API 호출에서 파이프라인 입력 전달

트리거 API 호출에서 파이프라인 입력을 전달할 수 있어요. 입력(inputs)은 내장된 검증과 문서화로 파이프라인을 구조적으로 파라미터화하는 방법을 제공합니다.

파라미터 형식은 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

파이프라인 트리거 토큰 폐기

파이프라인 트리거 토큰을 폐기하려면:

상단 바에서 Search or go to를 선택해 프로젝트를 찾으세요.
왼쪽 사이드바에서 Settings > CI/CD를 선택하세요.
Pipeline triggers를 펼치세요.
폐기할 트리거 토큰 왼쪽에서 Revoke를 선택하세요.

폐기된 트리거 토큰은 다시 추가할 수 없어요.

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

트리거된 파이프라인에서 job 실행 시점을 구성하려면 다음을 사용할 수 있어요.

$CI_PIPELINE_SOURCE 사전 정의된 CI/CD 변수와 함께 rules 사용
only/except 키워드 사용 — 다만 rules가 권장되는 키워드예요.

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

어떤 파이프라인 트리거 토큰이 사용됐는지 확인

단일 job 페이지를 방문하면 어떤 파이프라인 트리거 토큰이 job을 실행시켰는지 확인할 수 있어요. 트리거 토큰의 일부분이 오른쪽 사이드바의 Job details 아래에 표시됩니다.

트리거 토큰으로 트리거된 파이프라인의 job은 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

workflow:rules를 검토해서 CI_PIPELINE_SOURCE 값이 trigger일 때 파이프라인이 생성될 수 있도록 확인하세요.

더 알아보기 (Learn more)

다운스트림 파이프라인 구성 원리를 알고 싶다면 다운스트림 파이프라인 문서를, 파이프라인 입력을 파라미터로 활용하는 방법은 파이프라인 입력 문서를 참고하세요. API 인증 토큰 종류를 비교하려면 보안 토큰 문서도 함께 보면 좋아요.