배포 토큰

요약

배포 토큰은 개별 사용자 계정에 권한을 묶지 않고도 GitLab 리소스에 안전하게 접근할 수 있게 합니다. 배포 토큰을 사용하면 다음과 같은 이점이 있습니다. 배포 토큰은 다음 두 값의 쌍입니다. 배포 토큰은 SSH 인증을 지원하지 않습니다.

배포 토큰은 개별 사용자 계정에 권한을 묶지 않고도 GitLab 리소스에 안전하게 접근할 수 있게 합니다. Git 작업, 컨테이너 레지스트리, 패키지 레지스트리에 사용해 배포 자동화에 필요한 범위만 정확히 부여할 수 있습니다.

배포 토큰을 사용하면 다음과 같은 이점이 있습니다.

자동화 시스템에서 개인 자격 증명을 제거해 배포를 더 안전하게 유지합니다
토큰마다 구체적인 권한을 지정해 세분화된 접근 제어를 적용합니다
내장 인증 변수로 CI/CD 파이프라인을 단순하게 구성합니다
팀원이 바뀌어도 중단되지 않는 배포 프로세스를 유지합니다
전용 토큰 ID로 배포를 추적해 감사 기록을 개선합니다
외부 빌드 시스템 및 배포 도구와 연동합니다

배포 토큰은 다음 두 값의 쌍입니다.

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

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

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

GitLab 패키지 레지스트리 공개 API.
Git 명령.
GitLab 가상 레지스트리 패키지 작업.

배포 토큰은 프로젝트 수준 또는 그룹 수준에서 만들 수 있습니다.

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

기본적으로 배포 토큰은 만료되지 않습니다. 토큰을 만들 때 만료 날짜를 선택적으로 설정할 수 있습니다. 만료는 해당 날짜의 UTC 자정에 이루어집니다.

Warning

외부 인가가 활성화되어 있으면 새 배포 토큰과 기존 배포 토큰 모두 Git 작업 및 패키지 레지스트리 작업에 사용할 수 없습니다.

범위#

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

범위	설명
`read_repository`	`git clone`을 사용한 리포지터리 읽기 전용 액세스.
`read_registry`	프로젝트의 컨테이너 레지스트리에 있는 이미지에 대한 읽기 전용 액세스.
`write_registry`	프로젝트의 컨테이너 레지스트리에 대한 쓰기 액세스(푸시). 이미지를 푸시하려면 읽기 및 쓰기 액세스가 모두 필요합니다.
`read_virtual_registry`	그룹 수준 의존성 프록시와 가상 레지스트리를 통한 컨테이너 이미지 읽기 전용(풀) 액세스를 부여합니다. 프로젝트의 컨테이너 레지스트리에 직접 접근하는 권한은 부여하지 않습니다. 의존성 프록시가 활성화된 경우에만 사용할 수 있습니다.
`write_virtual_registry`	그룹 수준 의존성 프록시 캐시에 대한 쓰기 액세스를 부여하며, 해당 캐시를 통한 풀도 암묵적으로 허용합니다. 프로젝트의 컨테이너 레지스트리에 대한 푸시 또는 삭제 권한은 부여하지 않습니다. 의존성 프록시가 활성화된 경우에만 사용할 수 있습니다.
`read_package_registry`	프로젝트의 패키지 레지스트리에 대한 읽기 전용 액세스.
`write_package_registry`	프로젝트의 패키지 레지스트리에 대한 쓰기 액세스.

GitLab 배포 토큰#

GitLab 배포 토큰은 특별한 유형의 배포 토큰입니다. gitlab-deploy-token이라는 이름으로 배포 토큰을 만들면 해당 배포 토큰이 프로젝트 CI/CD job에 다음 변수로 자동 노출됩니다.

CI_DEPLOY_USER: 사용자 이름
CI_DEPLOY_PASSWORD: 토큰

예를 들어 GitLab 토큰으로 GitLab 컨테이너 레지스트리에 로그인하려면 다음과 같이 실행합니다.

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

그룹에 gitlab-deploy-token이 정의되어 있으면 CI_DEPLOY_USER와 CI_DEPLOY_PASSWORD CI/CD 변수는 해당 그룹의 바로 하위 프로젝트에서만 사용할 수 있습니다.

배포 토큰 만료#

히스토리

GitLab 18.3에서 project_deploy_token_expiring_notifications라는 기능 플래그와 함께 배포 토큰 만료 이메일 알림이 도입됨. 기본적으로 비활성화되어 있습니다.

Feature flag

이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 히스토리를 참고합니다.

