GitLab CI/CD 작업 토큰

Tier: Free, Premium, Ultimate Offering: GitLab.com, 자체관리, GitLab Dedicated

CI/CD 파이프라인 작업이 실행되기 직전에, GitLab은 고유한 토큰을 생성하여 이를 CI_JOB_TOKEN 사전 정의 변수로 작업에서 사용할 수 있게 합니다. 이 토큰은 작업이 실행되는 동안에만 유효합니다. 작업이 완료된 후에는 토큰 액세스가 취소되며 더 이상 해당 토큰을 사용할 수 없습니다.

CI/CD 작업 토큰을 사용하여 실행 중인 작업으로부터 특정 GitLab 기능을 인증할 수 있습니다. 이 토큰은 파이프라인을 트리거한 사용자와 동일한 액세스 수준을 받지만, 개인 액세스 토큰보다는 더 적은 리소스에 액세스할 수 있습니다. 사용자는 커밋을 푸시하거나 수동 작업을 트리거하거나 예약된 파이프라인의 소유자가 되는 등의 작업으로 작업을 실행할 수 있습니다. 이 사용자는 필요한 권한을 갖는 역할을 가져야 합니다.

작업 토큰을 사용하여 GitLab에 인증하여 다른 그룹이나 프로젝트의 리소스(대상 프로젝트)에 액세스할 수 있습니다. 기본적으로 작업 토큰의 그룹이나 프로젝트는 대상 프로젝트의 허용 목록에 추가되어야 합니다.

프로젝트가 공개 또는 내부적인 경우, 허용 목록에 없어도 일부 기능에 액세스할 수 있습니다. 예를 들어, 해당 프로젝트의 공개 파이프라인에서 아티팩트를 가져올 수 있습니다. 이 액세스는 또한 제한될 수 있습니다.

기능 추가 정보
컨테이너 레지스트리 API 해당 작업의 프로젝트의 컨테이너 레지스트리로 제한됩니다.
컨테이너 레지스트리 $CI_REGISTRY_PASSWORD 사전 정의 변수가 CI/CD 작업 토큰입니다.
배포 API GET 요청은 기본적으로 공개됩니다.
환경 API GET 요청은 기본적으로 공개됩니다.
작업 아티팩트 API GET 요청은 기본적으로 공개됩니다.
작업 API 작업 토큰의 작업을 얻기 위해 사용합니다.
패키지 레지스트리  
패키지 API GET 요청은 기본적으로 공개됩니다.
파이프라인 트리거 token= 매개변수와 함께 사용하여 다중 프로젝트 파이프라인을 트리거합니다.
파이프라인 API 파이프라인 메타데이터를 업데이트하기 위해 사용합니다.
릴리스 링크 API  
릴리스 API GET 요청은 기본적으로 공개됩니다.
보안 파일 download-secure-files 도구는 기본적으로 CI/CD 작업 토큰으로 인증합니다.
테라폼 플랜  

작업 토큰은 프로젝트 리소스에 대한 액세스를 구성할 필요 없이 사용할 수 있지만, 필요하지 않은 추가 권한을 부여할 수도 있습니다. 액세스 권한을 더 세밀하게 제어하기 위한 제안서가 있습니다.

GitLab CI/CD 작업 토큰 보안

작업 토큰이 유출되면, 해당 CI/CD 작업을 트리거한 사용자가 액세스할 수 있는 개인 데이터에 잠재적으로 액세스할 수 있습니다. 이러한 토큰이 누출되거나 오용될 수 있는 것을 방지하기 위해 GitLab은:

  • 작업 로그에서 작업 토큰을 마스킹합니다.
  • 작업이 실행될 때에만 작업 토큰에 대한 권한을 부여합니다.

또한 런너를 안전하게 구성해야 합니다:

  • 머신을 재사용하는 경우 Docker privileged 모드를 사용하지 않습니다.
  • 작업이 동일한 머신에서 실행될 때, shell executor를 사용하지 않습니다.

안전하지 않은 GitLab 러너 구성은 다른 작업에서 토큰을 도용할 수 있는 위험을 증가시킵니다.

프로젝트의 작업 토큰 액세스 제어

프로젝트의 리소스에 작업 토큰을 사용하여 인증하여 엑세스할 수 있는 그룹이나 프로젝트를 제어할 수 있습니다.

