GitLab CI/CD 작업 토큰

세부 정보: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, 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 요청은 기본적으로 공개됩니다.
Terraform 계획  

작업 토큰은 프로젝트의 리소스에 액세스할 수 있지만 필요하지 않은 추가 권한을 부여할 수 있습니다. 더 세밀한 액세스 권한을 위해 제안되었습니다.

GitLab CI/CD 작업 토큰 보안

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

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

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

  • 머신을 재사용하는 경우 도커 privileged 모드를 사용하지 않습니다.
  • 작업이 같은 머신에서 실행될 때 shell executor를 사용하지 않습니다.

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

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

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

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

  • 작업 토큰 허용 목록에 프로젝트를 추가해야 합니다.
  • 작업을 트리거하는 사용자가 프로젝트의 구성원이어야 합니다.
  • 사용자는 작업을 수행할 권한을 가져야 합니다.

프로젝트가 공개되거나 내부적이라면 일부 공개적으로 액세스할 수 있는 리소스에 대해 프로젝트의 작업 토큰을 사용하여 액세스할 수 있습니다. 이러한 리소스는 또한 허용 목록에 있는 프로젝트에만 제한될 수 있습니다.

작업 토큰 허용 목록에 프로젝트 추가

작업 토큰 허용 목록에 프로젝트를 추가하여 인증을 위해 작업 토큰을 사용하여 프로젝트의 리소스에 액세스할 수 있습니다. 기본적으로 어떠한 프로젝트의 허용 목록은 해당 프로젝트 자체만 포함됩니다.

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

프로젝트 간 액세스가 필요할 때에만 허용 목록에 프로젝트를 추가하세요.

전제 조건:

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

프로젝트를 허용 목록에 추가하려면 다음을 수행하세요:

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

또한 API를 사용하여 프로젝트를 허용 목록에 추가할 수 있습니다.

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

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

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

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

전제 조건:

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

기능을 프로젝트 멤버만 볼 수 있도록 설정하려면 다음을 수행하세요:

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

어떤 프로젝트든지 귀하의 프로젝트에 액세스할 수 있게 허용

경고: 토큰 액세스 제한 및 허용 목록을 비활성화하는 것은 보안 위험이 됩니다. 악의적인 사용자가 인가되지 않은 프로젝트에서 생성된 파이프라인을 침해할 수 있습니다. 파이프라인이 귀하의 유지자 중 한 명에 의해 생성된 경우 해당 유지자의 작업 토큰을 사용하여 귀하의 프로젝트에 액세스를 시도할 수 있습니다.

이 프로젝트에 대한 제한 으로 설정을 비활성화하면 허용 목록은 무시됩니다. 어떤 프로젝트의 작업에서든 해당 프로젝트에 액세스할 수 있습니다.

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

전제 조건:

  • 프로젝트에 적어도 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 프로토콜이 그룹, 프로젝트 또는 인스턴스 설정에 의해 비활성화되었더라도 작업 토큰을 사용하여 저장소를 복제할 수 있습니다. 하지만 작업 토큰으로 저장소에 푸시할 수는 없습니다. 그러나 이 문제에서 이 동작을 변경하도록 제안하고 있습니다.

프로젝트의 작업 토큰 액세스 제한하기 (deprecated)

참고: 새 프로젝트의 경우 이 프로젝트로부터의 액세스 제한 설정은 기본적으로 비활성화되어 있으며 GitLab 17.0에서 제거 예정입니다. 프로젝트 유지 관리자 또는 소유자는 이 프로젝트로의 액세스 제한 설정을 구성해야 합니다.

프로젝트의 작업 토큰 범위를 관리하기 위해 프로젝트의 작업 토큰 허용 목록을 만들어 사용할 수 있습니다.

기본적으로 허용 목록에는 현재 프로젝트가 포함됩니다. 유지 관리자가 두 프로젝트에 액세스할 수 있는 경우 다른 프로젝트를 추가하거나 삭제할 수 있습니다.

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

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

작업 토큰 범위 구성 (deprecated)

전제 조건:

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

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

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

문제 해결

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

  • 인증되지 않은 Git 복제: 

    $ 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에 액세스 권한 부여 또는 A의 허용 목록에 B 추가.
    • 프로젝트 액세스 제거.
  • 작업이 더 이상 실행 중이지 않거나 지워졌거나 프로젝트가 삭제 진행 중인 경우 CI 작업 토큰이 무효화됩니다.