CI/CD job token

요약

CI/CD 파이프라인 job이 실행되기 직전에 GitLab은 고유한 토큰을 생성하여 CI_JOB_TOKEN 사전 정의된 변수로 job에 제공합니다. CI/CD job 토큰을 사용하여 실행 중인 job에서 특정 GitLab 기능으로 인증합니다.

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

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

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

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

잡 토큰 접근#

히스토리

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

GitLab 19.1에서 Badges API에 접근하는 권한이 도입됨.

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

리소스	참고
Badges API	이 API의 모든 엔드포인트에 접근할 수 있습니다.
Branches API	`GET /projects/:id/repository/branches` 엔드포인트에 접근할 수 있습니다.
Commits API	`GET /projects/:id/repository/commits/:sha` 및 `GET /projects/:id/repository/commits/:sha/merge_requests` 엔드포인트에 접근할 수 있습니다.
Container registry	job의 프로젝트와 연결된 컨테이너 레지스트리로 인증하기 위해 `$CI_REGISTRY_PASSWORD` 사전 정의된 변수로 사용됩니다.
Package registry	레지스트리로 인증하는 데 사용됩니다.
Terraform module registry	레지스트리로 인증하는 데 사용됩니다.
Secure files	job에서 보안 파일을 사용하기 위해 `glab securefile` 명령에 사용됩니다.
Container registry API	job의 프로젝트와 연결된 컨테이너 레지스트리로만 인증할 수 있습니다.
Deployments API	이 API의 모든 엔드포인트에 접근할 수 있습니다.
Environments API	이 API의 모든 엔드포인트에 접근할 수 있습니다.
Files API	`GET /projects/:id/repository/files/:file_path/raw` 엔드포인트에 접근할 수 있습니다.
Jobs API	`GET /job` 엔드포인트에만 접근할 수 있습니다.
Job artifacts API	다운로드 엔드포인트에만 접근할 수 있습니다.
Merge requests API	`GET /projects/:id/merge_requests` 및 `GET /projects/:id/merge_requests/:merge_request_iid` 엔드포인트에 접근할 수 있습니다.
Notes API	`GET /projects/:id/merge_requests/:merge_request_iid/notes` 및 `GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id` 엔드포인트에 접근할 수 있습니다.
Packages API	이 API의 모든 엔드포인트에 접근할 수 있습니다.
Pipeline trigger tokens API	`POST /projects/:id/trigger/pipeline` 엔드포인트에만 접근할 수 있습니다.
Pipelines API	`PUT /projects/:id/pipelines/:pipeline_id/metadata` 엔드포인트에만 접근할 수 있습니다.
Release links API	이 API의 모든 엔드포인트에 접근할 수 있습니다.
Releases API	이 API의 모든 엔드포인트에 접근할 수 있습니다.
Repositories API	공개 리포지터리의 `GET /projects/:id/repository/changelog` 엔드포인트에만 접근할 수 있습니다.
Tags API	`GET /projects/:id/repository/tags` 및 `GET /projects/:id/repository/tags/:tag_name` 엔드포인트에 접근할 수 있습니다.

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

GitLab CI/CD 잡 토큰 보안#

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

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

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

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

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

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

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

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

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

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

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

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

히스토리

GitLab 17.0에서 job 토큰 허용 목록에 그룹 추가 도입됨.

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

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

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

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

사전 조건:

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

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

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

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

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

히스토리

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

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

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

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

사전 조건:

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

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

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > General을 선택합니다.
Visibility, project features, permissions를 확장합니다.
접근을 제한하려는 기능에 대해 가시성을 Only project members로 설정합니다.

아티팩트를 가져오는 기능은 CI/CD 가시성 설정으로 제어됩니다.

Save changes를 선택합니다.

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

Offering: GitLab Self-Managed, GitLab Dedicated

히스토리

Token Access 섹션이 Job token permissions으로 이름 변경, 이 프로젝트에 대한 접근 제한 설정이 승인된 그룹 및 프로젝트로 이름 변경 GitLab 17.2에서.

승인된 그룹 및 프로젝트 설정이 CI/CD 잡 토큰 허용 목록으로 이름 변경 GitLab 17.3에서.

Warning

토큰 접근 제한 및 허용 목록을 비활성화하는 것은 보안 위험입니다. 악의적인 사용자가 승인되지 않은 프로젝트에서 생성된 파이프라인을 손상시키려 할 수 있습니다. 파이프라인이 유지 관리자 중 한 명에 의해 생성된 경우 job 토큰을 사용하여 프로젝트에 접근하려 할 수 있습니다.

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

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

