GitLab 프로젝트를 위한 액세스 토큰
GitLab v19.5요약
이 가이드는 GitLab 프로젝트 안에서 보안 모범 사례를 우선하여 필요에 맞는 액세스 토큰 유형을 선택하도록 돕습니다. 자세한 내용은 CI/CD job 토큰 문서를 참고합니다. 다음과 같은 경우에는 사용하지 않습니다.
이 가이드는 GitLab 프로젝트 안에서 보안 모범 사례를 우선하여 필요에 맞는 액세스 토큰 유형을 선택하도록 돕습니다.
보안 원칙#
- 수동 교체 최소화 - 자동으로 또는 API로 교체되는 토큰을 우선합니다
- 가능한 한 좁은 범위 - 필요를 충족하는 가장 제한적인 범위를 사용합니다
- 만료 가시성 - 토큰 만료 전에 적절한 알림이 전달되도록 합니다
- 손쉬운 교체 - 큰 다운타임 없이 교체할 수 있는 토큰을 선택합니다
결정 트리#
Mermaid 다이어그램 (36줄)
소스 코드 보기
flowchart TD
A[Need GitLab API Access?] --> B{Running in CI/CD pipeline?}
B -->|Yes| C{Need only limited API access?<br/>Git repos, packages, releases,<br/>specific endpoints}
C -->|Yes| D[CI Job Token<br/>Auto-rotates<br/>No manual management<br/>Limited API endpoints only]
C -->|No| E{Access to multiple projects?}
E -->|No| F[Project Access Token<br/>Single project scope<br/>Full API access<br/>Email notifications]
E -->|Yes| G[Service Account PAT<br/>Add to specific projects only<br/>Precise permission control<br/>API manageable]
B -->|No| H{Single Project Only?}
H -->|Yes| I{Need administrative actions<br/>like creating tokens?}
I -->|No| J[Project Access Token<br/>Scoped to one project<br/>Email notifications<br/>API manageable]
I -->|Yes| K[Service Account PAT<br/>Admin permissions possible<br/>Add to specific project<br/>Better than Group token]
H -->|No| L{Multiple projects needed?}
L -->|Yes| M{Large group with many projects<br/>like gitlab-org?}
M -->|Yes| N[Service Account PAT<br/>Add to specific projects only<br/>Avoid overpermissive group tokens<br/>Granular control]
M -->|No| O{Small, well-defined group?}
O -->|Yes| P[Consider Group Access Token<br/>Only for small groups<br/>High privilege risk]
O -->|No| Q[Service Account PAT<br/>Selective project membership<br/>Better security boundary]
L -->|No| R{Can create Service Account?}
R -->|Yes| S[Service Account PAT<br/>API manageable<br/>Proper user separation<br/>Precise permissions]
R -->|No| T[Bot User PAT<br/>Manual rotation required<br/>Use shared email for notifications<br/>Last resort option]
style D fill:#d4f6d4
style F fill:#d4f6d4
style G fill:#d4f6d4
style J fill:#d4f6d4
style K fill:#d4f6d4
style N fill:#d4f6d4
style Q fill:#d4f6d4
style S fill:#d4f6d4
style P fill:#fff3cd
style T fill:#ffe6e6</code></pre></details></div>
토큰 유형 비교#
토큰 유형
교체
범위 유연성
가시성
최적 사용 사례
가용성
CI Job Token
자동
매우 제한적(특정 엔드포인트만)
기본 제공 로그
제한된 파이프라인 API 접근
모든 티어
프로젝트 액세스 토큰
수동/API
단일 프로젝트
이메일 알림
단일 프로젝트 자동화
Premium+
그룹 액세스 토큰
수동/API
그룹 + 하위 그룹/프로젝트 (높은 위험)
이메일 알림
드물게 권장 - 대신 서비스 계정 사용
Free+ (GitLab Self-Managed)
서비스 계정 PAT
수동/API
선택적 프로젝트/그룹 멤버십
이메일 가능
정밀 제어가 있는 다중 프로젝트
Free+ (CE 제외)
봇 사용자 PAT
수동만
사용자 수준 권한
수동 설정 필요
레거시/폴백 옵션
모든 티어
각 토큰 유형의 사용 시기#
CI Job Token#
자세한 내용은 CI/CD job 토큰 문서를 참고합니다.
다음과 같은 경우에 사용합니다.
- GitLab CI/CD 파이프라인 안에서 실행하는 경우
- 제한된 API 접근만 필요한 경우: Git 리포지터리, 컨테이너/패키지 레지스트리, 릴리스, 배포, 환경, 특정 job/파이프라인 엔드포인트(전체 목록)
- 접근이 파이프라인 실행 시간으로 제한되는 경우
- 대상 리소스가 같은 프로젝트에 있거나 적절히 허용 목록에 등록된 경우
제한 사항:
- 대부분의 GitLab API 엔드포인트(이슈, 머지 리퀘스트, 사용자, 그룹 등)에 접근할 수 없습니다
- 토큰 생성이나 사용자 관리 같은 관리 작업을 수행할 수 없습니다
- GitLab 외부의 API 나 서비스에 접근할 수 없습니다
다음과 같은 경우에는 사용하지 않습니다.
- GitLab API 전체 접근(이슈, MR, 사용자, 그룹, 관리 작업)이 필요한 경우
- 파이프라인 컨텍스트 밖에서 지속적인 접근이 필요한 경우
- 외부 시스템 연동을 위한 토큰이 필요한 경우
프로젝트 액세스 토큰#
자세한 내용은 프로젝트 액세스 토큰 문서를 참고합니다.
다음과 같은 경우에 사용합니다.
- 자동화 범위가 단일 프로젝트로 한정되는 경우
- CI/CD 밖에서 지속적인 API 접근이 필요한 경우
- Maintainer에게 만료 알림이 자동으로 전달되기를 원하는 경우
- 교체를 GitLab API로 관리할 수 있는 경우
다음과 같은 경우에는 사용하지 않습니다.
- 여러 프로젝트에 접근해야 하는 경우
- 다른 액세스 토큰을 생성해야 하는 경우(부트스트래핑 문제)
- 범위 제한이 필요한 공개 프로젝트에서 작업하는 경우
그룹 액세스 토큰#
자세한 내용은 그룹 액세스 토큰 문서를 참고합니다.
다음과 같은 경우에 사용합니다.
- 자동화가 작고 명확하게 정의된 그룹 안의 여러 프로젝트에 걸치는 경우
- 그룹에 보안 요구 사항이 비슷한 소수의 프로젝트만 있는 경우
- 그룹 수준 기능에 접근해야 하는 경우
- 교체를 GitLab API로 관리할 수 있는 경우
높은 위험 - 제한적으로 사용:
- 그룹 안 모든 프로젝트에 대한 접근을 부여하므로, 유출되면 영향 범위가 매우 큽니다
- 수백 개의 프로젝트가 있는
gitlab-org 같은 대규모 그룹에서는 특히 위험합니다
- 범위를 더 잘 제어하려면 서비스 계정 PAT를 대신 고려합니다
다음과 같은 경우에는 사용하지 않습니다.
- 대규모 그룹(프로젝트 10~20개 초과)에서 작업하는 경우
- 프로젝트마다 보안 요구 사항이 다른 경우
- 더 좁게 지정된 토큰으로 같은 목표를 달성할 수 있는 경우
서비스 계정 PAT#
자세한 내용은 서비스 계정 문서를 참고합니다.
다음과 같은 경우에 사용합니다.
- 다른 액세스 토큰을 생성하거나 관리해야 하는 경우(Terraform 사용 사례)
- 여러 특정 프로젝트에 접근해야 하는 경우 - 서비스 계정을 각 프로젝트에 개별로 추가합니다
- 그룹을 넘나들거나 인스턴스 전체 접근이 필요한 경우
- 감사 추적을 위해 사용자 분리를 명확히 하려는 경우
- 정밀한 권한 제어를 위해 그룹 액세스 토큰보다 나은 대안이 필요한 경우
핵심 장점:
- 세분화된 권한. 서비스 계정을 최소 필요 권한으로 특정 프로젝트나 그룹에만 추가합니다
- 대규모 조직에서는 그룹 액세스 토큰보다 훨씬 안전합니다
다음과 같은 경우에는 사용하지 않습니다.
- 더 단순한 범위 제한 토큰으로 요구 사항을 충족할 수 있는 경우
- 서비스 계정을 사용할 수 없는 GitLab Community Edition(CE)을 실행하는 경우
- 조직 수준에서 서비스 계정을 관리할 수 없는 경우
봇 사용자 PAT(레거시)#
자세한 내용은 개인 액세스 토큰 문서를 참고합니다.
다음과 같은 경우에만 사용합니다.
- 서비스 계정을 사용할 수 없는 경우
- 기존 자동화가 이미 이 방식에 의존하는 경우
- 마이그레이션 기간의 임시 해결책이 필요한 경우
필요한 설정:
- 만료 알림을 위해 공유 이메일 주소를 사용합니다
- 교체 절차를 명확하게 문서화합니다
- 더 나은 토큰 유형으로의 마이그레이션을 계획합니다
보안 모범 사례#
- 가능한 한 좁은 범위를 사용합니다 - 꼭 필요한 경우가 아니면
api 범위를 사용하지 않습니다
- 만료일을 설정합니다 - 토큰 수명을 365일 이내로 유지합니다
- 토큰을 안전하게 저장합니다 - GitLab CI/CD 변수(마스킹), 볼트 시스템, 자격 증명 관리자를 사용합니다
- 만료일을 모니터링합니다 - 알림과 교체 절차를 마련합니다
관련 문서#