기본적으로 작업 토큰 액세스는 해당 프로젝트의 파이프라인에서 실행되는 CI/CD 작업에만 제한됩니다. 다른 그룹이나 프로젝트가 다른 프로젝트의 파이프라인에서 작업 토큰을 사용하여 인증하도록 허용하려면:

프로젝트가 공개 또는 내부적일 경우, 일부 공개적으로 액세스 가능한 리소스는 해당 프로젝트에서의 작업 토큰을 사용할 수 있습니다. 이러한 리소스는 또한 허용 목록에 있는 프로젝트에만 제한될 수 있습니다.

그룹 또는 프로젝트를 작업 토큰 허용 목록에 추가

프로젝트의 리소스에 대한 액세스를 허용하기 위해 그룹 또는 프로젝트를 작업 토큰 허용 목록에 추가할 수 있습니다. 기본적으로 어떤 프로젝트의 허용 목록에는 해당 프로젝트 자체만 포함됩니다.

프로젝트를 허용 목록에 추가하는 작업은 허용된 프로젝트의 구성원이 추가적인 권한을 부여하지 않습니다. 그들은 프로젝트의 리소스에 액세스하기 위해 허용 목록에 있는 프로젝트에서 작업 토큰을 사용할 수 있도록 추가적으로 권한을 가지고 있어야 합니다.

예를 들어, 프로젝트 A에서 프로젝트 A의 허용 목록에 프로젝트 B를 추가할 수 있습니다. 이제 프로젝트 B(허용된 프로젝트)의 CI/CD 작업은 프로젝트 A의 리소스에 인증하기 위해 CI/CD 작업 토큰을 사용할 수 있습니다.

교차 프로젝트 액세스가 필요한 경우에만 그룹 또는 프로젝트를 허용 목록에 추가합니다.

필수 조건:

  • 현재 프로젝트의 유지자 권한을 가져야 합니다. 허용된 프로젝트가 내부적이거나 비공개인 경우, 해당 프로젝트에서 최소한 게스트 권한을 가져야 합니다.
  • 허용 목록에 추가된 그룹 및 프로젝트가 최대 200개 이상이어서는 안 됩니다.

허용 목록에 그룹 또는 프로젝트를 추가하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > CI/CD를 선택합니다.
  3. 작업 토큰 권한을 확장합니다.
  4. 이 프로젝트에 대한 액세스 제한 토글이 활성화되어 있는지 확인합니다. 새 프로젝트에서는 기본적으로 이 기능이 비활성화되어 있습니다. 이 설정을 비활성화하는 것은 보안 위험이 있으므로 프로젝트 유지자 또는 소유자는 항상 이 설정을 활성화해야 합니다.
  5. 그룹 또는 프로젝트 추가를 선택합니다.
  6. 허용 목록에 추가할 그룹 또는 프로젝트의 경로를 입력하고 프로젝트 추가를 선택합니다.

또한 API로 그룹 또는 프로젝트를 허용 목록에 추가할 수 있습니다.

공개 또는 내부 프로젝트를 위한 작업 토큰 범위 제한

허용 목록에 없는 프로젝트는 작업 토큰을 사용하여 공개 또는 내부 프로젝트와 인증할 수 있습니다:

  • 아티팩트 가져오기
  • 컨테이너 레지스트리 접근
  • 패키지 레지스트리 접근
  • 릴리스, 배포 및 환경 접근

이러한 작업에 대한 액세스를 허용 목록에 있는 프로젝트에만 제한하려면 각 기능을 프로젝트 멤버만 볼 수 있도록 설정하면 됩니다.

필수 사항:

  • 프로젝트의 Maintainer 역할이 있어야 합니다.

기능을 프로젝트 멤버만 볼 수 있도록 설정하는 방법:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 일반을 선택합니다.
  3. 가시성, 프로젝트 기능, 권한을 확장합니다.
  4. 원하는 기능에 대해 가시성을 프로젝트 멤버만으로 설정합니다.
    • 아티팩트 가져오기의 기능은 CI/CD 가시성 설정으로 제어됩니다.
  5. 변경 사항 저장을 선택합니다.

프로젝트에 대한 액세스 허용

  • GitLab 16.3에서 프로젝트로의 액세스 제한으로 이름이 변경되었습니다.
  • GitLab 17.2에서 토큰 액세스 설정이 작업 토큰 권한으로 이름이 변경되었습니다.