사전 조건:

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

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

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
Job token permissions를 확장합니다.
All groups and projects를 선택합니다.
권장됨. 테스트가 완료되면 This project and any groups and projects in the allowlist를 선택하여 job 토큰 허용 목록을 다시 활성화합니다.

GraphQL(inboundJobTokenScopeEnabled) 또는 REST API를 사용하여 이 설정을 수정할 수도 있습니다.

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

히스토리

GitLab 17.2에서 allow_push_repository_for_job_token이라는 플래그와 함께 도입됨. 기본적으로 비활성화됨.

Token Access 섹션이 Job token permissions으로 이름 변경, 이 프로젝트에 대한 접근 제한 설정이 승인된 그룹 및 프로젝트로 이름 변경 GitLab 17.2에서.
승인된 그룹 및 프로젝트 설정이 CI/CD 잡 토큰 허용 목록으로 이름 변경 GitLab 17.3에서.
GitLab 18.3에서 GitLab.com에서 활성화됨.
GitLab 18.4에서 일반 제공됨. 기능 플래그 allow_push_repository_for_job_token 제거됨.

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

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

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

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

Warning

풀 미러로 구성된 프로젝트에서는 이 설정을 활성화하지 마세요. 특히 미러 업데이트에 대해 파이프라인이 실행되는 경우. 업스트림 리포지터리 소유자가 CI_JOB_TOKEN을 사용하여 미러링된 프로젝트에 커밋을 푸시하려 할 수 있습니다.

사전 조건:

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

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

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
Job token permissions를 확장합니다.
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에서 일반 제공됨. 기능 플래그 allow_push_to_allowlisted_projects 제거됨.

허용 목록에 있는 프로젝트의 CI/CD job 토큰이 프로젝트 리포지터리로 푸시할 수 있도록 허용할 수 있습니다. 이는 장기 액세스 토큰 없이 GitOps 워크플로, 서브모듈 태깅, 교차 리포지터리 CI/CD 파이프라인에 유용합니다.

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

Warning

풀 미러로 구성된 프로젝트에서는 이 설정을 활성화하지 마세요. 특히 미러 업데이트에 대해 파이프라인이 트리거되는 경우. 허용 목록에 있는 소스 프로젝트의 소유자가 CI/CD job 토큰을 사용하여 미러링된 프로젝트에 커밋을 푸시할 수 있습니다.

교차 프로젝트 푸시가 작동하려면 다음 모든 조건이 참이어야 합니다:

대상 프로젝트에 Allow Git push requests to the repository가 활성화되어 있어야 합니다.
대상 프로젝트에 Allow cross-project Git push requests from allowlisted projects가 활성화되어 있어야 합니다.
대상 프로젝트에 job 토큰 허용 목록이 활성화되어 있어야 합니다.
소스 프로젝트가 admin_repositories 세밀한 권한을 가지거나 기본 권한(세밀한 제한 없음)으로 대상 프로젝트의 허용 목록에 있어야 합니다. 소스 프로젝트를 포함하는 허용 목록의 그룹 항목도 이 요구 사항을 충족합니다.
파이프라인을 시작한 사용자가 대상 프로젝트에서 최소한 Developer 권한이 있어야 합니다.

사전 조건:

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

교차 프로젝트 푸시 요청을 허용하려면:

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
Settings > CI/CD를 선택합니다.
Job token permissions를 확장합니다.
Permissions 섹션에서 Allow Git push requests to the repository를 선택합니다.
Allow cross-project Git push requests from allowlisted projects를 선택합니다.
Save Changes를 선택합니다.
ADMIN_REPOSITORIES 세밀한 권한 또는 기본 권한을 활성화하여 소스 프로젝트 또는 해당 그룹을 허용 목록에 추가합니다.

잡 토큰의 세밀한 권한#

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

자세한 내용은 CI/CD job 토큰의 세밀한 권한을 참조하세요.

Git 리포지터리 클론#

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

예를 들어:

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

HTTPS 프로토콜이 그룹, 프로젝트 또는 인스턴스 설정에 의해 비활성화된 경우에도 이 job 토큰을 사용하여 리포지터리를 클론할 수 있습니다.

REST API 인증#

