CI/CD 파이프라인 잡이 실행되려고 하면 GitLab은 고유한 토큰을 생성하여 CI_JOB_TOKEN 사전 정의 변수로 잡에서 사용할 수 있게 합니다. 이 토큰은 잡이 실행되는 동안에만 유효합니다. 잡이 끝나면 토큰 접근 권한이 취소되어 더 이상 토큰을 사용할 수 없습니다.

CI/CD 잡 토큰을 사용하면 실행 중인 잡에서 특정 GitLab 기능을 인증할 수 있습니다. 이 토큰은 파이프라인을 트리거한 사용자와 동일한 접근 수준을 받지만 개인 액세스 토큰보다 접근 가능한 리소스가 더 적습니다. 사용자는 커밋을 푸시하거나 수동 잡을 실행하거나 예약된 파이프라인을 소유함으로써 잡을 트리거할 수 있습니다. 이 사용자는 리소스에 접근하기 위해 필요한 권한을 가진 역할을 보유해야 합니다.

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

프로젝트가 공개(public) 또는 내부(internal)인 경우 허용 목록에 없어도 일부 기능에 접근할 수 있습니다. 예를 들어 프로젝트의 공개 파이프라인에서 아티팩트를 가져올 수 있습니다. 이 접근 권한은 제한할 수도 있습니다.

잡 토큰 접근#

히스토리

• 단일 태그를 조회하는 권한이 GitLab 18.8에서 도입되었습니다.
• Badges API에 접근하는 권한이 GitLab 19.1에서 도입되었습니다.
• 커밋이 푸시된 모든 참조를 나열하는 권한이 GitLab 19.4에서 도입되었습니다.

CI/CD 잡 토큰은 다음 리소스에 접근할 수 있습니다.

권한을 더 세분화하기 위한 제안이 논의 중입니다.

GitLab CI/CD 잡 토큰 보안#

잡 토큰이 유출되면 CI/CD 잡을 실행한 사용자가 접근할 수 있는 비공개 데이터에 접근하는 데 악용될 수 있습니다. 이 토큰의 유출이나 오용을 방지하기 위해 GitLab은 다음을 수행합니다.

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

또한 보안을 위해 러너를 다음과 같이 구성해야 합니다.

• 머신을 재사용하는 경우 Docker privileged 모드 사용을 피합니다.
• 잡이 동일한 머신에서 실행되는 경우 shell executor 사용을 피합니다.

안전하지 않은 GitLab Runner 구성은 다른 잡에서 토큰을 탈취당할 위험을 높입니다.

프로젝트에 대한 잡 토큰 접근 제어#

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

기본적으로 잡 토큰 접근은 해당 프로젝트의 파이프라인에서 실행되는 CI/CD 잡으로만 제한됩니다. 다른 그룹이나 프로젝트가 해당 프로젝트의 파이프라인에서 잡 토큰으로 인증하도록 허용하려면 다음이 필요합니다.

• 그룹 또는 프로젝트를 잡 토큰 허용 목록에 추가해야 합니다.
• 잡을 트리거하는 사용자는 해당 프로젝트의 멤버여야 합니다.
• 사용자는 해당 작업을 수행할 권한을 보유해야 합니다.

프로젝트가 공개 또는 내부인 경우 공개적으로 접근 가능한 일부 리소스는 어떤 프로젝트의 잡 토큰으로도 접근할 수 있습니다. 이러한 리소스는 허용 목록에 있는 프로젝트로만 제한할 수도 있습니다.

GitLab Self-Managed 관리자는 이 설정을 재정의하고 강제 적용할 수 있습니다. 이 설정이 강제 적용되면 CI/CD 잡 토큰은 항상 프로젝트의 허용 목록으로 제한됩니다.

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

히스토리

• 잡 토큰 허용 목록에 그룹을 추가하는 기능이 GitLab 17.0에서 도입되었습니다.
• Token Access 섹션이 Job token permissions로 이름이 변경되었고, Limit access to this project 설정이 Authorized groups and projects로 이름이 변경되었습니다(GitLab 17.2).
• Authorized groups and projects 설정이 CI/CD job token allowlist로 이름이 변경되었습니다(GitLab 17.3).
• Add project 옵션이 GitLab 17.6에서 Add로 이름이 변경되었습니다.

