GitLab CI/CD 작업 토큰

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

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

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

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

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

기능 추가 세부 정보
컨테이너 레지스트리 API 해당 토큰은 작업의 프로젝트의 컨테이너 레지스트리로 범위가 지정됩니다.
컨테이너 레지스트리 $CI_REGISTRY_PASSWORD predefined 변수가 CI/CD 작업 토큰입니다.
배포 API GET 요청은 기본적으로 공개됩니다.
환경 API GET 요청은 기본적으로 공개됩니다.
작업 아티팩트 API GET 요청은 기본적으로 공개됩니다.
작업 API 작업 토큰의 작업을 가져오기 위해.
패키지 레지스트리  
패키지 API GET 요청은 기본적으로 공개됩니다.
파이프라인 트리거 API를 사용하여 token= 매개변수로 다중 프로젝트 파이프라인을 트리거.
파이프라인 API 파이프라인 메타데이터를 업데이트하기 위해.
릴리스 링크 API  
릴리스 API GET 요청은 기본적으로 공개됩니다.
Terraform Plan  

작업 토큰은 프로젝트의 리소스에 액세스할 수 있지만 필요하지 않은 추가 권한을 제공할 수 있습니다. 데이터 접근 권한을 더 세밀하게 제어하기 위한 제안이 있습니다.

GitLab CI/CD 작업 토큰 보안

작업 토큰이 유출되면 해당 토큰을 사용하여 CI/CD 작업을 트리거한 사용자가 액세스할 수 있는 개인 데이터에 접근하는 데 사용될 수 있습니다. 해당 토큰의 누출이나 남용을 방지하기 위해 GitLab은 다음을 수행합니다:

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

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

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

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

프로젝트에 작업 토큰 액세스 제어하기

프로젝트의 리소스에 대한 작업 토큰 사용을 제어할 수 있습니다.

기본적으로 작업 토큰 액세스는 프로젝트 내의 파이프라인에서 실행되는 CI/CD 작업에만 제한됩니다. 다른 프로젝트가 다른 프로젝트의 파이프라인에서 작업 토큰으로 인증하려면:

  • 해당 프로젝트를 작업 토큰 허용 디렉터리에 추가해야 합니다.
  • 작업을 트리거한 사용자가 현재 프로젝트의 멤버여야 합니다.
  • 사용자는 해당 작업을 수행하는 데 필요한 권한을 가져야 합니다.

프로젝트가 공개 또는 내부적으로 소유되어 있는 경우, 허용 디렉터리에 없어도 일부 공개적으로 접근 가능한 리소스에 대한 액세스는 다른 프로젝트의 작업 토큰을 통해서 얻을 수 있습니다. 해당 리소스 역시 허용 디렉터리에 있는 프로젝트에만 제한될 수 있습니다.

프로젝트를 작업 토큰 허용 디렉터리에 추가

프로젝트를 작업 토큰 허용 디렉터리에 추가하여 작업 토큰을 사용하여 인증하고 프로젝트 리소스에 액세스할 수 있습니다. 기본적으로 어떤 프로젝트의 허용 디렉터리에도 해당 프로젝트만 포함됩니다.

예를 들어, 프로젝트 A는 프로젝트 A의 허용 디렉터리에 프로젝트 B를 추가할 수 있습니다. 이제 프로젝트 B(허용된 프로젝트)의 CI/CD 작업은 프로젝트 A에 대한 API 호출을 인증하기 위해 CI/CD 작업 토큰을 사용할 수 있습니다.

교차 프로젝트 액세스가 필요한 경우에만 프로젝트를 허용 디렉터리에 추가하세요.

사전 조건:

  • 현재 프로젝트에서 최소한 Maintainer 역할이 있어야 합니다. 허용된 프로젝트가 내부적 또는 비공개인 경우 해당 프로젝트에서 최소한 Guest 역할이 있어야 합니다.
  • 허용 디렉터리에 추가된 프로젝트는 200개를 초과해서는 안 됩니다.

허용 디렉터리에 프로젝트를 추가하려면:

  1. 좌측 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > CI/CD를 선택합니다.
  3. 토큰 액세스를 확장합니다.
  4. 해당 프로젝트로의 액세스 제한 토글이 활성화되어 있는지 확인합니다. 새 프로젝트에서는 기본적으로 이 기능이 활성화됩니다. 보안상의 이유로 프로젝트 관리자 또는 소유자는 이러한 설정을 항상 활성화해야 합니다.
  5. 프로젝트 추가를 선택합니다.
  6. 허용 디렉터리에 추가할 프로젝트의 경로를 입력하고 프로젝트 추가를 선택합니다.

또한 API를 통해 프로젝트를 허용 디렉터리에 추가할 수도 있습니다.

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

허용 디렉터리에 없는 프로젝트는 작업 토큰을 사용하여 다음을 수행할 수 있습니다:

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

