프로젝트 접근 토큰

프로젝트 접근 토큰은 비밀번호와 유사하지만, 자원에 대한 접근을 제한하고, 제한된 역할을 선택하며, 만료 날짜를 제공할 수 있습니다.

note
실제 프로젝트에 대한 접근은 역할과 권한 및 토큰 범위의 조합에 의해 제어됩니다.

프로젝트 접근 토큰을 사용하여 인증하세요:

  • GitLab API와 함께.
  • Git에서 HTTP 기본 인증을 사용할 때:
    • 사용자 이름으로 빈 값이 아닌 값을 사용하세요.
    • 비밀번호로 프로젝트 접근 토큰을 사용하세요.

프로젝트 접근 토큰은 그룹 접근 토큰 및 개인 접근 토큰과 유사하지만, 프로젝트 접근 토큰은 특정 프로젝트에 제한되므로 다른 프로젝트의 자원에 접근할 수 없습니다.

자체 관리 인스턴스에서는, 프로젝트 접근 토큰은 제한 사항이 설정된 경우 개인 접근 토큰과 동일한 최대 수명 제한의 적용을 받습니다.

프로젝트 접근 토큰을 사용할 수 있습니다:

  • GitLab SaaS에서: Premium 또는 Ultimate 라이선스 계층이 있는 경우, 시험 라이선스와 함께 하나의 프로젝트 접근 토큰만 사용할 수 있습니다.
  • GitLab의 자체 관리 인스턴스에서: 모든 라이선스 계층으로 사용 가능합니다. Free 계층이 있는 경우, 잠재적인 남용을 줄이기 위해 프로젝트 접근 토큰 비활성화를 고려하세요.

프로젝트 접근 토큰을 사용하여 다른 그룹, 프로젝트 또는 개인 접근 토큰을 생성할 수 없습니다.

프로젝트 접근 토큰은 개인 접근 토큰에 대해 구성된 기본 접두사 설정을 상속합니다.

프로젝트 접근 토큰 생성

  • GitLab 15.1에서 도입, 소유자는 프로젝트 접근 토큰에 대해 소유자 역할을 선택할 수 있습니다.
  • GitLab 15.3에서 도입, UI에 기본 만료 30일 및 기본 역할로 게스트가 채워집니다.
  • 만료되지 않는 프로젝트 접근 토큰 생성 기능이 제거됨 (GitLab 16.0에서).
caution
만료 날짜가 없는 프로젝트 접근 토큰을 생성하는 기능은 사용 중단되었고, 제거됨 (GitLab 16.0에서). 기존 토큰에 추가된 만료 날짜에 대한 자세한 내용은 접근 토큰 만료 문서를 참조하세요.

프로젝트 접근 토큰을 생성하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 접근 토큰을 선택합니다.
  3. 새로운 토큰 추가를 선택합니다.
  4. 이름을 입력합니다. 토큰 이름은 프로젝트를 볼 수 있는 권한이 있는 사용자에게 표시됩니다.
  5. 토큰의 만료 날짜를 입력합니다.
    • 토큰은 그 날짜의 자정 UTC에 만료됩니다. 만료 날짜가 2024-01-01인 토큰은 2024-01-01 00:00:00 UTC에 만료됩니다.
    • 만료 날짜를 입력하지 않으면, 만료 날짜가 현재 날짜보다 30일 후로 자동 설정됩니다.
    • 기본적으로 이 날짜는 현재 날짜보다 최대 365일 후일 수 있습니다.
    • 인스턴스 전체 최대 수명 설정이 자체 관리 인스턴스에서 허용된 최대 수명을 제한할 수 있습니다.
  6. 토큰에 대한 역할을 선택합니다.
  7. 원하는 범위를 선택합니다.
  8. 프로젝트 접근 토큰 생성을 선택합니다.

프로젝트 접근 토큰이 표시됩니다. 프로젝트 접근 토큰을 안전한 곳에 저장하세요. 페이지를 떠나거나 새로 고침하면 다시 볼 수 없습니다.

caution
프로젝트 접근 토큰은 내부 사용자로 취급됩니다. 내부 사용자가 프로젝트 접근 토큰을 생성하면, 그 토큰은 내부로 설정된 가시성 수준이 있는 모든 프로젝트에 접근할 수 있습니다.

