GitLab 토큰 개요

요약

이 문서는 GitLab에서 사용하는 토큰과 그 용도, 해당하는 경우 보안 지침을 설명합니다. 토큰을 안전하게 유지하려면 다음을 수행합니다. 일관된 이름 지정 규칙을 사용하면 액세스 토큰을 감사하고 용도를 파악하며 각 토큰을 교체하거나 취소했을 때의 영향을 평가하기가 더 쉬워집니다.

이 문서는 GitLab에서 사용하는 토큰과 그 용도, 해당하는 경우 보안 지침을 설명합니다.

보안 고려 사항#

토큰을 안전하게 유지하려면 다음을 수행합니다.

토큰을 비밀번호처럼 다루고 안전하게 보관합니다.
범위가 지정된 토큰을 생성할 때는 실수로 유출되었을 때의 영향을 줄이기 위해 가능한 한 제한된 범위를 사용합니다.
- 별도의 프로세스에 서로 다른 범위(예: read와 write)가 필요한 경우 범위마다 별도의 토큰을 사용하는 것을 고려합니다. 토큰 하나가 유출되더라도 전체 API 액세스처럼 범위가 넓은 단일 토큰보다 액세스 권한이 적습니다.
토큰을 생성할 때는 다음을 수행합니다.
- 아래 토큰 이름 지정 지침을 따라 이름을 선택합니다.
- 작업이 완료되면 만료되는 토큰을 설정하는 것을 고려합니다. 예를 들어 일회성 가져오기를 수행해야 하는 경우 토큰이 몇 시간 후에 만료되도록 설정합니다.
- 관련 URL을 포함해 추가 컨텍스트를 제공하는 설명을 추가합니다.
URL 대신 헤더로 토큰을 전달합니다.
- 개인, 프로젝트, 그룹 액세스 토큰에는 PRIVATE-TOKEN을 사용합니다.
- job 토큰에는 JOB-TOKEN을 사용합니다.
데모 환경이 있는 경우 프로젝트에 관한 동영상을 녹화하거나 블로그 게시물을 게시한 후 모든 토큰을 취소합니다.
Git 자격 증명 저장소를 사용해 토큰을 저장할 수 있습니다.
모든 유형의 활성 액세스 토큰을 정기적으로 검토하고 필요하지 않은 토큰은 취소합니다.

다음을 하지 않습니다.

URL에 토큰을 추가하지 않습니다.
- URL에 토큰을 포함해 클론하거나 리모트를 추가하면 Git 이 해당 URL을 .git/config 파일에 일반 텍스트로 기록합니다.
- URL은 프록시와 애플리케이션 서버에 자주 기록되며, 이로 인해 시스템 관리자에게 자격 증명이 유출될 수 있습니다.
프로젝트에 토큰을 일반 텍스트로 저장하지 않습니다.
- 토큰이 GitLab CI/CD 용 외부 시크릿인 경우 CI/CD에서 외부 시크릿 사용하기를 참고합니다.
이슈, MR 설명, 댓글, 기타 자유 텍스트 입력란에 코드, 콘솔 명령, 로그 출력을 붙여넣을 때 토큰을 포함하지 않습니다.
콘솔 로그나 아티팩트에 자격 증명을 기록하지 않습니다. 자격 증명을 보호하고 마스킹하는 것을 고려합니다.

토큰 이름 지정 지침#

일관된 이름 지정 규칙을 사용하면 액세스 토큰을 감사하고 용도를 파악하며 각 토큰을 교체하거나 취소했을 때의 영향을 평가하기가 더 쉬워집니다.

이름 지정 규칙은 팀마다 다르지만, 유용한 규칙은 다음 질문에 답할 수 있어야 합니다.

토큰이 수행하는 작업은 무엇입니까? 예를 들어 ci-deploy 또는 api-read 입니다.
토큰이 작동하는 리소스 또는 서비스는 무엇입니까? 예를 들어 gitlab 또는 terraform 입니다.
토큰이 연결된 환경 또는 소유자는 무엇입니까? 예를 들어 production 또는 auth-team 입니다.

예를 들면 다음과 같습니다.

토큰 이름	용도
`ci-deploy-gitlab-production`	프로덕션 환경의 GitLab 프로젝트에 대한 CI/CD 배포 job
`api-read-reporting-dashboard`	리포팅 대시보드에 대한 읽기 전용 API 액세스
`automation-sync-vulnmapper-staging`	스테이징 환경에서 데이터를 동기화하는 자동화 스크립트