그룹이나 프로젝트를 잡 토큰 허용 목록에 추가하면 잡 토큰 인증으로 프로젝트 리소스에 접근할 수 있습니다. 기본적으로 모든 프로젝트의 허용 목록에는 자기 자신만 포함됩니다. 프로젝트 간 접근이 필요한 경우에만 그룹이나 프로젝트를 허용 목록에 추가합니다.

프로젝트를 허용 목록에 추가해도 허용 목록에 등록된 프로젝트의 멤버에게 추가 권한이 부여되지는 않습니다. 허용 목록에 등록된 프로젝트의 잡 토큰으로 해당 프로젝트에 접근하려면 이미 리소스에 접근할 권한을 보유하고 있어야 합니다.

예를 들어 프로젝트 A는 프로젝트 A의 허용 목록에 프로젝트 B를 추가할 수 있습니다. 그러면 프로젝트 B("허용된 프로젝트")의 CI/CD 잡은 CI/CD 잡 토큰을 사용해 API 호출을 인증하여 프로젝트 A에 접근할 수 있습니다.

허용 목록에 그룹을 추가하면 해당 항목은 그 그룹과 모든 깊이의 하위 그룹에 있는 모든 프로젝트에 접근 권한을 부여합니다. GitLab은 잡이 토큰을 사용할 때마다 일치 여부를 평가하므로 나중에 그룹에 추가된 프로젝트도 허용 목록을 변경하지 않아도 포함됩니다.

예를 들어 프로젝트 A가 자신의 허용 목록에 example-group 그룹을 추가한다고 가정합니다. 그러면 example-group/team-b/project-c의 잡은 잡 토큰을 사용해 프로젝트 A에 접근할 수 있고, 이후 example-group 아래에 생성되는 모든 프로젝트의 잡도 마찬가지입니다.

사전 요구 사항:

• 현재 프로젝트에 대해 Maintainer 또는 Owner 권한을 보유해야 합니다. 허용되는 프로젝트가 internal 또는 private인 경우 해당 프로젝트에서 Guest, Planner, Reporter, Developer, Maintainer, Owner 중 하나의 권한을 보유해야 합니다.
• 허용 목록의 그룹은 200개, 프로젝트는 200개를 초과할 수 없습니다. 두 제한은 별도로 계산됩니다.

그룹이나 프로젝트를 허용 목록에 추가하려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Job token permissions를 펼칩니다.
4. CI/CD job token allowlist 오른쪽에서 Add를 선택합니다.
5. Group or project를 선택합니다.
6. 허용 목록에 추가할 그룹 또는 프로젝트의 경로를 입력하고 Add를 선택합니다.

API를 사용해 그룹이나 프로젝트를 허용 목록에 추가할 수도 있습니다.

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

히스토리

• 리포지터리 접근이 GitLab 17.0에서 도입되었습니다.

허용 목록에 없는 프로젝트도 잡 토큰을 사용해 공개 또는 내부 프로젝트에 인증하고 다음을 수행할 수 있습니다.

• 아티팩트를 가져옵니다.
• 컨테이너 레지스트리에 접근합니다.
• 패키지 레지스트리에 접근합니다.
• 릴리스, 배포, 환경에 접근합니다.
• 리포지터리에 접근합니다.

각 기능을 프로젝트 멤버에게만 표시되도록 설정하면 이러한 작업에 대한 접근을 허용 목록의 프로젝트로만 제한할 수 있습니다.

사전 요구 사항:

• 프로젝트에 대해 Maintainer 권한을 보유해야 합니다.

기능을 프로젝트 멤버에게만 표시되도록 설정하려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. Visibility, project features, permissions를 펼칩니다.
4. 접근을 제한하려는 기능에 대해 가시성을 Only project members로 설정합니다.
   • 아티팩트 가져오기 접근은 CI/CD 가시성 설정으로 제어됩니다.
5. Save changes를 선택합니다.

모든 프로젝트가 프로젝트에 접근하도록 허용#

히스토리