프로젝트 액세스 토큰 취소

  • 취소된 토큰을 볼 수 있는 기능이 도입되었습니다. GitLab 17.3에서 retain_resource_access_token_user_after_revoke라는 플래그와 함께 제공됩니다. 기본적으로 비활성화되어 있습니다.

프로젝트 액세스 토큰을 취소하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 액세스 토큰을 선택합니다.
  3. 취소할 프로젝트 액세스 토큰 옆에서 취소( )를 선택합니다.

GitLab 17.3 이상에서 retain_resource_access_token_user_after_revoke 기능 플래그를 활성화하면 액세스 토큰 페이지에서 활성 및 비활성 취소된 프로젝트 액세스 토큰을 모두 볼 수 있습니다. 기능 플래그를 활성화하지 않으면 활성 토큰만 볼 수 있습니다. 비활성 프로젝트 액세스 토큰 테이블:

  • 포함됩니다:
    • 이미 취소되었지만 아직 만료되지 않은 기존 토큰. 이러한 토큰이 만료되면 더 이상 테이블에 표시되지 않습니다.
    • 기능 플래그가 활성화된 이후에 생성되어 취소된 토큰. 이러한 토큰은 만료된 후에도 테이블에 남아 있습니다.
  • 포함되지 않습니다:
    • 이미 만료되었거나 취소된 토큰.
    • 미래에 만료되거나 취소되지 않은 기존 토큰.

프로젝트 액세스 토큰에 대한 범위

  • k8s_proxy 도입되었습니다. GitLab 16.4에서 k8s_proxy_pat라는 플래그와 함께 제공됩니다. 기본적으로 활성화되어 있습니다.
  • 기능 플래그 k8s_proxy_pat 제거되었습니다. GitLab 16.5에서 제거되었습니다.

범위는 프로젝트 액세스 토큰으로 인증할 때 수행할 수 있는 작업을 결정합니다.

참고: 내부 프로젝트에 대한 프로젝트 액세스 토큰 생성 경고를 참조하세요.

범위 설명
api 컨테이너 레지스트리, 의존성 프록시, 패키지 레지스트리를 포함한 스코프 프로젝트 API에 대한 전체 읽기 및 쓰기 액세스를 허용합니다.
read_api 패키지 레지스트리를 포함한 스코프 프로젝트 API에 대한 읽기 액세스를 허용합니다.
read_registry 프로젝트가 비공식이고 인증이 필요한 경우 컨테이너 레지스트리 이미지에 대한 읽기(풀) 액세스를 허용합니다.
write_registry 컨테이너 레지스트리에 대한 쓰기(푸시) 액세스를 허용합니다. 이미지를 푸시하기 위해서는 읽기 및 쓰기 액세스가 모두 필요합니다.
read_repository 리포지토리에 대한 읽기(풀) 액세스를 허용합니다.
write_repository 리포지토리에 대한 읽기 및 쓰기(풀 및 푸시) 액세스를 허용합니다.
create_runner 프로젝트에서 러너를 생성할 수 있는 권한을 허용합니다.
manage_runner 프로젝트에서 러너를 관리할 수 있는 권한을 허용합니다.
ai_features GitLab Duo에 대한 API 작업을 수행할 수 있는 권한을 허용합니다. 이 범위는 JetBrains용 GitLab Duo 플러그인과 함께 작동하도록 설계되었습니다. 모든 다른 확장에 대해서는 범위 요구 사항을 참조하세요.
k8s_proxy 프로젝트의 Kubernetes 에이전트를 사용하여 Kubernetes API 호출을 수행할 수 있는 권한을 허용합니다.

프로젝트 액세스 토큰 생성 활성화 또는 비활성화

상위 그룹의 모든 프로젝트에 대해 프로젝트 액세스 토큰 생성 기능을 활성화하거나 비활성화하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
  2. 설정 > 일반을 선택합니다.
  3. 권한 및 그룹 기능을 확장합니다.
  4. 권한에서 사용자가 이 그룹에서 프로젝트 액세스 토큰 및 그룹 액세스 토큰을 생성할 수 있습니다 체크 박스를 선택하거나 해제합니다.

생성 기능이 비활성화되더라도 기존의 프로젝트 액세스 토큰을 여전히 사용할 수 있으며, 이를 취소할 수 있습니다.