구체적으로 작성합니다. test, mytoken, token1, GITLAB_API_TOKEN, API_TOKEN, default 같은 일반적인 이름은 피합니다. 이러한 이름은 감사 시 토큰의 용도를 파악할 수 없게 만듭니다.
토큰을 사용하는 시스템이나 도구를 포함합니다. 토큰이 특정 애플리케이션, 스크립트, 통합에서 사용되는 경우 해당 이름을 포함합니다. 예를 들어 terraform-state-backend 또는 grafana-metrics-reader 입니다.
환경을 포함합니다. 해당하는 경우 토큰이 production, staging, development 중 어느 환경을 대상으로 하는지 표시합니다. 이렇게 하면 프로덕션 토큰을 하위 환경에서 실수로 사용하는 것을 방지할 수 있습니다.
민감한 정보를 포함하지 않습니다. 토큰 이름은 감사 로그와 UI에 표시되므로 사용자 이름, 이메일 주소, 기타 개인 식별 정보(PII)를 토큰 이름에 포함하지 않습니다.
표준화된 대소문자와 구두점 규칙을 설정합니다. 일관된 대소문자와 구분 기호를 사용하면 토큰을 읽고 검색하기가 더 쉬워집니다. 예를 들어 밑줄(_) 대신 하이픈(-)을 사용합니다.
설명 필드를 사용합니다. 토큰 설명 필드를 사용하면 관련 이슈 링크나 토큰을 사용하는 팀 이름 같은 추가 세부 정보를 덧붙일 수 있습니다.

CI/CD 에서의 토큰#

개인 액세스 토큰은 범위가 넓으므로 가능하면 CI/CD 변수로 사용하지 않습니다. CI/CD job에서 다른 리소스에 대한 액세스가 필요한 경우 액세스 범위가 작은 순서대로 다음 중 하나를 사용합니다.

Job 토큰(가장 작은 액세스 범위)
프로젝트 토큰
그룹 토큰

CI/CD 변수 보안에 관한 추가 권장 사항은 다음과 같습니다.

모든 자격 증명에 시크릿 저장소를 사용합니다.
민감한 정보가 포함된 CI/CD 변수는 보호하고, 마스킹하고, 숨겨야 합니다.

개인 액세스 토큰#

개인 액세스 토큰을 생성해 다음으로 인증할 수 있습니다.

GitLab API.
GitLab 리포지터리.
GitLab 레지스트리.

개인 액세스 토큰의 범위와 만료일을 제한할 수 있습니다. 기본적으로 개인 액세스 토큰은 생성한 사용자의 권한을 상속받습니다.

개인 액세스 토큰 API를 사용해 개인 액세스 토큰 교체와 같은 작업을 프로그래밍 방식으로 수행할 수 있습니다.

개인 액세스 토큰이 곧 만료되면 이메일을 받습니다.

권한을 위해 토큰이 필요한 CI/CD job을 고려할 때는 개인 액세스 토큰 사용을 피합니다. 특히 CI/CD 변수로 저장하는 경우에는 더욱 피해야 합니다. CI/CD job 토큰과 프로젝트 액세스 토큰으로도 훨씬 적은 위험으로 같은 결과를 얻을 수 있는 경우가 많습니다.

OAuth 2.0 토큰#

GitLab은 OAuth 2.0 공급자 역할을 수행해 다른 서비스가 사용자를 대신해 GitLab API에 액세스하도록 허용할 수 있습니다.

OAuth 2.0 토큰의 범위와 수명을 제한할 수 있습니다.

가장 토큰(Impersonation token)#

가장 토큰은 특수한 유형의 개인 액세스 토큰입니다. 관리자만 특정 사용자를 위해 생성할 수 있습니다. 가장 토큰을 사용하면 특정 사용자로서 GitLab API, 리포지터리, GitLab 레지스트리에 인증하는 애플리케이션이나 스크립트를 빌드할 수 있습니다.

가장 토큰의 범위를 제한하고 만료일을 설정할 수 있습니다.

프로젝트 액세스 토큰#

프로젝트 액세스 토큰은 프로젝트 범위로 지정됩니다. 개인 액세스 토큰과 마찬가지로 다음으로 인증하는 데 사용할 수 있습니다.

GitLab API.
GitLab 리포지터리.
GitLab 레지스트리.

프로젝트 액세스 토큰의 범위와 만료일을 제한할 수 있습니다. 프로젝트 액세스 토큰을 생성하면 GitLab 이 프로젝트용 봇 사용자를 생성합니다. 프로젝트용 봇 사용자는 서비스 계정이며 라이선스 좌석 수에 포함되지 않습니다.

프로젝트 액세스 토큰 API를 사용해 프로젝트 액세스 토큰 교체와 같은 작업을 프로그래밍 방식으로 수행할 수 있습니다.

Maintainer 또는 Owner 권한을 가진 프로젝트 멤버는 프로젝트 액세스 토큰이 곧 만료되면 이메일을 받습니다.