• Token Access 섹션이 Job token permissions로 이름이 변경되었고, Limit access to this project 설정이 Authorized groups and projects로 이름이 변경되었습니다(GitLab 17.2).
• Authorized groups and projects 설정이 CI/CD job token allowlist로 이름이 변경되었습니다(GitLab 17.3).

CI/CD 잡 토큰 허용 목록을 비활성화하면 모든 프로젝트의 잡이 잡 토큰으로 프로젝트에 접근할 수 있습니다. 파이프라인을 트리거하는 사용자는 프로젝트에 접근할 권한을 보유해야 합니다. 이 설정은 테스트 등의 목적으로만 비활성화해야 하며, 가능한 한 빨리 다시 활성화해야 합니다.

이 옵션은 Enable and enforce job token allowlist for all projects 설정이 비활성화된 GitLab Self-Managed 또는 GitLab Dedicated 인스턴스에서만 사용할 수 있습니다.

사전 요구 사항:

• 프로젝트에 대해 Maintainer 또는 Owner 권한을 보유해야 합니다.

잡 토큰 허용 목록을 비활성화하려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Job token permissions를 펼칩니다.
4. All groups and projects를 선택합니다.
5. 권장. 테스트가 끝나면 This project and any groups and projects in the allowlist를 선택해 잡 토큰 허용 목록을 다시 활성화합니다.

GraphQL (inboundJobTokenScopeEnabled) 또는 REST API로도 이 설정을 수정할 수 있습니다.

프로젝트 리포지터리에 대한 Git 푸시 요청 허용#

히스토리

• GitLab 17.2에서 allow_push_repository_for_job_token이라는 이름의 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• Token Access 섹션이 Job token permissions로 이름이 변경되었고, Limit access to this project 설정이 Authorized groups and projects로 이름이 변경되었습니다(GitLab 17.2).
• Authorized groups and projects 설정이 CI/CD job token allowlist로 이름이 변경되었습니다(GitLab 17.3).
• GitLab 18.3에서 GitLab.com에 활성화되었습니다.
• GitLab 18.4에서 일반 공급(GA)되었습니다. allow_push_repository_for_job_token 기능 플래그가 제거되었습니다.

CI/CD 잡 토큰으로 인증된 Git 푸시 요청을 허용하도록 프로젝트를 구성할 수 있습니다. 이 설정은 기본적으로 꺼져 있습니다.

이 설정을 켜면 프로젝트 파이프라인에서 실행되는 CI/CD 잡이 생성한 잡 토큰만 프로젝트에 푸시할 수 있습니다.

잡 토큰을 사용해 프로젝트에 푸시하면 CI/CD 파이프라인이 트리거되지 않습니다. 잡 토큰은 잡을 시작한 사용자와 동일한 접근 권한을 가집니다.

semantic-release 도구를 사용하는 경우 이 설정이 파이프라인 생성을 막을 수 있습니다.

사전 요구 사항:

• 프로젝트에 대해 Maintainer 또는 Owner 권한을 보유해야 합니다.

프로젝트에서 생성된 잡 토큰이 프로젝트 리포지터리에 푸시할 수 있는 권한을 부여하려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Job token permissions를 펼칩니다.
4. Permissions 섹션에서 Allow Git push requests to the repository를 선택합니다.

프로젝트 API의 ci_push_repository_for_job_token_allowed 매개변수로도 이 설정을 제어할 수 있습니다.

허용 목록에 등록된 프로젝트에서 프로젝트 간 Git 푸시 요청 허용#

히스토리

• GitLab 19.0에서 allow_push_to_allowlisted_projects라는 이름의 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 19.1에서 일반 공급(GA)되었습니다. allow_push_to_allowlisted_projects 기능 플래그가 제거되었습니다.

허용 목록에 등록된 프로젝트의 CI/CD 잡 토큰이 프로젝트 리포지터리에 푸시하도록 허용할 수 있습니다. 프로젝트 간 푸시를 사용하면 GitOps 워크플로, 서브모듈 태깅, 리포지터리 간 CI/CD 파이프라인에 장기 액세스 토큰을 사용하지 않아도 됩니다.

잡 토큰 푸시가 성공하면 대상 프로젝트에서 CI/CD 파이프라인이 트리거되지 않습니다.

