API를 사용하여 파이프라인 트리거하기
특정 브랜치 또는 태그를 위해 파이프라인을 트리거하려면 파이프라인 트리거 API 엔드포인트를 사용할 수 있습니다.
만약 GitLab CI/CD로 이전하는 중이라면, 다른 제공업체의 작업에서 API 엔드포인트를 호출하여 GitLab CI/CD 파이프라인을 트리거할 수 있습니다. 예를 들어 Jenkins 또는 CircleCI에서의 마이그레이션 중인 경우입니다.
API로 인증할 때 사용할 수 있는 것들:
- 파이프라인 트리거 토큰을 사용하여 브랜치 또는 태그 파이프라인을 트리거합니다.
- CI/CD 작업 토큰을 사용하여 다중 프로젝트 파이프라인을 트리거합니다.
- 개인 액세스 토큰도 사용할 수 있습니다.
파이프라인 트리거 토큰 생성
파이프라인 트리거 토큰을 생성하고 이를 사용하여 브랜치 또는 태그의 파이프라인을 트리거할 수 있습니다. 이 토큰은 사용자의 프로젝트 액세스 및 권한을 흉내냅니다.
전제 조건:
- 프로젝트의 유지보수자 역할을 적어도 가지고 있어야 합니다.
트리거 토큰을 만들려면:
- 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
- 설정 > CI/CD를 선택합니다.
- 파이프라인 트리거 토큰을 확장합니다.
- 새 토큰 추가를 선택합니다.
- 설명을 입력하고 파이프라인 트리거 토큰 생성을 선택합니다.
- 생성한 모든 트리거의 전체 토큰을 볼 수 있고 복사할 수 있습니다.
- 다른 프로젝트 구성원이 만든 토큰에 대해서는 처음 4자만 볼 수 있습니다.
경고: 공개 프로젝트에서 평문으로 토큰을 저장하거나 악의적 사용자가 액세스할 수 있는 방식으로 저장하는 것은 보안 위험이 됩니다. 누설된 트리거 토큰은 예정되지 않은 배포를 강제로 수행하거나 CI/CD 변수에 액세스를 시도하거나 다른 악의적인 용도로 사용될 수 있습니다. 가려진 CI/CD 변수를 사용하여 트리거 토큰의 보안성을 향상할 수 있습니다. 더 많은 보안 정보는 보안 고려 사항을 참조하세요.
파이프라인 트리거
파이프라인 트리거 토큰을 만든 후, 이를 사용하여 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>
는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
이 예에서:
-
1234
는project-B
의 프로젝트 ID입니다. 프로젝트 ID는 프로젝트 개요 페이지에서 확인할 수 있습니다. -
rules
은project-A
에 태그가 추가될 때마다 작업을 실행하도록 합니다. -
MY_TRIGGER_TOKEN
은 트리거 토큰이 포함된 가려진 CI/CD 변수입니다.
웹훅 사용
다른 프로젝트의 웹훅에서 파이프라인을 실행하려면 다음과 같은 웹훅 URL을 사용하십시오. 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로 바꿉니다. 프로젝트 ID는 프로젝트 개요 페이지에서 표시됩니다. -
<ref_name>
을 브랜치 또는 태그 이름인main
과 같이 바꿉니다. 이 값은 웹훅 페이로드의ref_name
보다 우선합니다. 페이로드의ref
는 소스 저장소에서 트리거된 브랜치입니다.ref_name
이 슬래시를 포함하는 경우 URL 인코딩해야 합니다. -
<token>
을 파이프라인 트리거 토큰으로 바꿉니다.
웹훅 페이로드 액세스
- GitLab 13.9에서 도입.
- 기능 플래그가 제거됨 (GitLab 13.11).
웹훅을 사용하여 파이프라인을 트리거하면 TRIGGER_PAYLOAD
사전 정의 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 변수는 각 작업 페이지에 표시되지만 값은 소유자 및 유지 관리자 역할을 갖는 사용자만 볼 수 있습니다.
파이프라인 트리거 토큰 폐기
파이프라인 트리거 토큰을 폐기하려면:
- 왼쪽 사이드바에서 찾거나 이동하여를 선택하고 프로젝트를 찾습니다.
- 설정 > CI/CD를 선택합니다.
- 파이프라인 트리거를 확장합니다.
- 폐기하려는 트리거 토큰 왼쪽에 폐기()를 선택합니다.
폐기된 트리거 토큰은 다시 추가할 수 없습니다.
트리거된 파이프라인에서 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
로 설정됩니다.
어떤 파이프라인 트리거 토큰이 사용되었는지 확인
작업을 실행시킨 파이프라인 트리거 토큰을 확인하려면 개별 작업 페이지를 방문할 수 있습니다. 페이지의 오른쪽 아래에서 작업 세부 정보 아래에 트리거 토큰의 일부가 표시됩니다:
트리거 토큰으로 트리거된 파이프라인에서는 작업이 Build > 작업에서 triggered
로 표시됩니다.
문제 해결
웹훅으로 파이프라인을 트리거할 때 403 Forbidden
오류
웹훅으로 파이프라인을 트리거하면 API에서 {"message":"403 Forbidden"}
응답이 반환될 수 있습니다.
트리거 루프를 피하려면 파이프라인 이벤트를 사용하여 파이프라인을 트리거하지 마십시오.
파이프라인을 트리거할 때 404 Not Found
오류
파이프라인을 트리거할 때 {"message":"404 Not Found"}
라는 응답은 개인 액세스 토큰 대신에 파이프라인 트리거 토큰을 사용했을 때 발생할 수 있습니다. 대신 새로운 트리거 토큰을 생성하고 개인 액세스 토큰 대신 사용하세요.
파이프라인을 트리거할 때 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
을 검토하세요.