배포 토큰은 지정한 날짜의 UTC 00:00에 만료됩니다.

GitLab은 매일 UTC 오전 1시에 곧 만료되는 배포 토큰을 확인합니다. 프로젝트 Owner와 Maintainer에게는 토큰 만료 60일, 30일, 7일 전에 이메일로 알림이 전송됩니다.

이 이메일 알림은 취소되지 않은 활성 배포 토큰에 대해 각 시점마다 한 번씩만 전송됩니다.

GitLab 배포 토큰 보안#

GitLab 배포 토큰은 수명이 길어 공격자의 표적이 되기 쉽습니다.

배포 토큰 유출을 막으려면 러너도 안전하게 구성해야 합니다.

머신을 재사용한다면 Docker privileged 모드 사용을 피합니다.
여러 job이 같은 머신에서 실행된다면 shell executor 사용을 피합니다.

GitLab Runner 구성이 안전하지 않으면 다른 job의 토큰을 탈취당할 위험이 커집니다.

GitLab 공개 API#

배포 토큰은 GitLab 공개 API에 사용할 수 없습니다. 다만 패키지 레지스트리의 엔드포인트처럼 일부 엔드포인트에는 배포 토큰을 사용할 수 있습니다. URL에 packages/<format> 문자열이 있으면 패키지 레지스트리에 속한 엔드포인트입니다. 예: https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt. 자세한 내용은 레지스트리 인증을 참고합니다.

배포 토큰 만들기#

사용자 계정과 무관하게 실행할 수 있는 배포 작업을 자동화하려면 배포 토큰을 만듭니다.

사전 요구 사항:

그룹 배포 토큰을 만들려면 그룹의 Owner 권한이 있어야 합니다.
프로젝트 배포 토큰을 만들려면 프로젝트의 Maintainer 또는 Owner 권한이 있어야 합니다.

상단 바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾습니다.
왼쪽 사이드바에서 Settings > Repository를 선택합니다.
Deploy tokens를 펼칩니다.
Add token을 선택합니다.
각 필드를 입력하고 원하는 범위를 선택합니다.
Create deploy token을 선택합니다.

배포 토큰의 값을 기록해 둡니다. 페이지를 벗어나거나 새로 고치면 다시 확인할 수 없습니다.

배포 토큰 취소#

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

사전 요구 사항:

그룹 배포 토큰을 취소하려면 그룹의 Owner 권한이 있어야 합니다.
프로젝트 배포 토큰을 취소하려면 프로젝트의 Maintainer 또는 Owner 권한이 있어야 합니다.

배포 토큰을 취소하려면 다음 절차를 따릅니다.

상단 바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾습니다.
왼쪽 사이드바에서 Settings > Repository를 선택합니다.
Deploy tokens를 펼칩니다.
Active Deploy Tokens 섹션에서 취소할 토큰 옆의 Revoke를 선택합니다.

리포지터리 복제#

배포 토큰으로 리포지터리를 복제할 수 있습니다.

사전 요구 사항:

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 범위.
가상 레지스트리의 경우: read_virtual_registry 및 write_virtual_registry 범위.

의존성 프록시 인증 절차를 따릅니다.

배포 토큰

GitLab v19.5

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

원문 보기

번역일: 2026-09-18

요약

배포 토큰을 사용하면 다음과 같은 이점이 있습니다.

자동화 시스템에서 개인 자격 증명을 제거해 배포를 더 안전하게 유지합니다
토큰마다 구체적인 권한을 지정해 세분화된 접근 제어를 적용합니다
내장 인증 변수로 CI/CD 파이프라인을 단순하게 구성합니다
팀원이 바뀌어도 중단되지 않는 배포 프로세스를 유지합니다
전용 토큰 ID로 배포를 추적해 감사 기록을 개선합니다
외부 빌드 시스템 및 배포 도구와 연동합니다

배포 토큰은 다음 두 값의 쌍입니다.

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

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

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

GitLab 패키지 레지스트리 공개 API.
Git 명령.
GitLab 가상 레지스트리 패키지 작업.

배포 토큰은 프로젝트 수준 또는 그룹 수준에서 만들 수 있습니다.

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

Warning

외부 인가가 활성화되어 있으면 새 배포 토큰과 기존 배포 토큰 모두 Git 작업 및 패키지 레지스트리 작업에 사용할 수 없습니다.

범위#

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