각 기능을 프로젝트 구성원만 볼 수 있도록 설정하여, 이러한 작업에 대한 액세스를 허용디렉터리에 있는 프로젝트에만 제한할 수 있습니다.

필수 사항:

  • 프로젝트의 유지보수자(Maintainer) 역할이 있어야 합니다.

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

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

아무 프로젝트라도 귀하의 프로젝트에 액세스 허용

caution
토큰 액세스 제한 및 허용디렉터리을 비활성화하는 것은 보안 위험입니다. 악의적 사용자가 무단으로 만든 프로젝트의 파이프라인을 침해하려 할 수 있습니다. 파이프라인을 유지보수자(Maintainer) 중 하나가 만들었을 경우, 작업 토큰을 사용하여 귀하의 프로젝트에 액세스하려 할 수 있습니다.

이 프로젝트로의 액세스 제한 설정이 비활성화되면 허용디렉터리이 무시됩니다. 파이프라인을 유발한 사용자가 귀하의 프로젝트에 액세스할 권한이 있다면, 아무 프로젝트에서의 작업이 귀하의 프로젝트에 액세스할 수 있습니다.

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

필수 사항:

  • 프로젝트의 유지보수자(Maintainer) 역할이 최소한 있어야 합니다.

작업 토큰 범위 허용디렉터리 비활성화하는 방법:

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

또한 GraphQL (inboundJobTokenScopeEnabled) 및 REST API로 설정을 활성화하거나 비활성화할 수 있습니다.

작업 토큰을 사용하여 비공개 프로젝트의 리포지터리 복제 제한

CI/CD 작업에서 작업 토큰을 사용하여 비공개 프로젝트의 리포지터리를 인증 및 복제할 수 있습니다. 예를 들면: 

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

이 작업 토큰을 사용하여 HTTPS 프로토콜이 그룹, 프로젝트 또는 인스턴스 설정에 의해 비활성화된 경우에도 리포지터리를 복제할 수 있습니다. 그러나 작업 토큰을 사용하여 리포지터리로 푸시할 수는 없으며, issue 389060에서 이 동작을 변경하도록 제안하고 있습니다.

귀하의 프로젝트의 작업 토큰 액세스 제한 (사용 중지됨)

note
새 프로젝트에 대해 이 프로젝트로의 액세스 제한 설정은 기본적으로 비활성화되어 있으며, GitLab 17.0에서 제거 예정입니다. 프로젝트 유지보수자 또는 소유자는 대신 이 프로젝트에 대한 액세스 제한 설정을 구성해야 합니다.

프로젝트의 작업 토큰 범위에 대한 허용디렉터리을 만들어 프로젝트의 작업 토큰 범위를 제어합니다. 기본적으로 허용디렉터리에는 현재 프로젝트가 포함됩니다. 다른 프로젝트는 해당 프로젝트에 액세스 권한이 있는 유지보수자에 의해 추가 및 제거될 수 있습니다.

이 설정이 비활성화된 경우, 모든 프로젝트가 허용디렉터리에 있는 것으로 간주되고 작업 토큰은 사용자의 액세스 권한에만 제한됩니다.

예를 들어, 설정이 활성화된 경우 프로젝트 A의 파이프라인에서 프로젝트 B로의 액세스를 필요로 하는 작업이 있다면 프로젝트 B를 A의 허용디렉터리에 추가해야 합니다.

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

필수 사항:

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

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

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

문제 해결

CI 작업 토큰의 실패는 일반적으로 404 Not Found와 유사한 응답으로 나타납니다:

  • 권한 없는 Git 복제: 

    $ git clone https://gitlab-ci-token:$CI_JOB_TOKEN@gitlab.com/fabiopitino/test2.git
  
'test2'로 복제 중...
remote: 찾고 있던 프로젝트를 찾을 수 없거나 보기 위한 권한이 없습니다.
fatal: 리포지터리 'https://gitlab-ci-token:[MASKED]@gitlab.com/<namespace>/<project>.git/'을(를) 찾을 수 없음

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

    $ 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
gitlab.com (gitlab.com)를 찾는 중... 172.65.251.78, 2606:4700:90:0:f22e:fbec:5bed:a9b9
gitlab.com (gitlab.com)|172.65.251.78|:443... 연결됨.
HTTP 요청 보냄, 응답 대기 중...
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 예제 변경이 있습니다.
  • Bash 및 cURL을 사용하여 이 주석에서:
    • 내부 토큰 액세스 범위를 활성화하고
    • 프로젝트 B로부터 프로젝트 A에 액세스 권한을 부여하거나 A의 허용디렉터리에 B를 추가하는 방법을 보여줍니다.
    • 액세스를 제거합니다.
  • 작업이 더 이상 실행 중이 아니거나 지워졌거나 프로젝트가 삭제되는 과정에 있는 경우 CI 작업 토큰이 무효화됩니다.