그룹 액세스 토큰#

그룹 액세스 토큰은 그룹 범위로 지정됩니다. 개인 액세스 토큰과 마찬가지로 다음으로 인증하는 데 사용할 수 있습니다.

GitLab API.
GitLab 리포지터리.
GitLab 레지스트리.

그룹 액세스 토큰의 범위와 만료일을 제한할 수 있습니다. 그룹 액세스 토큰을 생성하면 GitLab 이 그룹용 봇 사용자를 생성합니다. 그룹용 봇 사용자는 서비스 계정이며 라이선스 좌석 수에 포함되지 않습니다.

그룹 액세스 토큰 API를 사용해 그룹 액세스 토큰 교체와 같은 작업을 프로그래밍 방식으로 수행할 수 있습니다.

Owner 권한을 가진 그룹 멤버는 그룹 액세스 토큰이 곧 만료되면 이메일을 받습니다.

배포 토큰#

배포 토큰을 사용하면 사용자 계정과 비밀번호 없이 프로젝트의 패키지와 컨테이너 레지스트리 이미지를 클론, 푸시, 풀할 수 있습니다. 배포 토큰은 GitLab API와 함께 사용할 수 없습니다.

배포 토큰을 관리하려면 최소 Maintainer 권한을 가진 프로젝트 멤버여야 합니다.

배포 키#

배포 키를 사용하면 SSH 공개 키를 GitLab 인스턴스로 가져와 리포지터리에 대한 읽기 전용 또는 읽기-쓰기 액세스를 허용할 수 있습니다. 배포 키는 GitLab API 나 레지스트리와 함께 사용할 수 없습니다.

배포 키를 사용하면 가짜 사용자 계정을 설정하지 않고도 지속적 통합 서버로 리포지터리를 클론할 수 있습니다.

프로젝트에 배포 키를 추가하거나 활성화하려면 최소 Maintainer 권한이 있어야 합니다.

러너 인증 토큰#

러너를 등록할 때 러너 등록 토큰 대신 러너 인증 토큰을 사용할 수 있습니다. 러너 등록 토큰은 지원 중단되었습니다.

러너와 그 설정을 생성하면 러너를 등록하는 데 사용하는 러너 인증 토큰을 받습니다. 러너 인증 토큰은 러너를 설정하는 데 사용하는 config.toml 파일에 로컬로 저장됩니다.

러너는 job 대기열에서 job을 가져올 때 러너 인증 토큰을 사용해 GitLab에 인증합니다. 러너가 GitLab에 인증되면 러너는 job을 실행하는 데 사용하는 job 토큰을 받습니다.

러너 인증 토큰은 러너 머신에 남아 있습니다. 다음 executor의 실행 환경은 러너 인증 토큰이 아니라 job 토큰에만 액세스할 수 있습니다.

Docker Machine
Kubernetes
VirtualBox
Parallels
SSH

러너의 파일 시스템에 악의적으로 액세스하면 config.toml 파일과 러너 인증 토큰이 노출될 수 있습니다. 공격자는 러너 인증 토큰을 사용해 러너를 복제할 수 있습니다.

러너 API를 사용해 러너 인증 토큰을 교체하거나 취소할 수 있습니다.

러너 등록 토큰(레거시)#

Warning

러너 등록 토큰을 전달하는 옵션과 특정 설정 인수 지원은 레거시로 간주되며 권장하지 않습니다. 러너를 등록할 인증 토큰을 생성하려면 러너 생성 워크플로를 사용합니다. 이 프로세스는 러너 소유권을 완전히 추적할 수 있게 하며 러너 플릿의 보안을 강화합니다. GitLab은 새로운 GitLab Runner 토큰 아키텍처를 구현했으며, 이는 러너를 등록하는 새로운 방법을 도입하고 러너 등록 토큰을 제거합니다.

러너 등록 토큰은 GitLab에 러너를 등록하는 데 사용됩니다. 그룹 또는 프로젝트 소유자, 인스턴스 관리자는 GitLab 사용자 인터페이스를 통해 이를 얻을 수 있습니다. 등록 토큰은 러너 등록으로만 범위가 제한되며 그 밖의 범위는 없습니다.

러너 등록 토큰을 사용해 프로젝트나 그룹에서 job을 실행하는 러너를 추가할 수 있습니다. 러너는 프로젝트의 코드에 액세스할 수 있으므로 프로젝트나 그룹에 권한을 할당할 때 주의합니다.

CI/CD job 토큰#

CI/CD job 토큰은 job 이 실행되는 동안에만 유효한 단기 토큰입니다. CI/CD job에 제한된 수의 API 엔드포인트에 대한 액세스 권한을 부여합니다. API 인증은 job을 트리거한 사용자의 권한을 사용해 job 토큰으로 이루어집니다.

