CI/CD 파이프라인 잡이 실행되기 직전에 GitLab은 고유한 토큰을 생성하여 CI_JOB_TOKEN 사전 정의된 변수로 잡에 제공합니다. 토큰은 잡이 실행되는 동안에만 유효합니다. 잡이 완료되면 토큰 접근이 취소되어 더 이상 토큰을 사용할 수 없습니다.

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

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

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

잡 토큰 접근#

히스토리

• GitLab 18.8에서 단일 태그를 가져오는 권한이 도입.

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

권한을 더 세밀하게 만들기 위한 공개 제안이 있습니다.

GitLab CI/CD 잡 토큰 보안#

잡 토큰이 유출되면 CI/CD 잡을 실행한 사용자가 접근할 수 있는 개인 데이터에 접근하는 데 잠재적으로 사용될 수 있습니다. 이 토큰의 유출 또는 남용을 방지하기 위해 GitLab은 다음과 같이 합니다:

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

또한 러너가 안전하게 구성되도록 해야 합니다:

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

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

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

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

기본적으로 잡 토큰 접근은 프로젝트의 파이프라인에서 실행되는 CI/CD 잡만으로 제한됩니다. 다른 그룹 또는 프로젝트가 다른 프로젝트의 파이프라인에서 잡 토큰으로 인증하려면:

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

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

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

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

히스토리

• GitLab 15.9에서 도입. :inbound_ci_scoped_job_token 기능 플래그로 배포, 기본적으로 활성화됨.
• GitLab 15.10에서 기능 플래그 제거.
• 이 프로젝트에 CI_JOB_TOKEN으로 접근 허용 설정이 GitLab 16.3에서 이 프로젝트에 대한 접근 제한으로 이름 변경.
• GitLab 17.0에서 잡 토큰 허용 목록에 그룹 추가 도입.
• Token Access 섹션이 Job token permissions으로 이름 변경, 이 프로젝트에 대한 접근 제한 설정이 승인된 그룹 및 프로젝트로 이름 변경 GitLab 17.2에서.
• Add project 옵션이 GitLab 17.6에서 Add로 이름 변경.
• 승인된 그룹 및 프로젝트 설정이 GitLab 17.3에서 CI/CD 잡 토큰 허용 목록으로 이름 변경.

그룹 또는 프로젝트를 잡 토큰 허용 목록에 추가하여 잡 토큰을 인증으로 사용하여 프로젝트의 리소스에 접근을 허용할 수 있습니다. 기본적으로 모든 프로젝트의 허용 목록에는 해당 프로젝트 자체만 포함됩니다. 교차 프로젝트 접근이 필요한 경우에만 허용 목록에 그룹 또는 프로젝트를 추가하세요.

프로젝트를 허용 목록에 추가해도 허용 목록에 있는 프로젝트의 멤버에게 추가적인 권한이 부여되지 않습니다. 그들은 이미 허용 목록에 있는 프로젝트의 잡 토큰을 사용하여 프로젝트에 접근하기 위해 프로젝트의 리소스에 접근할 권한이 있어야 합니다.

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

사전 조건:

• 현재 프로젝트에 대한 Maintainer 또는 Owner 역할이 있어야 합니다. 허용된 프로젝트가 내부 또는 비공개인 경우 해당 프로젝트에 Guest, Planner, Reporter, Developer, Maintainer 또는 Owner 역할이 있어야 합니다.
• 허용 목록에 200개 이상의 그룹 및 프로젝트가 추가되지 않아야 합니다.

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

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
3. Job token permissions를 확장합니다.
4. CI/CD 잡 토큰 허용 목록 오른쪽에서 Add를 선택합니다.
5. Group or project를 선택합니다.
6. 허용 목록에 추가할 그룹 또는 프로젝트의 경로를 입력하고 Add를 선택합니다.

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

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

히스토리

• GitLab 16.6에서 도입.
• GitLab 17.0에서 리포지터리에 대한 접근 도입.

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

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

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

사전 조건:

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

기능을 프로젝트 멤버에게만 표시되도록 설정하려면:

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

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

히스토리

• 이 프로젝트에 CI_JOB_TOKEN으로 접근 허용 설정이 GitLab 16.3에서 이 프로젝트에 대한 접근 제한으로 이름 변경.
• Token Access 섹션이 Job token permissions으로 이름 변경, 이 프로젝트에 대한 접근 제한 설정이 승인된 그룹 및 프로젝트로 이름 변경 GitLab 17.2에서.
• 승인된 그룹 및 프로젝트 설정이 GitLab 17.3에서 CI/CD 잡 토큰 허용 목록으로 이름 변경.

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

이 옵션은 모든 프로젝트에 대해 잡 토큰 허용 목록 활성화 및 적용 설정이 비활성화된 GitLab Self-Managed 또는 GitLab Dedicated 인스턴스에서만 사용할 수 있습니다.

사전 조건:

• 프로젝트에 대한 Maintainer 또는 Owner 역할이 있어야 합니다.

잡 토큰 허용 목록을 비활성화하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
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으로 이름 변경, 이 프로젝트에 대한 접근 제한 설정이 승인된 그룹 및 프로젝트로 이름 변경 GitLab 17.2에서.
• 승인된 그룹 및 프로젝트 설정이 GitLab 17.3에서 CI/CD 잡 토큰 허용 목록으로 이름 변경.
• GitLab 18.3에서 GitLab.com에서 활성화.
• GitLab 18.4에서 일반 제공. 기능 플래그 allow_push_repository_for_job_token 제거.

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

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

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

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

사전 조건:

• 프로젝트에 대한 Maintainer 또는 Owner 역할이 있어야 합니다.

프로젝트에서 생성된 잡 토큰에 프로젝트 리포지터리로 푸시하는 권한을 부여하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
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라는 플래그와 함께 도입. 기본적으로 비활성화됨.

허용 목록에 있는 프로젝트의 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 세밀한 권한 또는 기본 권한을 활성화하여 소스 프로젝트 또는 해당 그룹을 허용 목록에 추가합니다.

잡 토큰의 세밀한 권한#

세밀한 권한을 사용하여 제한된 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. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
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. 상단 바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
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의 접근 허용, 또는 A의 허용 목록에 B 추가.
  • 프로젝트 접근 제거.
• CI 잡 토큰은 잡이 더 이상 실행되지 않거나, 지워졌거나, 프로젝트가 삭제 중인 경우 무효화됩니다.

semantic-release 도구와 잡 토큰#

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

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

자세한 내용은 이슈 891을 참조하세요.

JWT 형식 잡 토큰 오류#

CI/CD 잡 토큰의 JWT 형식에서 몇 가지 알려진 문제가 있습니다.

EC2 Fargate Runner 사용자 정의 실행기의 Error when persisting the task ARN. 오류#

EC2 Fargate 사용자 정의 실행기 버전 0.5.0 이하에 버그가 있습니다. 이 문제는 다음 오류를 유발합니다:

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

이 문제를 해결하려면 Fargate 사용자 정의 실행기 버전 0.5.1 이상으로 업그레이드하세요.

base64 인코딩으로 인한 invalid character '\n' in string literal 오류#

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

base64 명령의 기본 동작은 79자보다 긴 문자열을 줄 바꿈합니다. 잡 실행 중 JWT 형식 잡 토큰을 base64로 인코딩할 때(예: echo $CI_JOB_TOKEN | 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로 업데이트하세요.