GitLab 프로젝트를 위한 액세스 토큰
요약
이 가이드는 GitLab 프로젝트 내에서 보안 모범 사례를 우선시하여 필요에 맞는 올바른 액세스 토큰 유형을 선택하는 데 도움을 줍니다. 전체 세부 정보는 CI/CD 작업 토큰 문서를 참조하세요. 전체 세부 정보는 프로젝트 액세스 토큰 문서를 참조하세요.
이 가이드는 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+ (Self-managed)
서비스 계정 PAT
수동/API
선택적 프로젝트/그룹 멤버십
이메일 가능
정밀 제어가 있는 다중 프로젝트
Premium+
봇 사용자 PAT
수동만
사용자 수준 권한
수동 설정 필요
레거시/폴백 옵션
모든 티어
각 토큰 유형의 사용 시기#
CI Job Token#
전체 세부 정보는 CI/CD 작업 토큰 문서를 참조하세요.
사용 시기:
- GitLab CI/CD 파이프라인 내에서 실행 중일 때
- 제한된 API 접근만 필요할 때: Git 리포, 컨테이너/패키지 레지스트리, 릴리스, 배포, 환경, 특정 작업/파이프라인 엔드포인트(전체 목록)
- 접근이 파이프라인 지속 시간으로 제한될 때
- 대상 리소스가 동일한 프로젝트에 있거나 적절히 허용 목록에 등록되어 있을 때
제한 사항:
- 대부분의 GitLab API 엔드포인트에 접근 불가 (이슈, 머지 리퀘스트, 사용자, 그룹 등)
- 관리 작업 수행 불가 (토큰 생성이나 사용자 관리 등)
- 외부 API 또는 GitLab 외부 서비스에 접근 불가
피해야 할 경우:
- 전체 GitLab API 접근이 필요한 경우 (이슈, MR, 사용자, 그룹, 관리 작업)
- 파이프라인 컨텍스트 외부에서 지속적인 접근이 필요한 경우
- 외부 시스템 통합을 위한 토큰이 필요한 경우
프로젝트 액세스 토큰#
전체 세부 정보는 프로젝트 액세스 토큰 문서를 참조하세요.
사용 시기:
- 자동화가 단일 프로젝트로 범위가 지정된 경우
- CI/CD 외부에서 지속적인 API 접근이 필요한 경우
- 유지 관리자에게 자동 만료 알림을 원할 때
- 교체를 위해 GitLab API를 통해 관리할 수 있을 때
피해야 할 경우:
- 여러 프로젝트에 대한 접근이 필요한 경우
- 다른 액세스 토큰을 생성해야 하는 경우 (부트스트랩 문제)
- 범위 제한이 필요한 공개 프로젝트 작업 시
그룹 액세스 토큰#
전체 세부 정보는 그룹 액세스 토큰 문서를 참조하세요.
사용 시기:
- 자동화가 소규모의 잘 정의된 그룹에서 여러 프로젝트에 걸쳐 있을 때
- 그룹에 유사한 보안 요구 사항을 가진 제한된 수의 프로젝트가 있을 때
- 그룹 수준 기능에 접근이 필요한 경우
- 교체를 위해 GitLab API를 통해 관리할 수 있을 때
높은 위험 - 신중하게 사용:
- 그룹의 모든 프로젝트에 접근 권한 부여 - 유출 시 엄청난 영향 범위
gitlab-org처럼 수백 개의 프로젝트가 있는 대규모 그룹에서 특히 위험- 더 나은 범위 제어를 위해 대신 서비스 계정 PAT 고려
피해야 할 경우:
- 대규모 그룹(프로젝트 10~20개 이상)으로 작업할 때
- 프로젝트가 다른 보안 요구 사항을 가진 경우
- 더 표적화된 토큰으로 동일한 목표를 달성할 수 있는 경우
서비스 계정 PAT#
전체 세부 정보는 서비스 계정 문서를 참조하세요.
사용 시기:
- 다른 액세스 토큰을 생성/관리해야 할 때 (Terraform 사용 사례)
- 여러 특정 프로젝트 접근이 필요할 때 - 각 프로젝트에 개별적으로 서비스 계정 추가
- 그룹 간 또는 인스턴스 전체 접근이 필요한 경우
- 감사 추적을 위한 적절한 사용자 분리를 원할 때
- 그룹 액세스 토큰의 더 나은 대안 (정밀한 권한 제어)
핵심 장점:
- 세분화된 권한: 최소 필요 역할로 특정 프로젝트/그룹에만 서비스 계정 추가
- 대규모 조직을 위한 그룹 액세스 토큰보다 훨씬 안전
피해야 할 경우:
- 더 간단한 범위 지정 토큰이 요구 사항을 충족하는 경우
- Premium+ 라이선스가 없는 경우
- 조직 수준에서 서비스 계정을 관리할 수 없는 경우
봇 사용자 PAT (레거시)#
전체 세부 정보는 개인 액세스 토큰 문서를 참조하세요.
다음 경우에만 사용:
- 서비스 계정을 사용할 수 없는 경우
- 기존 자동화가 이미 의존하고 있는 경우
- 마이그레이션 중 임시 솔루션
필요한 설정:
- 만료 알림을 위한 공유 이메일 주소 사용
- 교체 절차를 명확히 문서화
- 더 나은 토큰 유형으로의 마이그레이션 계획
보안 모범 사례#
- 가능한 가장 좁은 범위 사용 - 절대적으로 필요하지 않으면
api 범위를 사용하지 않습니다.
- 만료 날짜 설정 - 토큰 수명을 365일 이내로 유지합니다.
- 토큰을 안전하게 저장 - GitLab CI/CD 변수(마스킹), vault 시스템 또는 자격 증명 관리자를 사용합니다.
- 만료 날짜 모니터링 - 알림과 교체 절차를 설정합니다.
관련 문서#