job 토큰은 짧은 수명과 제한된 범위로 보호됩니다. 여러 job 이 같은 머신에서 실행되는 경우(예: shell 러너 사용 시) 이 토큰이 유출될 수 있습니다. 프로젝트 allowlist를 사용해 job 토큰이 액세스할 수 있는 범위를 추가로 제한할 수 있습니다.

Docker Machine 러너에서는 러너 머신이 빌드를 하나만 실행한 후 폐기되도록 MaxBuilds=1을 설정해야 합니다. 프로비저닝에는 시간이 걸리므로 이 설정은 성능에 영향을 줄 수 있습니다.

GitLab 클러스터 에이전트 토큰#

Kubernetes 용 GitLab 에이전트를 등록하면 GitLab은 클러스터 에이전트를 GitLab에 인증하기 위한 액세스 토큰을 생성합니다.

이 클러스터 에이전트 토큰을 취소하려면 다음 중 하나를 수행합니다.

에이전트 API로 토큰을 취소합니다.
토큰을 재설정합니다.

두 방법 모두 토큰, 에이전트, 프로젝트 ID를 알아야 합니다. 이 정보를 확인하려면 Rails 콘솔을 사용합니다.

# Find token ID
Clusters::AgentToken.find_by_token('glagent-xxx').id

# Find agent ID
Clusters::AgentToken.find_by_token('glagent-xxx').agent.id
=> 1234

# Find project ID
Clusters::AgentToken.find_by_token('glagent-xxx').agent.project_id
=> 12345

Rails 콘솔에서 직접 토큰을 취소할 수도 있습니다.

# Revoke token with RevokeService, including generating an audit event
Clusters::AgentTokens::RevokeService.new(token: Clusters::AgentToken.find_by_token('glagent-xxx'), current_user: User.find_by_username('admin-user')).execute

# Revoke token manually, which does not generate an audit event
Clusters::AgentToken.find_by_token('glagent-xxx').revoke!

기타 토큰#

피드 토큰#

각 사용자는 만료되지 않는 장기 피드 토큰을 가지고 있습니다. 이 토큰을 사용해 다음으로 인증합니다.

RSS 리더 — 개인화된 RSS 피드를 로드합니다.
캘린더 애플리케이션 — 개인화된 캘린더를 로드합니다.

이 토큰으로는 다른 데이터에 액세스할 수 없습니다.

사용자 범위의 피드 토큰은 모든 피드에 사용할 수 있습니다. 다만 피드 및 캘린더 URL은 하나의 피드에만 유효한 별도의 토큰으로 생성됩니다.

토큰을 가진 사람은 누구나 기밀 이슈를 포함해 사용자인 것처럼 피드 활동을 볼 수 있습니다. 토큰이 유출되었다고 생각되면 즉시 토큰을 재설정합니다.

피드 토큰을 사용하는 피드#

GitLab은 다음 위치에서 RSS 피드를 제공합니다.

피드 토큰 비활성화#

사전 요구 사항:

관리자여야 합니다.

오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > General을 선택합니다.
Visibility and access controls를 펼칩니다.
Feed token 아래에서 Disable feed token 체크박스를 선택한 후 Save changes를 선택합니다.

수신 이메일 토큰#

각 사용자는 만료되지 않는 수신 이메일 토큰을 가지고 있습니다. 이 토큰은 개인 프로젝트별 이메일 주소에 포함됩니다. 이메일로 이슈와 머지 리퀘스트를 생성하는 데 이 토큰을 사용합니다.

Warning

이 토큰을 비밀로 유지합니다. 토큰에 액세스할 수 있는 사람은 누구나 사용자인 것처럼 이슈와 머지 리퀘스트를 생성할 수 있습니다. 이 토큰이 유출된 것으로 의심되면 즉시 토큰을 재설정합니다.

수신 이메일 토큰 재설정#

오른쪽 상단에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > Personal access tokens를 선택합니다.
Incoming email token 아래에서 reset this token을 선택합니다.

워크스페이스 토큰#

히스토리

GitLab 18.2에서 도입되었습니다.

각 워크스페이스는 만료되지 않는 내부 자동 관리 토큰을 가지고 있습니다. 이 토큰은 워크스페이스와의 HTTP 및 SSH 통신을 허용합니다. 워크스페이스가 running 상태를 요청받을 때마다 존재하며, 워크스페이스에 의해 자동으로 주입되고 사용됩니다.

중지된 워크스페이스를 시작하면 새 워크스페이스 토큰이 생성됩니다. 실행 중인 워크스페이스를 재시작하면 기존 토큰이 삭제되고 새 토큰이 생성됩니다.