액세스 토큰 만료

기존의 프로젝트 액세스 토큰에 만료 날짜가 자동으로 적용되는지는 귀하의 GitLab offering에 따라 다르며, GitLab 16.0 이상으로 업그레이드한 시기에 따라 달라집니다:

  • GitLab.com에서, 16.0 마일스톤 동안, 만료 날짜가 없는 기존 프로젝트 액세스 토큰은 현재 날짜로부터 365일 후의 만료 날짜가 자동으로 부여되었습니다.
  • GitLab self-managed에서, GitLab 15.11 이하에서 GitLab 16.0 이상으로 업그레이드한 경우:
    • 2024년 7월 23일 이전에는, 만료 날짜가 없는 기존 프로젝트 액세스 토큰은 현재 날짜로부터 365일 후의 만료 날짜가 자동으로 부여되었습니다. 이 변경은 중대한 변경사항입니다.
    • 2024년 7월 24일 이후에는, 만료 날짜가 없는 기존 프로젝트 액세스 토큰은 만료 날짜가 설정되지 않았습니다.

GitLab self-managed에서 다음 GitLab 버전 중 하나를 새로 설치하는 경우, 기존 프로젝트 액세스 토큰에 만료 날짜가 자동으로 적용되지 않습니다:

  • 16.0.9
  • 16.1.7
  • 16.2.10
  • 16.3.8
  • 16.4.6
  • 16.5.9
  • 16.6.9
  • 16.7.9
  • 16.8.9
  • 16.9.10
  • 16.10.9
  • 16.11.7
  • 17.0.5
  • 17.1.3
  • 17.2.1

프로젝트용 봇 사용자

  • GitLab 17.2에서 변경됨 플래그와 함께 retain_resource_access_token_user_after_revoke. 기본적으로 비활성화되어 있습니다. 활성화되면 새로운 봇 사용자는 만료 날짜 없이 구성원으로 추가되며, 토큰이 나중에 취소되거나 만료될 때 봇 사용자가 유지됩니다. 삭제되지 않으며, 기록이 Ghost User로 이동되지 않습니다.

봇 사용자의 동작은 프로젝트 액세스 토큰이 취소된 후 기능 플래그에 의해 제어됩니다. 자세한 내용은 기록을 참조하세요.

프로젝트용 봇 사용자는 GitLab에서 생성한 청구되지 않는 사용자입니다.
프로젝트 액세스 토큰을 생성할 때마다 봇 사용자가 생성되고 프로젝트에 추가됩니다.
이 사용자는 청구되지 않는 사용자이므로 라이센스 제한에 포함되지 않습니다.

프로젝트용 봇 사용자는 프로젝트 액세스 토큰의 선택된 역할 및 범위에 해당하는 권한을 가집니다.

  • 이름은 토큰의 이름으로 설정됩니다.
  • 사용자 이름은 project_{project_id}_bot_{random_string}로 설정됩니다. 예: project_123_bot_4ffca233d8298ea1.
  • 이메일은 project_{project_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}로 설정됩니다. 예: project_123_bot_4ffca233d8298ea1@noreply.example.com.

프로젝트 액세스 토큰으로 수행된 API 호출은 해당 봇 사용자와 연관됩니다.

프로젝트용 봇 사용자는:

  • 프로젝트의 구성원 목록에 포함되지만 수정할 수 없습니다.
    멤버십은 토큰이 만료될 때 만료됩니다.
  • 다른 프로젝트에 추가될 수 없습니다.
  • 프로젝트에 대해 최대 역할이 소유자일 수 있습니다. 자세한 내용은
    프로젝트 액세스 토큰 생성을 참조하세요.

프로젝트 액세스 토큰이 취소되었을 때:

  • 봇 사용자가 삭제됩니다.
  • 모든 기록이 사용자 이름이 Ghost User인 시스템 범위 사용자로 이동됩니다.

또한 그룹용 봇 사용자를 참조하세요.

토큰 가용성

하나 이상의 프로젝트 액세스 토큰은 유료 구독에서만 제공됩니다. 프리미엄 및 얼티밋 체험 구독에서는 하나의 프로젝트 액세스 토큰만 포함됩니다. 자세한 내용은 GitLab 체험 FAQ의 “포함된 항목” 섹션을 참조하세요.