프로젝트 간 푸시가 작동하려면 다음 조건이 모두 충족되어야 합니다.

• 대상 프로젝트에서 Allow Git push requests to the repository가 활성화되어 있습니다.
• 대상 프로젝트에서 Allow cross-project Git push requests from allowlisted projects가 활성화되어 있습니다.
• 대상 프로젝트에서 잡 토큰 허용 목록이 활성화되어 있습니다.
• 소스 프로젝트가 admin_repositories 세분화된 권한으로, 또는 기본 권한(세분화된 제한이 설정되지 않음)으로 대상 프로젝트의 허용 목록에 등록되어 있습니다. 소스 프로젝트를 포함하는 그룹 항목이 허용 목록에 있어도 이 요구 사항을 충족합니다.
• 파이프라인을 시작한 사용자가 대상 프로젝트에서 최소 Developer 권한을 보유하고 있습니다.

사전 요구 사항:

• 프로젝트에 대해 Maintainer 또는 Owner 권한을 보유해야 합니다.

프로젝트 간 푸시 요청을 허용하려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. Settings > CI/CD를 선택합니다.
3. Job token permissions를 펼칩니다.
4. Permissions 섹션에서 Allow Git push requests to the repository를 선택합니다.
5. Allow cross-project Git push requests from allowlisted projects를 선택합니다.
6. Save Changes를 선택합니다.
7. 소스 프로젝트나 해당 그룹을 허용 목록에 추가하고 ADMIN_REPOSITORIES 세분화된 권한을 부여하거나 기본 권한을 그대로 둡니다. 허용 목록 항목에서 ADMIN_REPOSITORIES는 Repositories의 Read and write 옵션입니다. 이 권한은 REST API 엔드포인트가 아니라 Git 푸시 액세스를 부여하므로 세분화된 권한 엔드포인트 표에는 나타나지 않습니다.

잡 토큰의 세분화된 권한#

세분화된 권한을 사용하면 제한된 REST API 엔드포인트 집합에 대한 접근을 명시적으로 허용할 수 있습니다.

자세한 내용은 CI/CD 잡 토큰의 세분화된 권한을 참조합니다.

Git 리포지터리 클로닝#

CI/CD 잡에서 잡 토큰을 사용해 비공개 프로젝트의 리포지터리를 인증하고 클론할 수 있습니다. 사용자로는 gitlab-ci-token을, 비밀번호로는 잡 토큰 값을 사용합니다.

예를 들면 다음과 같습니다.

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

HTTPS 프로토콜이 그룹, 프로젝트, 또는 인스턴스 설정으로 비활성화되어 있어도 이 잡 토큰을 사용해 리포지터리를 클론할 수 있습니다.

REST API 인증#

다음 방법으로 잡 토큰을 사용해 특정 REST API 엔드포인트에 대한 요청을 인증할 수 있습니다.

• 헤더: --header "JOB-TOKEN: $CI_JOB_TOKEN" (권장)
• 폼: --form "token=$CI_JOB_TOKEN"
• 데이터: --data "job_token=$CI_JOB_TOKEN"
• URL의 쿼리 문자열: ?job_token=$CI_JOB_TOKEN (권장하지 않음)

예를 들어 권장되는 헤더 방식을 사용하면 다음과 같습니다.

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

토큰 보안 관련 지침은 보안 고려 사항을 참조합니다.

잡 토큰으로는 GraphQL 요청을 인증할 수 없습니다.

잡 토큰 인증 로그#

히스토리

• GitLab 17.6에서 도입되었습니다.

다른 어떤 프로젝트가 CI/CD 잡 토큰을 사용해 프로젝트에 인증하는지 인증 로그에서 추적할 수 있습니다. 로그를 확인하려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Job token permissions를 펼칩니다. Authentication log 섹션에는 잡 토큰으로 인증하여 프로젝트에 접근한 다른 프로젝트의 목록이 표시됩니다.
4. 선택 사항. Download CSV를 선택해 전체 인증 로그를 CSV 형식으로 다운로드합니다.

인증 로그에는 최대 100개의 인증 이벤트가 표시됩니다. 이벤트 수가 100개를 초과하면 CSV 파일을 다운로드해 로그를 확인합니다.