다음 방법을 사용하여 특정 REST API 엔드포인트에 대한 요청을 인증하는 데 job 토큰을 사용할 수 있습니다:

헤더: --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"

토큰 보안 지침은 보안 고려 사항을 참조하세요.

job 토큰을 사용하여 GraphQL 요청을 인증할 수 없습니다.

잡 토큰 인증 로그#

히스토리

GitLab 17.6에서 도입됨.

인증 로그에서 다른 프로젝트가 CI/CD job 토큰을 사용하여 프로젝트로 인증하는 방법을 추적할 수 있습니다. 로그를 확인하려면:

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

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

프로젝트에 대한 새 인증은 인증 로그에 표시되는 데 최대 5분이 걸릴 수 있습니다.

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

히스토리

GitLab 17.10에서 도입됨.

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

CI/CD 토큰에 레거시 형식을 사용하려면:

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

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

문제 해결#

CI job 토큰 실패는 보통 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 job 토큰 인증 문제를 해결하는 동안 다음 사항을 참고하세요:

GraphQL 예시 뮤테이션을 사용하여 프로젝트별 범위 설정을 토글할 수 있습니다.
이 댓글은 Bash와 cURL로 GraphQL을 사용하는 방법을 보여줍니다:

인바운드 토큰 접근 범위 활성화.

프로젝트 A에서 프로젝트 B의 접근 허용, 또는 A의 허용 목록에 B 추가.
프로젝트 접근 제거.
CI job 토큰은 job이 더 이상 실행되지 않거나, 지워졌거나, 프로젝트가 삭제 중인 경우 무효화됩니다.

`semantic-release` 도구와 잡 토큰#

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

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

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

JWT 형식 잡 토큰 오류#

CI/CD job 토큰의 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를 사용하여 job 토큰을 인코딩하면 invalid character '\n' 오류가 발생할 수 있습니다.

base64 명령의 기본 동작은 79자보다 긴 문자열을 줄 바꿈합니다. job 실행 중 JWT 형식 job 토큰을 base64로 인코딩할 때(예: echo $CI_JOB_TOKEN | base64), 토큰이 무효화됩니다.

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

장기 실행 잡에서 `403 Forbidden` 오류#

GitLab 18.8 이하에서 JWT 형식 job 토큰을 사용할 때 job이 403 Forbidden 오류로 실패할 수 있습니다. 다음의 경우에 발생할 수 있습니다:

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

오류는 일반적으로 러너 로그에 다음과 같이 표시됩니다:

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로 업데이트하세요.

CI/CD job token

GitLab v19.2

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

원문 보기

번역일: 2026-06-19

요약

잡 토큰 접근#

히스토리

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

GitLab 19.1에서 Badges API에 접근하는 권한이 도입됨.

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

리소스	참고
Badges API	이 API의 모든 엔드포인트에 접근할 수 있습니다.
Branches API	`GET /projects/:id/repository/branches` 엔드포인트에 접근할 수 있습니다.
Commits API	`GET /projects/:id/repository/commits/:sha` 및 `GET /projects/:id/repository/commits/:sha/merge_requests` 엔드포인트에 접근할 수 있습니다.
Container registry	job의 프로젝트와 연결된 컨테이너 레지스트리로 인증하기 위해 `$CI_REGISTRY_PASSWORD` 사전 정의된 변수로 사용됩니다.
Package registry	레지스트리로 인증하는 데 사용됩니다.
Terraform module registry	레지스트리로 인증하는 데 사용됩니다.
Secure files	job에서 보안 파일을 사용하기 위해 `glab securefile` 명령에 사용됩니다.
Container registry API	job의 프로젝트와 연결된 컨테이너 레지스트리로만 인증할 수 있습니다.
Deployments API	이 API의 모든 엔드포인트에 접근할 수 있습니다.
Environments API	이 API의 모든 엔드포인트에 접근할 수 있습니다.
Files API	`GET /projects/:id/repository/files/:file_path/raw` 엔드포인트에 접근할 수 있습니다.
Jobs API	`GET /job` 엔드포인트에만 접근할 수 있습니다.
Job artifacts API	다운로드 엔드포인트에만 접근할 수 있습니다.
Merge requests API	`GET /projects/:id/merge_requests` 및 `GET /projects/:id/merge_requests/:merge_request_iid` 엔드포인트에 접근할 수 있습니다.
Notes API	`GET /projects/:id/merge_requests/:merge_request_iid/notes` 및 `GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id` 엔드포인트에 접근할 수 있습니다.
Packages API	이 API의 모든 엔드포인트에 접근할 수 있습니다.
Pipeline trigger tokens API	`POST /projects/:id/trigger/pipeline` 엔드포인트에만 접근할 수 있습니다.
Pipelines API	`PUT /projects/:id/pipelines/:pipeline_id/metadata` 엔드포인트에만 접근할 수 있습니다.
Release links API	이 API의 모든 엔드포인트에 접근할 수 있습니다.
Releases API	이 API의 모든 엔드포인트에 접근할 수 있습니다.
Repositories API	공개 리포지터리의 `GET /projects/:id/repository/changelog` 엔드포인트에만 접근할 수 있습니다.
Tags API	`GET /projects/:id/repository/tags` 및 `GET /projects/:id/repository/tags/:tag_name` 엔드포인트에 접근할 수 있습니다.

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

