GitLab CI/CD 작업 토큰

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

CI/CD 파이프라인 작업이 실행될 준비가 되면, GitLab은 고유한 토큰을 생성하고 이를 CI_JOB_TOKEN 미리 정의된 변수로 작업에 제공합니다.

토큰은 작업이 실행되는 동안만 유효합니다. 작업이 완료된 후에는 토큰 접근이 취소되며 더 이상 토큰을 사용할 수 없습니다.

CI/CD 작업 토큰을 사용하여 실행 중인 작업에서 특정 GitLab 기능에 인증할 수 있습니다.

토큰은 파이프라인을 트리거한 사용자와 동일한 접근 수준을 가지지만, 개인 접근 토큰보다 적은 자원에 접근할 수 있습니다. 사용자는 커밋을 푸시하거나, 수동 작업을 트리거하거나, 예약된 파이프라인의 소유자가 되는 등의 행동으로 작업을 실행할 수 있습니다. 이 사용자는 자원에 접근하기 위해 필요한 권한이 있는 역할을 가지고 있어야 합니다.

작업 토큰을 사용하여 GitLab에 인증하고 다른 그룹이나 프로젝트의 자원(대상 프로젝트)에 접근할 수 있습니다.

기본적으로 작업 토큰의 그룹이나 프로젝트는 대상 프로젝트의 허용 목록에 추가되어야 합니다.

프로젝트가 공개적이거나 내부적이라면, 허용 목록에 없더라도 일부 기능에 접근할 수 있습니다. 예를 들어, 프로젝트의 공개 파이프라인에서 아티팩트를 가져올 수 있습니다. 이 접근은 제한될 수 있습니다.

Feature Additional details
컨테이너 레지스트리 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 작업 토큰으로 인증됩니다.
Terraform 계획  

작업 토큰은 구성 없이 프로젝트의 자원에 접근할 수 있지만, 불필요한 추가 권한을 부여할 수 있습니다. 접근 권한에 대한 보다 세밀한 제어를 위해 기능을 재설계할 제안이 있습니다.

GitLab CI/CD 작업 토큰 보안

작업 토큰이 유출될 경우, CI/CD 작업을 트리거한 사용자에게 접근 가능한 개인 데이터를 액세스하는 데 사용될 수 있습니다. 이 토큰의 유출이나 오용을 방지하기 위해, GitLab은:

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

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

  • 머신이 재사용되는 경우 Docker privileged 모드 사용을 피하세요.
  • 작업이 동일한 머신에서 실행될 때 shell 실행기 사용을 피하세요.

안전하지 않은 GitLab Runner 구성은 다른 작업에서 토큰을 훔칠 위험을 증가시킵니다.

프로젝트에 대한 작업 토큰 접근 제어

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

기본적으로 작업 토큰 접근은 프로젝트 내의 파이프라인에서 실행되는 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 중 한 명에 의해 생성된 경우, 작업 토큰을 사용하여 귀하의 프로젝트에 접근하려고 할 수 있습니다.

이 프로젝트에 대한 접근 제한 설정을 비활성화하면 허용 목록이 무시됩니다.

어떤 프로젝트에서든 작업 토큰을 사용하여 귀하의 프로젝트에 접근할 수 있으며, 파이프라인을 트리거한 사용자가 귀하의 프로젝트에 접근할 권한이 있는 경우 가능합니다.

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

전제 조건:

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

작업 토큰 범위 허용 목록을 비활성화하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > CI/CD를 선택합니다.
  3. 작업 토큰 권한을 확장합니다.
  4. 이 프로젝트에 대한 접근 제한을 비활성화로 전환합니다. 새로운 프로젝트에서는 기본적으로 활성화되어 있습니다.

이 설정을 GraphQL (inboundJobTokenScopeEnabled) 및 REST API로도 활성화 및 비활성화할 수 있습니다.

귀하의 프로젝트 리포지토리에 Git 푸시

플래그: 이 기능의 사용 가능성은 기능 플래그에 의해 제어됩니다.

자세한 내용은 역사 기록을 참조하세요.

이 기능은 테스트를 위해 사용 가능하지만, 실제 사용을 위한 준비가 되지 않았습니다.

경고: CI/CD 작업 토큰으로 인증하여 프로젝트 리포지토리에 푸시하는 것은 여전히 개발 중이며 성능 최적화가 완료되지 않았습니다. 이 기능을 테스트를 위해 활성화하면, “푸시” 파이프라인을 트리거하는 무한 루프를 방지하기 위한 검증 조치를 신중하게 테스트하고 구현해야 합니다.

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

전제 조건:

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

프로젝트 리포지토리에 푸시하도록 귀하의 프로젝트에서 생성된 작업 토큰에 대한 권한을 부여하려면:

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

작업 토큰은 작업을 시작한 사용자의 접근 권한과 동일한 접근 권한을 가집니다.

허용 목록에 있는 다른 프로젝트 또는 그룹의 작업 토큰은 귀하의 프로젝트의 리포지토리에 푸시할 수 없습니다.

또한, 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 프로토콜이 비활성화되어 있더라도 이 작업 토큰을 사용하여 리포지토리를 클론할 수 있습니다. 리포지토리에 푸시하기 위해 작업 토큰을 사용할 수는 없지만, 문제 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의 파이프라인 내 작업은 프로젝트 A의 CI_JOB_TOKEN 범위로 제한됩니다. 작업이 프로젝트 B에 API 요청을 하기 위해 토큰을 사용해야 한다면, 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

Cloning into 'test2'...
remote: 찾고 있는 프로젝트를 찾을 수 없거나, 해당 프로젝트를 볼 수 있는 권한이 없습니다.
fatal: repository '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 오류 404: 찾을 수 없습니다.

  • 인증되지 않은 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을 사용하여 GraphQL을 사용하는 방법을 보여줍니다:

    • 인바운드 토큰 액세스 범위를 활성화합니다.

    • 프로젝트 A에서 프로젝트 B에 액세스를 허용하거나, B를 A의 허용 목록에 추가합니다.

    • 프로젝트 액세스를 제거합니다.

  • 작업이 더 이상 실행되지 않거나 삭제된 경우, 또는 프로젝트가 삭제되는 과정에 있는 경우 CI 작업 토큰은 무효가 됩니다.