경고: 토큰 액세스 제한 및 허용 목록을 해제하는 것은 보안 위험이 됩니다. 악의적인 사용자가 허가되지 않은 프로젝트에서 생성된 파이프라인을 탐침할 수 있습니다. 만약 파이프라인이 당신의 관리자 중 한 명에 의해 생성되었다면, 작업 토큰은 당신의 프로젝트에 액세스하려는 시도로 사용될 수 있습니다.

프로젝트로의 액세스 제한 설정을 해제하면 허용 목록이 무시됩니다. 프로젝트에 액세스할 수 있는 사용자가 파이프라인을 트리거하는 경우에 작업 토큰입니다.

이 설정을 테스트나 유사한 이유로만 비활성화해야 하며, 가능한 빨리 다시 활성화해야 합니다.

필수 사항:

  • 프로젝트의 적어도 Maintainer 역할이 있어야 합니다.

작업 토큰 범위 허용 목록을 해제하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > CI/CD를 선택합니다.
  3. 작업 토큰 권한을 확장합니다.
  4. 프로젝트로의 액세스 제한을 해제로 전환합니다. 새 프로젝트의 경우 기본적으로 활성화됨.

GraphQL (inboundJobTokenScopeEnabled) 및 REST API를 사용하여 이 설정을 활성화 및 비활성화할 수도 있습니다.

프로젝트 저장소로의 Git push

  • GitLab 17.2에서 도입되었습니다. 및 플래그인 allow_push_repository_for_job_token로 명명되었습니다. 기본적으로 비활성화됨.
  • GitLab 17.2에서 토큰 액세스 설정이 작업 토큰 권한으로 이름이 변경되었습니다.

플래그: 이 기능의 가용성은 플래그로 제어됩니다. 자세한 내용은 이력을 참조하십시오. 이 기능은 테스트용으로 제공되지만, 제품으로 사용하기에는 아직 준비되지 않았습니다.

경고: CI/CD 작업 토큰을 사용하여 프로젝트 저장소로 푸시하는 것은 아직 개발 중이며 아직 성능에 최적화되지 않았습니다. 이 기능을 테스트용으로 활성화한 경우, “푸시” 파이프라인의 무한 루프를 방지하기 위해 철저히 테스트하고 유효성 검사 조치를 시행해야 합니다.

작업 토큰으로 인증 된 Git 푸시 요청을 허용할 수 있습니다. 활성화되면 허용되는 액세스는 프로젝트의 파이프라인에서 실행되는 CI/CD 작업에서 생성된 토큰에 대해서만 허용됩니다. 이 권한은 기본적으로 비활성화됩니다.

필수 사항:

  • 프로젝트의 적어도 Maintainer 역할이 있어야 합니다.

프로젝트의 저장소로 작업 토큰에서 생성된 작업 토큰에게 푸시할 수 있는 권한을 부여하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > CI/CD를 선택합니다.
  3. 작업 토큰 권한을 확장합니다.
  4. 권한 섹션에서 저장소로의 Git 푸시 요청 허용을 선택합니다.

작업 토큰은 작업을 시작한 사용자와 동일한 액세스 권한을 갖습니다. 허용 목록의 다른 프로젝트 또는 그룹의 작업 토큰은 당신의 프로젝트의 저장소로 푸시할 수 없습니다.

또한 REST API의 ci_push_repository_for_job_token_allowed 매개변수를 사용하여 이 설정을 제어할 수도 있습니다.

작업 토큰 사용

비공개 프로젝트의 저장소를 git clone하는 경우

작업 토큰을 사용하여 CI/CD 작업에서 비공개 프로젝트의 저장소를 인증하고 복제할 수 있습니다. 사용자로 gitlab-ci-token을, 작업 토큰의 값을 비밀번호로 사용합니다. 예: 

git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com/<namespace>/<project>

HTTPS 프로토콜이 그룹, 프로젝트 또는 인스턴스 설정에서 비활성화된 경우에도 작업 토큰을 사용하여 저장소로 복제할 수 있습니다. 하지만 작업 토큰으로 저장소에 푸시할 수는 없으며, issue 389060에서 이 동작을 변경할 것으로 제안됩니다.

REST API 요청을 인증하는 경우

작업 토큰을 사용하여 허용된 REST API 엔드포인트의 요청을 인증할 수 있습니다. 예: 

curl --verbose --request POST --form "token=$CI_JOB_TOKEN" --form ref=master "https://gitlab.com/api/v4/projects/1234/trigger/pipeline"

또한 요청에서 작업 토큰을 전달하는 여러 유효한 방법이 있습니다:

  • --form "token=$CI_JOB_TOKEN"
  • --header "JOB-TOKEN: $CI_JOB_TOKEN"
  • --data "job_token=$CI_JOB_TOKEN"