GitLab CI/CD 잡 토큰 보안#

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

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

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

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

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

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

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

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

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

히스토리

GitLab 17.0에서 job 토큰 허용 목록에 그룹 추가 도입됨.

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

사전 조건:

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

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

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

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

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

히스토리

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

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

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

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

사전 조건:

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

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

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > General을 선택합니다.
Visibility, project features, permissions를 확장합니다.
접근을 제한하려는 기능에 대해 가시성을 Only project members로 설정합니다.

아티팩트를 가져오는 기능은 CI/CD 가시성 설정으로 제어됩니다.

Save changes를 선택합니다.

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

Offering: GitLab Self-Managed, GitLab Dedicated

히스토리

Token Access 섹션이 Job token permissions으로 이름 변경, 이 프로젝트에 대한 접근 제한 설정이 승인된 그룹 및 프로젝트로 이름 변경 GitLab 17.2에서.

승인된 그룹 및 프로젝트 설정이 CI/CD 잡 토큰 허용 목록으로 이름 변경 GitLab 17.3에서.

Warning

사전 조건:

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

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

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
Job token permissions를 확장합니다.
All groups and projects를 선택합니다.
권장됨. 테스트가 완료되면 This project and any groups and projects in the allowlist를 선택하여 job 토큰 허용 목록을 다시 활성화합니다.

GraphQL(inboundJobTokenScopeEnabled) 또는 REST API를 사용하여 이 설정을 수정할 수도 있습니다.

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

히스토리

GitLab 17.2에서 allow_push_repository_for_job_token이라는 플래그와 함께 도입됨. 기본적으로 비활성화됨.

Token Access 섹션이 Job token permissions으로 이름 변경, 이 프로젝트에 대한 접근 제한 설정이 승인된 그룹 및 프로젝트로 이름 변경 GitLab 17.2에서.
승인된 그룹 및 프로젝트 설정이 CI/CD 잡 토큰 허용 목록으로 이름 변경 GitLab 17.3에서.
GitLab 18.3에서 GitLab.com에서 활성화됨.
GitLab 18.4에서 일반 제공됨. 기능 플래그 allow_push_repository_for_job_token 제거됨.

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

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

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

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

Warning

사전 조건:

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

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

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
왼쪽 사이드바에서 Settings > CI/CD를 선택합니다.
Job token permissions를 확장합니다.
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에서 일반 제공됨. 기능 플래그 allow_push_to_allowlisted_projects 제거됨.

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

Warning

교차 프로젝트 푸시가 작동하려면 다음 모든 조건이 참이어야 합니다:

대상 프로젝트에 Allow Git push requests to the repository가 활성화되어 있어야 합니다.
대상 프로젝트에 Allow cross-project Git push requests from allowlisted projects가 활성화되어 있어야 합니다.
대상 프로젝트에 job 토큰 허용 목록이 활성화되어 있어야 합니다.
소스 프로젝트가 admin_repositories 세밀한 권한을 가지거나 기본 권한(세밀한 제한 없음)으로 대상 프로젝트의 허용 목록에 있어야 합니다. 소스 프로젝트를 포함하는 허용 목록의 그룹 항목도 이 요구 사항을 충족합니다.
파이프라인을 시작한 사용자가 대상 프로젝트에서 최소한 Developer 권한이 있어야 합니다.

사전 조건:

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

교차 프로젝트 푸시 요청을 허용하려면:

상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
Settings > CI/CD를 선택합니다.
Job token permissions를 확장합니다.
Permissions 섹션에서 Allow Git push requests to the repository를 선택합니다.
Allow cross-project Git push requests from allowlisted projects를 선택합니다.
Save Changes를 선택합니다.
ADMIN_REPOSITORIES 세밀한 권한 또는 기본 권한을 활성화하여 소스 프로젝트 또는 해당 그룹을 허용 목록에 추가합니다.

잡 토큰의 세밀한 권한#

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

자세한 내용은 CI/CD job 토큰의 세밀한 권한을 참조하세요.

Git 리포지터리 클론#

예를 들어:

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

HTTPS 프로토콜이 그룹, 프로젝트 또는 인스턴스 설정에 의해 비활성화된 경우에도 이 job 토큰을 사용하여 리포지터리를 클론할 수 있습니다.

REST API 인증#

다음 방법을 사용하여 특정 REST API 엔드포인트에 대한 요청을 인증하는 데 job 토큰을 사용할 수 있습니다:

헤더: --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"

토큰 보안 지침은 보안 고려 사항을 참조하세요.

job 토큰을 사용하여 GraphQL 요청을 인증할 수 없습니다.

잡 토큰 인증 로그#

히스토리

GitLab 17.6에서 도입됨.

인증 로그에서 다른 프로젝트가 CI/CD job 토큰을 사용하여 프로젝트로 인증하는 방법을 추적할 수 있습니다. 로그를 확인하려면:

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

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

프로젝트에 대한 새 인증은 인증 로그에 표시되는 데 최대 5분이 걸릴 수 있습니다.

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

히스토리

GitLab 17.10에서 도입됨.

CI/CD 토큰에 레거시 형식을 사용하려면:

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

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

문제 해결#

CI job 토큰 실패는 보통 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 job 토큰 인증 문제를 해결하는 동안 다음 사항을 참고하세요:

GraphQL 예시 뮤테이션을 사용하여 프로젝트별 범위 설정을 토글할 수 있습니다.
이 댓글은 Bash와 cURL로 GraphQL을 사용하는 방법을 보여줍니다:

인바운드 토큰 접근 범위 활성화.

프로젝트 A에서 프로젝트 B의 접근 허용, 또는 A의 허용 목록에 B 추가.
프로젝트 접근 제거.
CI job 토큰은 job이 더 이상 실행되지 않거나, 지워졌거나, 프로젝트가 삭제 중인 경우 무효화됩니다.

`semantic-release` 도구와 잡 토큰#

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

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

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

JWT 형식 잡 토큰 오류#

CI/CD job 토큰의 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를 사용하여 job 토큰을 인코딩하면 invalid character '\n' 오류가 발생할 수 있습니다.

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

장기 실행 잡에서 `403 Forbidden` 오류#

GitLab 18.8 이하에서 JWT 형식 job 토큰을 사용할 때 job이 403 Forbidden 오류로 실패할 수 있습니다. 다음의 경우에 발생할 수 있습니다:

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

오류는 일반적으로 러너 로그에 다음과 같이 표시됩니다:

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로 업데이트하세요.

CI/CD job token

잡 토큰 접근#

GitLab CI/CD 잡 토큰 보안#

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

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

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

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

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

허용 목록에 있는 프로젝트에서 교차 프로젝트 Git 푸시 요청 허용#

잡 토큰의 세밀한 권한#

Git 리포지터리 클론#

REST API 인증#

잡 토큰 인증 로그#

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

문제 해결#

semantic-release 도구와 잡 토큰#

JWT 형식 잡 토큰 오류#

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

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

장기 실행 잡에서 403 Forbidden 오류#

CI/CD job token

잡 토큰 접근#

GitLab CI/CD 잡 토큰 보안#

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

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

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

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

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

허용 목록에 있는 프로젝트에서 교차 프로젝트 Git 푸시 요청 허용#

잡 토큰의 세밀한 권한#

Git 리포지터리 클론#

REST API 인증#

잡 토큰 인증 로그#

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

문제 해결#

semantic-release 도구와 잡 토큰#

JWT 형식 잡 토큰 오류#

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

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

장기 실행 잡에서 403 Forbidden 오류#

`semantic-release` 도구와 잡 토큰#

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

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

장기 실행 잡에서 `403 Forbidden` 오류#

`semantic-release` 도구와 잡 토큰#

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

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

장기 실행 잡에서 `403 Forbidden` 오류#