배포 토큰

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

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

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

  • Git 리포지토리 복제.
  • GitLab 컨테이너 레지스트리에서 가져오기 및 푸시.
  • GitLab 패키지 레지스트리에서 가져오기 및 푸시.

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

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

배포 토큰은 SSH 인증을 지원하지 않습니다.

배포 토큰을 다음 엔드포인트에 대한 HTTP 인증에 사용할 수 있습니다:

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

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

기본적으로 배포 토큰은 만료되지 않습니다. 선택적으로 생성할 때 만료 날짜를 설정할 수 있습니다. 만료는 해당 날짜의 자정 UTC에 발생합니다.

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

범위

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

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

GitLab 배포 토큰

GitLab 배포 토큰은 특수한 유형의 배포 토큰입니다. gitlab-deploy-token이라는 이름의 배포 토큰을 생성하면, 이 배포 토큰은 자동으로 프로젝트 CI/CD 작업에 변수로 노출됩니다:

  • CI_DEPLOY_USER: 사용자 이름
  • CI_DEPLOY_PASSWORD: 토큰

예를 들어, GitLab 패키지 레지스트리에 로그인하기 위해 GitLab 토큰을 사용하는 방법은 다음과 같습니다:

echo "$CI_DEPLOY_PASSWORD" | docker login $CI_REGISTRY -u $CI_DEPLOY_USER --password-stdin

참고:
GitLab 15.0 및 이전 버전에서는 gitlab-deploy-token 배포 토큰에 대한 특별한 처리가 그룹 배포 토큰에는 작동하지 않습니다. 그룹 배포 토큰을 CI/CD 작업에 사용할 수 있도록 하려면 Settings > CI/CD > Variables에서 그룹 배포 토큰의 이름과 토큰을 CI_DEPLOY_USER 및 CI_DEPLOY_PASSWORD CI/CD 변수에 설정하세요.

gitlab-deploy-token이 그룹에 정의되면 CI_DEPLOY_USER 및 CI_DEPLOY_PASSWORD CI/CD 변수는 그룹의 직계 자식 프로젝트에만 사용할 수 있습니다.

GitLab 배포 토큰 보안

GitLab 배포 토큰은 장기 생존 가능하므로 공격자들에게 매력적입니다.

배포 토큰 유출을 방지하기 위해, 러너를 안전하게 구성해야 합니다:

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

안전하지 않은 GitLab 러너 구성은 다른 작업에서 토큰을 도 stolen 할 위험을 증가시킵니다.

GitLab 공개 API

배포 토큰은 GitLab 공개 API와 함께 사용할 수 없습니다. 그러나 패키지 레지스트리와 같은 일부 엔드포인트에서는 배포 토큰을 사용할 수 있습니다. 엔드포인트가 패키지 레지스트리에 속하는지 여부는 URL에 packages/<format> 문자열이 포함되어 있기 때문에 알 수 있습니다. 예를 들어: https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt. 추가 정보는 레지스트리에 대한 인증을 참조하세요.

배포 토큰 만들기

사용자 계정과 독립적으로 실행할 수 있는 배포 작업을 자동화하기 위해 배포 토큰을 만듭니다.

사전 요구 사항:

  • 그룹 배포 토큰을 만들려면 그룹에 대한 소유자 역할이 있어야 합니다.
  • 프로젝트 배포 토큰을 만들려면 프로젝트에 대해 최소한 Maintainer 역할이 있어야 합니다.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트나 그룹을 찾습니다.
  2. 설정 > 리포지토리를 선택합니다.
  3. 배포 토큰을 확장합니다.
  4. 토큰 추가를 선택합니다.
  5. 필드를 작성하고 원하는 범위를 선택합니다.
  6. 배포 토큰 만들기를 선택합니다.

배포 토큰의 값을 기록해 두세요. 페이지를 떠나거나 새로 고침하면 다시 접근할 수 없습니다.

배포 토큰 취소하기

더 이상 필요하지 않을 때 토큰을 취소하십시오.

사전 요구 사항:

  • 그룹 배포 토큰을 취소하려면 그룹에 대한 소유자 역할이 있어야 합니다.
  • 프로젝트 배포 토큰을 취소하려면 프로젝트에 대해 최소한 Maintainer 역할이 있어야 합니다.

배포 토큰을 취소하려면:

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

리포지토리 클론하기

배포 토큰을 사용하여 리포지토리를 클론할 수 있습니다.

사전 요구 사항:

  • read_repository 범위가 포함된 배포 토큰.

배포 토큰을 사용하여 리포지토리를 클론하는 예:

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

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

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

사전 요구 사항:

  • read_registry 범위가 포함된 배포 토큰.

컨테이너 레지스트리에서 이미지를 가져오기 위해 배포 토큰을 사용하는 예:

echo "$DEPLOY_TOKEN" | docker login -u <username> --password-stdin registry.example.com
docker pull $CONTAINER_TEST_IMAGE

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

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

사전 요구 사항:

  • read_registry 및 write_registry 범위가 포함된 배포 토큰.

컨테이너 레지스트리에 이미지를 푸시하기 위해 배포 토큰을 사용하는 예:

echo "$DEPLOY_TOKEN" | docker login -u <username> --password-stdin 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 범위가 있는 배포 토큰.

원하는 패키지 유형에 대해 배포 토큰의 인증 지침을 따르세요.

패키지 레지스트리에 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 범위가 있는 배포 토큰.

의존성 프록시 인증 지침을 따르세요.