프로젝트의 작업 토큰 액세스 제한 (사용 중단)

참고: 기본적으로 모든 새 프로젝트에 대해 이 프로젝트에서의 액세스 제한 설정은 비활성화되어 있으며, GitLab 17.0에서 제거 예정되었습니다. 프로젝트 관리자 또는 소유자는 대신 이 프로젝트로의 액세스 제한을 구성해야 합니다.

프로젝트의 작업 토큰 범위를 제어하려면 프로젝트의 작업 토큰에 액세스할 수 있는 프로젝트의 허용 목록을 만들어야 합니다.

기본적으로 허용 목록에는 현재 프로젝트가 포함됩니다. 다른 프로젝트는 액세스 권한이 있는 관리자가 두 프로젝트에 모두 액세스할 수 있도록 추가하거나 제거할 수 있습니다.

이 설정이 비활성화된 경우 모든 프로젝트가 허용 목록에 포함되며, 작업 토큰은 사용자의 액세스 권한에만 국한됩니다.

예를 들어, 설정이 활성화된 경우 프로젝트 A의 파이프라인 작업은 CI_JOB_TOKEN 범위가 프로젝트 A로 제한됩니다. 작업이 프로젝트 B에 API 요청을 하려는 경우 B를 A의 허용 목록에 추가해야 합니다.

작업 토큰 범위 구성 (사용 중단)

전제 조건:

  • 토큰 범위에 추가된 프로젝트 수가 200개를 초과하지 않아야 합니다.

작업 토큰 범위를 구성하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > CI/CD를 선택합니다.
  3. 작업 토큰 권한을 확장합니다.
  4. 이 프로젝트에서의 액세스 제한을 활성화하도록 토글합니다.
  5. 선택 사항. 기존 프로젝트를 토큰 액세스 범위에 추가합니다. 프로젝트를 추가하는 사용자는 두 프로젝트에 모두 Maintainer 역할을 가져야 합니다.

문제 해결

CI 작업 토큰 실패는 보통 404 Not Found와 유사한 응답으로 표시됩니다:

  • 권한 없는 Git clone: 

    $ git clone https://gitlab-ci-token:$CI_JOB_TOKEN@gitlab.com/fabiopitino/test2.git

Cloning into 'test2'...
remote: The project you were looking for could not be found or you don't have permission to view it.
fatal: repository 'https://gitlab-ci-token:[MASKED]@gitlab.com/<namespace>/<project>.git/' not found

  • 권한 없는 패키지 다운로드: 

    $ wget --header="JOB-TOKEN: $CI_JOB_TOKEN" ${CI_API_V4_URL}/projects/1234/packages/generic/my_package/0.0.1/file.txt

--2021-09-23 11:00:13--  https://gitlab.com/api/v4/projects/1234/packages/generic/my_package/0.0.1/file.txt
Resolving gitlab.com (gitlab.com)... 172.65.251.78, 2606:4700:90:0:f22e:fbec:5bed:a9b9
Connecting to gitlab.com (gitlab.com)|172.65.251.78|:443... connected.
HTTP request sent, awaiting response... 404 Not Found
2021-09-23 11:00:13 ERROR 404: Not Found.

  • 권한 없는 API 요청: 

    $ curl --verbose --request POST --form "token=$CI_JOB_TOKEN" --form ref=master "https://gitlab.com/api/v4/projects/1234/trigger/pipeline"

< HTTP/2 404
< date: Thu, 23 Sep 2021 11:00:12 GMT
{"message":"404 Not Found"}
< content-type: application/json

CI/CD 작업 토큰 인증 문제 해결 중에 주의할 점:

  • 프로젝트 당 범위 설정을 토글할 수 있는 GraphQL 예제 뮤테이션이 있습니다.
  • 이 코멘트는 GraphQL을 Bash 및 cURL로 사용하여 다음을 수행하는 방법을 보여줍니다:
    • 입받는 토큰 액세스 범위를 활성화합니다.
    • 프로젝트 A로부터 프로젝트 B에 액세스 권한을 부여하거나 B를 A의 허용 목록에 추가합니다.
    • 프로젝트 액세스를 제거합니다.
  • 작업이 더 이상 실행되지 않았거나 지워졌거나 프로젝트가 삭제 진행 중인 경우 CI 작업 토큰이 무효화됩니다.