이 내부 토큰은 직접 보거나 관리할 수 없습니다. 이 토큰으로는 다른 데이터에 액세스할 수 없습니다.

워크스페이스 토큰을 취소하려면 워크스페이스를 stop 또는 terminate합니다. 토큰은 즉시 삭제됩니다.

사용 가능한 범위#

이 표는 토큰별 기본 범위를 보여줍니다. 일부 토큰은 생성할 때 범위를 더 제한할 수 있습니다.

토큰 이름	API 액세스	레지스트리 액세스	리포지터리 액세스
개인 액세스 토큰	✅	✅	✅
OAuth 2.0 토큰	✅	❌	✅
가장 토큰	✅	✅	✅
프로젝트 액세스 토큰	✅¹	✅¹	✅¹
그룹 액세스 토큰	✅²	✅²	✅²
배포 토큰	❌	✅	✅
배포 키	❌	❌	✅
러너 등록 토큰	❌	❌	제한됨³
러너 인증 토큰	❌	❌	제한됨³
Job 토큰	제한됨⁴	❌	✅

토큰 프리픽스#

다음 표는 각 토큰 유형의 프리픽스를 보여줍니다. 개인 액세스 토큰을 제외하면 이러한 프리픽스는 표준 식별자로 설계되어 있어 구성할 수 없습니다.

토큰 이름	프리픽스
개인 액세스 토큰	`glpat-`
OAuth 애플리케이션 시크릿	`gloas-`
가장 토큰	`glpat-`
프로젝트 액세스 토큰	`glpat-`
그룹 액세스 토큰	`glpat-`
배포 토큰	`gldt-`
러너 인증 토큰	`glrt-`, 등록 토큰으로 생성한 경우 `glrtr-`
CI/CD Job 토큰	`glcbt-`
트리거 토큰	`glptt-`
피드 토큰	`glft-`
수신 메일 토큰	`glimt-`
Kubernetes 용 GitLab 에이전트 토큰	`glagent-`
워크스페이스 토큰	`glwt-`(GitLab 18.2에서 추가됨)
GitLab 세션 쿠키	`_gitlab_session=`
SCIM 토큰	`glsoat-`
기능 플래그 클라이언트 토큰	`glffct-`

해당 프로젝트로 제한됩니다. ↩ ↩² ↩³
해당 그룹으로 제한됩니다. ↩ ↩² ↩³
러너 등록 토큰과 인증 토큰은 리포지터리에 직접 액세스할 수 없지만, 리포지터리에 액세스할 수 있는 job을 실행하는 새 러너를 등록하고 인증하는 데 사용할 수 있습니다. ↩ ↩²
특정 엔드포인트만 해당합니다. ↩

GitLab 토큰 개요

GitLab v19.5

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

원문 보기

번역일: 2026-10-15

요약

이 문서는 GitLab에서 사용하는 토큰과 그 용도, 해당하는 경우 보안 지침을 설명합니다.

보안 고려 사항#

토큰을 안전하게 유지하려면 다음을 수행합니다.

토큰을 비밀번호처럼 다루고 안전하게 보관합니다.
범위가 지정된 토큰을 생성할 때는 실수로 유출되었을 때의 영향을 줄이기 위해 가능한 한 제한된 범위를 사용합니다.
- 별도의 프로세스에 서로 다른 범위(예: read와 write)가 필요한 경우 범위마다 별도의 토큰을 사용하는 것을 고려합니다. 토큰 하나가 유출되더라도 전체 API 액세스처럼 범위가 넓은 단일 토큰보다 액세스 권한이 적습니다.
토큰을 생성할 때는 다음을 수행합니다.
- 아래 토큰 이름 지정 지침을 따라 이름을 선택합니다.
- 작업이 완료되면 만료되는 토큰을 설정하는 것을 고려합니다. 예를 들어 일회성 가져오기를 수행해야 하는 경우 토큰이 몇 시간 후에 만료되도록 설정합니다.
- 관련 URL을 포함해 추가 컨텍스트를 제공하는 설명을 추가합니다.
URL 대신 헤더로 토큰을 전달합니다.
- 개인, 프로젝트, 그룹 액세스 토큰에는 PRIVATE-TOKEN을 사용합니다.
- job 토큰에는 JOB-TOKEN을 사용합니다.
데모 환경이 있는 경우 프로젝트에 관한 동영상을 녹화하거나 블로그 게시물을 게시한 후 모든 토큰을 취소합니다.
Git 자격 증명 저장소를 사용해 토큰을 저장할 수 있습니다.
모든 유형의 활성 액세스 토큰을 정기적으로 검토하고 필요하지 않은 토큰은 취소합니다.

다음을 하지 않습니다.

