배포 토큰

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

유저 계정과는 독립적으로 배포 작업의 인증을 활성화하기 위해 배포 토큰을 사용할 수 있습니다. 대부분의 경우, 빌드 서버나 CI/CD 서버와 같은 외부 호스트에서 배포 토큰을 사용합니다.

배포 토큰을 사용하면, 자동화된 작업들이 다음과 같은 작업을 수행할 수 있습니다:

  • Git 리포지토리 복제
  • GitLab 컨테이너 레지스트리에서의 풀 및 푸시
  • GitLab 패키지 레지스트리에서의 풀 및 푸시

배포 토큰은 다음과 같은 두 가지 값으로 구성됩니다:

  • username: HTTP 인증 프레임워크에서의 username. 기본 username 형식은 gitlab+deploy-token-{n}입니다. 배포 토큰을 생성할 때 사용자 정의 username을 지정할 수 있습니다.
  • token: HTTP 인증 프레임워크에서의 password.

다음 Endpoints로 HTTP 인증을 위해 배포 토큰을 사용할 수 있습니다:

프로젝트 또는 그룹 레벨에서 배포 토큰을 생성할 수 있습니다:

  • 프로젝트 배포 토큰: 권한은 해당 프로젝트에만 적용됩니다.
  • 그룹 배포 토큰: 권한은 해당 그룹의 모든 프로젝트에 적용됩니다.

기본적으로 배포 토큰은 만료되지 않습니다. 필요에 따라서 만료 날짜를 지정할 수 있습니다. 만료는 해당 날짜의 UTC 자정에 발생합니다.

경고: 외부 인증이 활성화된 경우, 새로운 또는 기존의 배포 토큰을 Git 작업과 패키지 레지스트리 작업에 사용할 수 없습니다.

범위

배포 토큰의 범위는 수행할 수 있는 작업을 결정합니다.

범위 설명
read_repository git clone을 사용하여 리포지토리에 대한 읽기 전용 액세스
read_registry 프로젝트의 컨테이너 레지스트리의 이미지에 대한 읽기 전용 액세스
write_registry 프로젝트의 컨테이너 레지스트리에 대한 쓰기 액세스 (푸시). 이미지를 푸시하려면 읽기 및 쓰기 권한이 모두 필요합니다.
read_package_registry 프로젝트의 패키지 레지스트리에 대한 읽기 전용 액세스
write_package_registry 프로젝트의 패키지 레지스트리에 대한 쓰기 액세스

GitLab 배포 토큰

  • GitLab 배포 토큰에 대한 gitlab-deploy-token 그룹 레벨에서의 지원은 GitLab 15.1에 도입되었으며, ci_variable_for_group_gitlab_deploy_token이라는 플래그와 함께 기본적으로 활성화되어 있습니다.
  • GitLab 15.4에서 기능 플래그 ci_variable_for_group_gitlab_deploy_token가 제거되었습니다.

GitLab 배포 토큰은 특수한 종류의 배포 토큰입니다. gitlab-deploy-token이라는 이름의 배포 토큰을 생성하면, 그 배포 토큰은 CI/CD 작업에서 변수로 자동 노출되어 CI/CD 파이프라인에서 사용할 수 있습니다:

  • CI_DEPLOY_USER: Username
  • CI_DEPLOY_PASSWORD: Token

예를 들어, GitLab 컨테이너 레지스트리에 로그인하려면 다음과 같이 GitLab 토큰을 사용합니다: 

docker login $CI_REGISTRY -u $CI_DEPLOY_USER --password-stdin <<<$CI_DEPLOY_PASSWORD

주의: GitLab 15.0 및 이전 버전에서 gitlab-deploy-token 배포 토큰에 대한 특별한 처리는 그룹 배포 토큰에서는 동작하지 않습니다. 그룹 배포 토큰을 CI/CD 작업에서 사용하려면, 설정 > CI/CD > 변수에서 그룹 배포 토큰의 이름과 토큰을 CI_DEPLOY_USER 및 CI_DEPLOY_PASSWORD CI/CD 변수로 설정해야 합니다.

GitLab 배포 토큰 보안

GitLab 배포 토큰은 장기간 사용되기 때문에 공격자에게 유용한 대상이 될 수 있습니다.

배포 토큰이 노출되는 것을 방지하기 위해 runners를 안전하게 구성해야 합니다:

  • 기계를 재사용하는 경우 Docker privileged 모드를 사용하지 말아야 합니다.
  • 작업이 동일한 머신에서 실행될 때 shell executor를 사용하지 말아야 합니다.