프로젝트에 대한 새 인증이 인증 로그에 나타나기까지 최대 5분이 걸릴 수 있습니다.

CI/CD 토큰에 레거시 형식 사용#

히스토리

• GitLab 17.10에서 도입되었습니다.

GitLab 19.0부터 CI/CD 잡 토큰은 기본적으로 JWT 표준을 사용합니다. 프로젝트는 최상위 그룹을 구성하여 계속 레거시 형식을 사용할 수 있습니다. 이 설정은 GitLab 20.0 릴리스까지만 사용할 수 있습니다.

CI/CD 토큰에 레거시 형식을 사용하려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. General pipelines를 펼칩니다.
4. Enable JWT format for CI/CD job tokens를 끕니다.

이제 CI/CD 토큰은 레거시 형식을 사용합니다. 나중에 다시 JWT 형식을 사용하려면 이 설정을 다시 활성화하면 됩니다.

문제 해결#

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 예제 뮤테이션이 있습니다.
• 이 댓글은 Bash와 cURL로 GraphQL을 사용해 다음을 수행하는 방법을 보여줍니다.
  • 인바운드 토큰 접근 범위를 활성화합니다.
  • 프로젝트 A에서 프로젝트 B에 접근 권한을 부여하거나, B를 A의 허용 목록에 추가합니다.
  • 프로젝트 접근 권한을 제거합니다.
• 잡이 더 이상 실행 중이지 않거나, 삭제되었거나, 프로젝트가 삭제되는 중이면 CI 잡 토큰이 무효화됩니다.

semantic-release 도구와 잡 토큰#

Allow Git push requests to the repository 설정과 함께 semantic-release 도구를 사용하는 경우 알려진 문제가 있습니다. 이 설정을 활성화하면 다음과 같습니다.

• 도구가 개인 액세스 토큰을 사용하도록 구성되어 있어도 잡 토큰으로 인증합니다.
• 잡 토큰은 새 파이프라인을 트리거하지 않으므로 릴리스 파이프라인이 실행되지 않을 수 있습니다.

자세한 내용은 이슈 891을 참조합니다.

JWT 형식 잡 토큰 오류#

CI/CD 잡 토큰의 JWT 형식에는 다음과 같은 알려진 문제가 있습니다.

EC2 Fargate Runner 커스텀 executor에서 발생하는 Error when persisting the task ARN. 오류#

EC2 Fargate 커스텀 executor의 0.5.0 버전 이하에는 버그가 있습니다. 이 문제는 다음 오류를 일으킵니다.

• Error when persisting the task ARN. Will stop the task for cleanup

이 문제를 해결하려면 Fargate 커스텀 executor를 0.5.1 버전 이상으로 업그레이드합니다.

base64 인코딩에서 발생하는 invalid character '\n' in string literal 오류#

base64로 잡 토큰을 인코딩하면 invalid character '\n' 오류가 발생할 수 있습니다.

base64 명령의 기본 동작은 79자보다 긴 문자열을 줄바꿈합니다. 예를 들어 echo $CI_JOB_TOKEN | base64처럼 잡 실행 중에 JWT 형식 잡 토큰을 base64로 인코딩하면 토큰이 무효화됩니다.

이 문제를 해결하려면 base64 -w0을 사용해 토큰의 자동 줄바꿈을 비활성화합니다.

장시간 실행되는 잡에서 발생하는 403 Forbidden 오류#

GitLab 18.8 이하에서 JWT 형식 잡 토큰을 사용하면 잡이 403 Forbidden 오류로 실패할 수 있습니다. 이는 다음과 같은 경우에 발생할 수 있습니다.

• needs를 사용하는 잡.
• 자식 파이프라인의 잡.
• 콘솔 출력 없이 약 6분 이상 실행되는 잡.

이 오류는 일반적으로 러너 로그에 다음과 같이 나타났습니다.

WARNING: Submitting job to coordinator... job failed
  code=403 job=<job_id> status=PUT https://gitlab.com/api/v4/jobs/<job_id>: 403 Forbidden

이 문제를 피하려면 GitLab 18.9로 업데이트합니다.