URL에 토큰을 추가하지 않습니다.
- URL에 토큰을 포함해 클론하거나 리모트를 추가하면 Git 이 해당 URL을 .git/config 파일에 일반 텍스트로 기록합니다.
- URL은 프록시와 애플리케이션 서버에 자주 기록되며, 이로 인해 시스템 관리자에게 자격 증명이 유출될 수 있습니다.
프로젝트에 토큰을 일반 텍스트로 저장하지 않습니다.
- 토큰이 GitLab CI/CD 용 외부 시크릿인 경우 CI/CD에서 외부 시크릿 사용하기를 참고합니다.
이슈, MR 설명, 댓글, 기타 자유 텍스트 입력란에 코드, 콘솔 명령, 로그 출력을 붙여넣을 때 토큰을 포함하지 않습니다.
콘솔 로그나 아티팩트에 자격 증명을 기록하지 않습니다. 자격 증명을 보호하고 마스킹하는 것을 고려합니다.

토큰 이름 지정 지침#

일관된 이름 지정 규칙을 사용하면 액세스 토큰을 감사하고 용도를 파악하며 각 토큰을 교체하거나 취소했을 때의 영향을 평가하기가 더 쉬워집니다.

이름 지정 규칙은 팀마다 다르지만, 유용한 규칙은 다음 질문에 답할 수 있어야 합니다.

토큰이 수행하는 작업은 무엇입니까? 예를 들어 ci-deploy 또는 api-read 입니다.
토큰이 작동하는 리소스 또는 서비스는 무엇입니까? 예를 들어 gitlab 또는 terraform 입니다.
토큰이 연결된 환경 또는 소유자는 무엇입니까? 예를 들어 production 또는 auth-team 입니다.

예를 들면 다음과 같습니다.

토큰 이름	용도
`ci-deploy-gitlab-production`	프로덕션 환경의 GitLab 프로젝트에 대한 CI/CD 배포 job
`api-read-reporting-dashboard`	리포팅 대시보드에 대한 읽기 전용 API 액세스
`automation-sync-vulnmapper-staging`	스테이징 환경에서 데이터를 동기화하는 자동화 스크립트

구체적으로 작성합니다. test, mytoken, token1, GITLAB_API_TOKEN, API_TOKEN, default 같은 일반적인 이름은 피합니다. 이러한 이름은 감사 시 토큰의 용도를 파악할 수 없게 만듭니다.
토큰을 사용하는 시스템이나 도구를 포함합니다. 토큰이 특정 애플리케이션, 스크립트, 통합에서 사용되는 경우 해당 이름을 포함합니다. 예를 들어 terraform-state-backend 또는 grafana-metrics-reader 입니다.
환경을 포함합니다. 해당하는 경우 토큰이 production, staging, development 중 어느 환경을 대상으로 하는지 표시합니다. 이렇게 하면 프로덕션 토큰을 하위 환경에서 실수로 사용하는 것을 방지할 수 있습니다.
민감한 정보를 포함하지 않습니다. 토큰 이름은 감사 로그와 UI에 표시되므로 사용자 이름, 이메일 주소, 기타 개인 식별 정보(PII)를 토큰 이름에 포함하지 않습니다.
표준화된 대소문자와 구두점 규칙을 설정합니다. 일관된 대소문자와 구분 기호를 사용하면 토큰을 읽고 검색하기가 더 쉬워집니다. 예를 들어 밑줄(_) 대신 하이픈(-)을 사용합니다.
설명 필드를 사용합니다. 토큰 설명 필드를 사용하면 관련 이슈 링크나 토큰을 사용하는 팀 이름 같은 추가 세부 정보를 덧붙일 수 있습니다.

CI/CD 에서의 토큰#

Job 토큰(가장 작은 액세스 범위)
프로젝트 토큰
그룹 토큰

CI/CD 변수 보안에 관한 추가 권장 사항은 다음과 같습니다.

모든 자격 증명에 시크릿 저장소를 사용합니다.
민감한 정보가 포함된 CI/CD 변수는 보호하고, 마스킹하고, 숨겨야 합니다.

개인 액세스 토큰#

개인 액세스 토큰을 생성해 다음으로 인증할 수 있습니다.

GitLab API.
GitLab 리포지터리.
GitLab 레지스트리.

개인 액세스 토큰의 범위와 만료일을 제한할 수 있습니다. 기본적으로 개인 액세스 토큰은 생성한 사용자의 권한을 상속받습니다.

개인 액세스 토큰 API를 사용해 개인 액세스 토큰 교체와 같은 작업을 프로그래밍 방식으로 수행할 수 있습니다.

개인 액세스 토큰이 곧 만료되면 이메일을 받습니다.

OAuth 2.0 토큰#