보안되지 않은 GitLab Runner 구성은 다른 작업에서 토큰을 도난당할 가능성을 높입니다.

GitLab 공개 API

배포 토큰은 GitLab 공개 API와 함께 사용할 수 없습니다. 그러나 패키지 레지스트리와 같은 일부 Endpoints에서 배포 토큰을 사용할 수 있습니다. 자세한 내용은 레지스트리로 인증을 참조하십시오.

배포 토큰 생성

유저 계정과는 독립적으로 실행될 수 있는 배포 작업을 자동화하기 위해 배포 토큰을 생성할 수 있습니다.

전제 조건: - 그룹 배포 토큰을 생성하려면 해당 그룹의 소유자 역할이 있어야 합니다. - 프로젝트 배포 토큰을 생성하려면 해당 프로젝트의 최소한 관리자 역할이 있어야 합니다.

  1. 좌측 사이드바에서 검색 또는 이동을 선택하여 프로젝트 또는 그룹을 찾습니다.
  2. 설정 > 리포지토리를 선택합니다.
  3. 배포 토큰을 확장합니다.
  4. 토큰 추가를 선택합니다.
  5. 필드를 작성하고 원하는 범위를 선택합니다.
  6. 배포 토큰 생성을 선택합니다.

배포 토큰 값들을 기록하세요. 페이지를 떠나거나 새로고침한 이후에 더 이상 액세스할 수 없습니다.

배포 토큰 취소

토큰이 더 이상 필요하지 않을 때 토큰을 취소합니다.

전제 조건:

  • 그룹 배포 토큰을 취소하려면 그룹의 소유자 역할이 있어야 합니다.
  • 프로젝트 배포 토큰을 취소하려면 프로젝트의 유지 관리자 역할 이상이 있어야 합니다.

배포 토큰을 취소하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
  2. 설정 > 저장소를 선택합니다.
  3. 배포 토큰을 확장합니다.
  4. 활성 배포 토큰 섹션에서 취소하려는 토큰 옆에서 취소를 선택합니다.

저장소 복제

배포 토큰을 사용하여 저장소를 복제할 수 있습니다.

전제 조건:

  • read_repository 범위를 갖는 배포 토큰이 있어야 합니다.

배포 토큰을 사용하여 저장소를 복제하는 예시: 

git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git

컨테이너 레지스트리에서 이미지 가져오기

배포 토큰을 사용하여 컨테이너 레지스트리에서 이미지를 가져올 수 있습니다.

전제 조건:

  • read_registry 범위를 갖는 배포 토큰이 있어야 합니다.

컨테이너 레지스트리에서 이미지를 가져오는 예시: 

docker login -u <username> -p <deploy_token> registry.example.com
docker pull $CONTAINER_TEST_IMAGE

컨테이너 레지스트리에 이미지 푸시

배포 토큰을 사용하여 컨테이너 레지스트리에 이미지를 푸시할 수 있습니다.

전제 조건:

  • read_registry 및 write_registry 범위를 갖는 배포 토큰이 있어야 합니다.

컨테이너 레지스트리에 이미지를 푸시하는 예시: 

docker login -u <username> -p <deploy_token> registry.example.com
docker push $CONTAINER_TEST_IMAGE

패키지 레지스트리에서 패키지 가져오기

배포 토큰을 사용하여 패키지 레지스트리에서 패키지를 가져올 수 있습니다.

전제 조건:

  • read_package_registry 범위를 갖는 배포 토큰이 있어야 합니다.

사용하려는 패키지 유형에 대한 인증 지침에 따라 배포 토큰을 사용하세요.

GitLab 레지스트리에서 NuGet 패키지를 설치하는 예시: 

nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName <username> -Password <deploy_token>
nuget install mypkg.nupkg

패키지 레지스트리로 패키지 푸시

배포 토큰을 사용하여 GitLab 패키지 레지스트리로 패키지를 푸시할 수 있습니다.

전제 조건:

  • write_package_registry 범위를 갖는 배포 토큰이 있어야 합니다.

사용하려는 패키지 유형에 대한 인증 지침에 따라 배포 토큰을 사용하세요.

GitLab 패키지 레지스트리로 NuGet 패키지를 게시하는 예시: 

nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName <username> -Password <deploy_token>
nuget push mypkg.nupkg -Source GitLab

의존성 프록시에서 이미지 가져오기

배포 토큰을 사용하여 의존성 프록시에서 이미지를 가져올 수 있습니다.

전제 조건:

  • read_registry 및 write_registry 범위를 갖는 배포 토큰이 있어야 합니다.

의존성 프록시 인증 지침에 따라 진행하세요.