범위	설명
`read_repository`	`git clone`을 사용한 리포지터리 읽기 전용 액세스.
`read_registry`	프로젝트의 컨테이너 레지스트리에 있는 이미지에 대한 읽기 전용 액세스.
`write_registry`	프로젝트의 컨테이너 레지스트리에 대한 쓰기 액세스(푸시). 이미지를 푸시하려면 읽기 및 쓰기 액세스가 모두 필요합니다.
`read_virtual_registry`	그룹 수준 의존성 프록시와 가상 레지스트리를 통한 컨테이너 이미지 읽기 전용(풀) 액세스를 부여합니다. 프로젝트의 컨테이너 레지스트리에 직접 접근하는 권한은 부여하지 않습니다. 의존성 프록시가 활성화된 경우에만 사용할 수 있습니다.
`write_virtual_registry`	그룹 수준 의존성 프록시 캐시에 대한 쓰기 액세스를 부여하며, 해당 캐시를 통한 풀도 암묵적으로 허용합니다. 프로젝트의 컨테이너 레지스트리에 대한 푸시 또는 삭제 권한은 부여하지 않습니다. 의존성 프록시가 활성화된 경우에만 사용할 수 있습니다.
`read_package_registry`	프로젝트의 패키지 레지스트리에 대한 읽기 전용 액세스.
`write_package_registry`	프로젝트의 패키지 레지스트리에 대한 쓰기 액세스.

GitLab 배포 토큰#

CI_DEPLOY_USER: 사용자 이름
CI_DEPLOY_PASSWORD: 토큰

예를 들어 GitLab 토큰으로 GitLab 컨테이너 레지스트리에 로그인하려면 다음과 같이 실행합니다.

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

그룹에 gitlab-deploy-token이 정의되어 있으면 CI_DEPLOY_USER와 CI_DEPLOY_PASSWORD CI/CD 변수는 해당 그룹의 바로 하위 프로젝트에서만 사용할 수 있습니다.

배포 토큰 만료#

히스토리

GitLab 18.3에서 project_deploy_token_expiring_notifications라는 기능 플래그와 함께 배포 토큰 만료 이메일 알림이 도입됨. 기본적으로 비활성화되어 있습니다.

Feature flag

이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 히스토리를 참고합니다.

배포 토큰은 지정한 날짜의 UTC 00:00에 만료됩니다.

이 이메일 알림은 취소되지 않은 활성 배포 토큰에 대해 각 시점마다 한 번씩만 전송됩니다.

GitLab 배포 토큰 보안#

GitLab 배포 토큰은 수명이 길어 공격자의 표적이 되기 쉽습니다.

배포 토큰 유출을 막으려면 러너도 안전하게 구성해야 합니다.

머신을 재사용한다면 Docker privileged 모드 사용을 피합니다.
여러 job이 같은 머신에서 실행된다면 shell executor 사용을 피합니다.

GitLab Runner 구성이 안전하지 않으면 다른 job의 토큰을 탈취당할 위험이 커집니다.

GitLab 공개 API#

배포 토큰 만들기#

사용자 계정과 무관하게 실행할 수 있는 배포 작업을 자동화하려면 배포 토큰을 만듭니다.

사전 요구 사항:

그룹 배포 토큰을 만들려면 그룹의 Owner 권한이 있어야 합니다.
프로젝트 배포 토큰을 만들려면 프로젝트의 Maintainer 또는 Owner 권한이 있어야 합니다.

상단 바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾습니다.
왼쪽 사이드바에서 Settings > Repository를 선택합니다.
Deploy tokens를 펼칩니다.
Add token을 선택합니다.
각 필드를 입력하고 원하는 범위를 선택합니다.
Create deploy token을 선택합니다.

배포 토큰의 값을 기록해 둡니다. 페이지를 벗어나거나 새로 고치면 다시 확인할 수 없습니다.

배포 토큰 취소#

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

사전 요구 사항:

그룹 배포 토큰을 취소하려면 그룹의 Owner 권한이 있어야 합니다.
프로젝트 배포 토큰을 취소하려면 프로젝트의 Maintainer 또는 Owner 권한이 있어야 합니다.

배포 토큰을 취소하려면 다음 절차를 따릅니다.

상단 바에서 Search or go to를 선택하고 프로젝트 또는 그룹을 찾습니다.
왼쪽 사이드바에서 Settings > Repository를 선택합니다.
Deploy tokens를 펼칩니다.
Active Deploy Tokens 섹션에서 취소할 토큰 옆의 Revoke를 선택합니다.

리포지터리 복제#

배포 토큰으로 리포지터리를 복제할 수 있습니다.

사전 요구 사항:

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 범위.
가상 레지스트리의 경우: read_virtual_registry 및 write_virtual_registry 범위.

의존성 프록시 인증 절차를 따릅니다.