GitLab은 OAuth 2.0 공급자 역할을 수행해 다른 서비스가 사용자를 대신해 GitLab API에 액세스하도록 허용할 수 있습니다.

OAuth 2.0 토큰의 범위와 수명을 제한할 수 있습니다.

가장 토큰(Impersonation token)#

가장 토큰의 범위를 제한하고 만료일을 설정할 수 있습니다.

프로젝트 액세스 토큰#

프로젝트 액세스 토큰은 프로젝트 범위로 지정됩니다. 개인 액세스 토큰과 마찬가지로 다음으로 인증하는 데 사용할 수 있습니다.

GitLab API.
GitLab 리포지터리.
GitLab 레지스트리.

프로젝트 액세스 토큰 API를 사용해 프로젝트 액세스 토큰 교체와 같은 작업을 프로그래밍 방식으로 수행할 수 있습니다.

Maintainer 또는 Owner 권한을 가진 프로젝트 멤버는 프로젝트 액세스 토큰이 곧 만료되면 이메일을 받습니다.

그룹 액세스 토큰#

그룹 액세스 토큰은 그룹 범위로 지정됩니다. 개인 액세스 토큰과 마찬가지로 다음으로 인증하는 데 사용할 수 있습니다.

GitLab API.
GitLab 리포지터리.
GitLab 레지스트리.

그룹 액세스 토큰 API를 사용해 그룹 액세스 토큰 교체와 같은 작업을 프로그래밍 방식으로 수행할 수 있습니다.

Owner 권한을 가진 그룹 멤버는 그룹 액세스 토큰이 곧 만료되면 이메일을 받습니다.

배포 토큰#

배포 토큰을 관리하려면 최소 Maintainer 권한을 가진 프로젝트 멤버여야 합니다.

배포 키#

배포 키를 사용하면 가짜 사용자 계정을 설정하지 않고도 지속적 통합 서버로 리포지터리를 클론할 수 있습니다.

프로젝트에 배포 키를 추가하거나 활성화하려면 최소 Maintainer 권한이 있어야 합니다.

러너 인증 토큰#

러너를 등록할 때 러너 등록 토큰 대신 러너 인증 토큰을 사용할 수 있습니다. 러너 등록 토큰은 지원 중단되었습니다.

러너 인증 토큰은 러너 머신에 남아 있습니다. 다음 executor의 실행 환경은 러너 인증 토큰이 아니라 job 토큰에만 액세스할 수 있습니다.

Docker Machine
Kubernetes
VirtualBox
Parallels
SSH

러너 API를 사용해 러너 인증 토큰을 교체하거나 취소할 수 있습니다.

러너 등록 토큰(레거시)#

Warning

CI/CD job 토큰#

GitLab 클러스터 에이전트 토큰#

Kubernetes 용 GitLab 에이전트를 등록하면 GitLab은 클러스터 에이전트를 GitLab에 인증하기 위한 액세스 토큰을 생성합니다.

이 클러스터 에이전트 토큰을 취소하려면 다음 중 하나를 수행합니다.

에이전트 API로 토큰을 취소합니다.
토큰을 재설정합니다.

두 방법 모두 토큰, 에이전트, 프로젝트 ID를 알아야 합니다. 이 정보를 확인하려면 Rails 콘솔을 사용합니다.

# Find token ID
Clusters::AgentToken.find_by_token('glagent-xxx').id

# Find agent ID
Clusters::AgentToken.find_by_token('glagent-xxx').agent.id
=> 1234

# Find project ID
Clusters::AgentToken.find_by_token('glagent-xxx').agent.project_id
=> 12345

Rails 콘솔에서 직접 토큰을 취소할 수도 있습니다.

# Revoke token with RevokeService, including generating an audit event
Clusters::AgentTokens::RevokeService.new(token: Clusters::AgentToken.find_by_token('glagent-xxx'), current_user: User.find_by_username('admin-user')).execute

# Revoke token manually, which does not generate an audit event
Clusters::AgentToken.find_by_token('glagent-xxx').revoke!

기타 토큰#

피드 토큰#

각 사용자는 만료되지 않는 장기 피드 토큰을 가지고 있습니다. 이 토큰을 사용해 다음으로 인증합니다.

RSS 리더 — 개인화된 RSS 피드를 로드합니다.
캘린더 애플리케이션 — 개인화된 캘린더를 로드합니다.

이 토큰으로는 다른 데이터에 액세스할 수 없습니다.

사용자 범위의 피드 토큰은 모든 피드에 사용할 수 있습니다. 다만 피드 및 캘린더 URL은 하나의 피드에만 유효한 별도의 토큰으로 생성됩니다.

피드 토큰을 사용하는 피드#

GitLab은 다음 위치에서 RSS 피드를 제공합니다.

피드 토큰 비활성화#

사전 요구 사항:

관리자여야 합니다.

오른쪽 상단에서 Admin을 선택합니다.
왼쪽 사이드바에서 Settings > General을 선택합니다.
Visibility and access controls를 펼칩니다.
Feed token 아래에서 Disable feed token 체크박스를 선택한 후 Save changes를 선택합니다.

수신 이메일 토큰#

Warning

수신 이메일 토큰 재설정#

오른쪽 상단에서 아바타를 선택합니다.
Edit profile을 선택합니다.
왼쪽 사이드바에서 Access > Personal access tokens를 선택합니다.
Incoming email token 아래에서 reset this token을 선택합니다.

워크스페이스 토큰#

히스토리

GitLab 18.2에서 도입되었습니다.

이 내부 토큰은 직접 보거나 관리할 수 없습니다. 이 토큰으로는 다른 데이터에 액세스할 수 없습니다.

워크스페이스 토큰을 취소하려면 워크스페이스를 stop 또는 terminate합니다. 토큰은 즉시 삭제됩니다.

사용 가능한 범위#

이 표는 토큰별 기본 범위를 보여줍니다. 일부 토큰은 생성할 때 범위를 더 제한할 수 있습니다.

토큰 이름	API 액세스	레지스트리 액세스	리포지터리 액세스
개인 액세스 토큰	✅	✅	✅
OAuth 2.0 토큰	✅	❌	✅
가장 토큰	✅	✅	✅
프로젝트 액세스 토큰	✅¹	✅¹	✅¹
그룹 액세스 토큰	✅²	✅²	✅²
배포 토큰	❌	✅	✅
배포 키	❌	❌	✅
러너 등록 토큰	❌	❌	제한됨³
러너 인증 토큰	❌	❌	제한됨³
Job 토큰	제한됨⁴	❌	✅

토큰 프리픽스#

토큰 이름	프리픽스
개인 액세스 토큰	`glpat-`
OAuth 애플리케이션 시크릿	`gloas-`
가장 토큰	`glpat-`
프로젝트 액세스 토큰	`glpat-`
그룹 액세스 토큰	`glpat-`
배포 토큰	`gldt-`
러너 인증 토큰	`glrt-`, 등록 토큰으로 생성한 경우 `glrtr-`
CI/CD Job 토큰	`glcbt-`
트리거 토큰	`glptt-`
피드 토큰	`glft-`
수신 메일 토큰	`glimt-`
Kubernetes 용 GitLab 에이전트 토큰	`glagent-`
워크스페이스 토큰	`glwt-`(GitLab 18.2에서 추가됨)
GitLab 세션 쿠키	`_gitlab_session=`
SCIM 토큰	`glsoat-`
기능 플래그 클라이언트 토큰	`glffct-`

해당 프로젝트로 제한됩니다. ↩ ↩² ↩³
해당 그룹으로 제한됩니다. ↩ ↩² ↩³
러너 등록 토큰과 인증 토큰은 리포지터리에 직접 액세스할 수 없지만, 리포지터리에 액세스할 수 있는 job을 실행하는 새 러너를 등록하고 인증하는 데 사용할 수 있습니다. ↩ ↩²
특정 엔드포인트만 해당합니다. ↩

GitLab 토큰 개요

보안 고려 사항#

토큰 이름 지정 지침#

CI/CD 에서의 토큰#

개인 액세스 토큰#

OAuth 2.0 토큰#

가장 토큰(Impersonation token)#

프로젝트 액세스 토큰#

그룹 액세스 토큰#

배포 토큰#

배포 키#

러너 인증 토큰#

러너 등록 토큰(레거시)#

CI/CD job 토큰#

GitLab 클러스터 에이전트 토큰#

기타 토큰#

피드 토큰#

피드 토큰을 사용하는 피드#

피드 토큰 비활성화#

수신 이메일 토큰#

수신 이메일 토큰 재설정#

워크스페이스 토큰#

사용 가능한 범위#

토큰 프리픽스#

Footnotes

GitLab 토큰 개요

보안 고려 사항#

토큰 이름 지정 지침#

CI/CD 에서의 토큰#

개인 액세스 토큰#

OAuth 2.0 토큰#

가장 토큰(Impersonation token)#

프로젝트 액세스 토큰#

그룹 액세스 토큰#

배포 토큰#

배포 키#

러너 인증 토큰#

러너 등록 토큰(레거시)#

CI/CD job 토큰#

GitLab 클러스터 에이전트 토큰#

기타 토큰#

피드 토큰#

피드 토큰을 사용하는 피드#

피드 토큰 비활성화#

수신 이메일 토큰#

수신 이메일 토큰 재설정#

워크스페이스 토큰#

사용 가능한 범위#

토큰 프리픽스#

Footnotes