프로젝트 액세스 토큰
프로젝트 액세스 토큰은 특정 프로젝트에 대한 인증된 액세스를 제공합니다. 프로젝트 액세스 토큰을 사용하여 다음을 인증할 수 있습니다: GitLab.com에서 프로젝트 액세스 토큰은 Premium 또는 Ultimate 구독이 필요합니다.
히스토리
- GitLab 16.1에서 평가판 구독을 위해 도입되었습니다.
프로젝트 액세스 토큰은 특정 프로젝트에 대한 인증된 액세스를 제공합니다. 그룹 액세스 토큰 및 개인 액세스 토큰과 유사하지만, 그룹이나 사용자가 아닌 연결된 프로젝트로 범위가 제한됩니다. 프로젝트 액세스 토큰을 사용하여 다른 프로젝트의 리소스에 액세스하거나 다른 그룹, 프로젝트 또는 개인 액세스 토큰을 생성할 수 없습니다.
프로젝트 액세스 토큰을 사용하여 다음을 인증할 수 있습니다:
- GitLab API
- HTTPS를 통한 Git. 다음을 사용합니다:
- 비어 있지 않은 임의의 값을 사용자 이름으로.
- 프로젝트 액세스 토큰을 비밀번호로.
사전 요건:
- 프로젝트에 대한 Maintainer 또는 Owner 역할.
GitLab.com에서 프로젝트 액세스 토큰은 Premium 또는 Ultimate 구독이 필요합니다. 평가판 기간 동안 프로젝트 액세스 토큰은 하나로 제한됩니다.
GitLab Self-Managed 및 GitLab Dedicated에서는 모든 라이선스로 프로젝트 액세스 토큰을 사용할 수 있습니다.
액세스 토큰 보기#
히스토리
- GitLab 16.0 이전에는 토큰 사용 정보가 24시간마다 업데이트됩니다.
- GitLab 16.1에서 토큰 사용 정보 업데이트 빈도가 24시간에서 10분으로 변경되었습니다.
- GitLab 17.8에서
pat_ip라는 플래그와 함께 IP 주소 보기 기능이 도입되었습니다. 17.9에서 기본적으로 활성화되었습니다. - GitLab 17.10에서 IP 주소 보기 기능이 일반적으로 사용 가능하게 되었습니다. 기능 플래그
pat_ip가 제거되었습니다.
프로젝트 액세스 토큰 페이지에는 액세스 토큰에 대한 정보가 표시됩니다.
이 페이지에서 다음 작업을 수행할 수 있습니다:
- 프로젝트 액세스 토큰 생성, 교체 및 취소.
- 모든 활성 및 비활성 프로젝트 액세스 토큰 보기.
- 범위, 할당된 역할, 만료 날짜를 포함한 토큰 정보 보기.
- 사용 날짜 및 마지막 5개의 고유 연결 IP 주소를 포함한 사용 정보 보기.
[!note] GitLab은 토큰이 Git 작업을 수행하거나 REST 또는 GraphQL API로 작업을 인증할 때 주기적으로 토큰 사용 정보를 업데이트합니다. 토큰 사용 시간은 10분마다, 토큰 사용 IP 주소는 1분마다 업데이트됩니다.
프로젝트 액세스 토큰을 보려면:
- 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
- 왼쪽 사이드바에서 Settings > Access tokens를 선택합니다.
활성 및 사용 가능한 액세스 토큰은 Active project access tokens 섹션에 저장됩니다. 만료, 교체 또는 취소된 토큰은 Inactive project access tokens 섹션에 저장됩니다.
프로젝트 액세스 토큰 생성#
히스토리
연장된 최대 허용 수명 제한의 가용성은 기능 플래그로 제어됩니다. 자세한 내용은 히스토리를 참조하십시오.
프로젝트 액세스 토큰을 생성하려면:
- 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
- 왼쪽 사이드바에서 Settings > Access tokens를 선택합니다.
- Add new token을 선택합니다.
- Token name에 이름을 입력합니다. 토큰 이름은 프로젝트를 볼 수 있는 권한을 가진 모든 사용자에게 표시됩니다.
- 선택사항. Token description에 토큰에 대한 설명을 입력합니다.
- Expiration date에 토큰의 만료 날짜를 입력합니다.
- 토큰은 해당 날짜 자정 UTC에 만료됩니다.
- 날짜를 입력하지 않으면 만료 날짜는 오늘로부터 365일로 설정됩니다.
- 기본적으로 만료 날짜는 오늘로부터 365일을 초과할 수 없습니다. GitLab 17.6 이상에서 관리자는 액세스 토큰의 최대 수명을 수정할 수 있습니다.
- 토큰의 역할을 선택합니다.
- 하나 이상의 프로젝트 액세스 토큰 범위를 선택합니다.
- Create project access token을 선택합니다.
프로젝트 액세스 토큰이 표시됩니다. 프로젝트 액세스 토큰을 안전한 곳에 저장하십시오. 페이지를 떠나거나 새로 고침하면 다시 볼 수 없습니다.
모든 프로젝트 액세스 토큰은 개인 액세스 토큰에 대해 구성된 기본 접두사 설정을 상속합니다.
프로젝트 액세스 토큰은 내부 사용자로 취급됩니다. 내부 사용자가 프로젝트 액세스 토큰을 생성하면, 해당 토큰은 가시성 수준이 Internal로 설정된 모든 프로젝트에 액세스할 수 있습니다.
프로젝트 액세스 토큰 범위#
히스토리
범위는 프로젝트 액세스 토큰으로 인증할 때 사용 가능한 작업을 정의합니다.
| 범위 | 설명 |
|---|---|
api |
컨테이너 레지스트리, 의존성 프록시, 패키지 레지스트리를 포함한 범위가 지정된 프로젝트 API에 대한 완전한 읽기 및 쓰기 액세스를 부여합니다. |
read_api |
패키지 레지스트리를 포함한 범위가 지정된 프로젝트 API에 대한 읽기 액세스를 부여합니다. |
read_registry |
프로젝트가 비공개이고 인증이 필요한 경우 컨테이너 레지스트리 이미지에 대한 읽기 액세스(pull)를 부여합니다. 컨테이너 레지스트리가 활성화된 경우에만 사용할 수 있습니다. |
write_registry |
컨테이너 레지스트리에 대한 쓰기 액세스(push)를 부여합니다. 이미지를 push하려면 read_registry 범위를 포함해야 합니다. 컨테이너 레지스트리가 활성화된 경우에만 사용할 수 있습니다. |
read_repository |
프로젝트의 저장소에 대한 읽기 액세스(pull)를 부여합니다. |
write_repository |
프로젝트의 저장소에 대한 읽기 및 쓰기 액세스(pull 및 push)를 부여합니다. |
create_runner |
프로젝트에서 러너를 생성할 수 있는 권한을 부여합니다. |
manage_runner |
프로젝트에서 러너를 관리할 수 있는 권한을 부여합니다. |
ai_features |
GitLab Duo, Code Suggestions API, GitLab Duo Chat API에 대한 API 작업을 수행할 수 있는 권한을 부여합니다. JetBrains용 GitLab Duo Plugin과 함께 작동하도록 설계되었습니다. 다른 모든 확장의 경우 각 확장 문서를 참조하십시오. GitLab Self-Managed 버전 16.5, 16.6, 16.7에서는 작동하지 않습니다. GitLab Self-Managed 및 GitLab Dedicated에서는 GitLab Duo가 활성화된 경우에만 이 범위를 사용할 수 있습니다. |
k8s_proxy |
프로젝트의 Kubernetes 에이전트를 사용하여 Kubernetes API 호출을 수행할 수 있는 권한을 부여합니다. |
self_rotate |
개인 액세스 토큰 API를 사용하여 이 토큰을 교체할 수 있는 권한을 부여합니다. 다른 토큰의 교체는 허용하지 않습니다. |
외부 인증을 활성화한 경우 개인 액세스 토큰은 컨테이너 또는 패키지 레지스트리에 액세스할 수 없습니다. 액세스를 복원하려면 외부 인증을 비활성화하십시오.
프로젝트 액세스 토큰 교체#
히스토리
- GitLab 17.3에서
retain_resource_access_token_user_after_revoke라는 플래그와 함께 만료 및 취소된 토큰 보기 기능이 도입되었습니다. 기본적으로 비활성화되어 있습니다. - GitLab 17.9에서 자동 삭제 전까지 만료 및 취소된 토큰 보기 기능이 일반적으로 사용 가능하게 되었습니다. 기능 플래그
retain_resource_access_token_user_after_revoke가 제거되었습니다.
토큰을 교체하면 원래 토큰과 동일한 권한 및 범위를 가진 새 토큰이 생성됩니다. 원래 토큰은 즉시 비활성화되고, GitLab은 감사 목적으로 두 버전을 모두 보유합니다. 액세스 토큰 페이지에서 활성 및 비활성 토큰을 모두 볼 수 있습니다.
GitLab Self-Managed 및 GitLab Dedicated에서는 비활성 토큰에 대한 보존 기간을 수정할 수 있습니다.
이 작업은 취소할 수 없습니다. 교체된 액세스 토큰에 의존하는 도구는 새 토큰을 참조할 때까지 작동하지 않습니다.
프로젝트 액세스 토큰을 교체하려면:
- 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
- 왼쪽 사이드바에서 Settings > Access tokens를 선택합니다.
- 해당 토큰에 대해 Rotate ([retry])를 선택합니다.
- 확인 대화 상자에서 Rotate를 선택합니다.
프로젝트 액세스 토큰 취소#
히스토리
- GitLab 17.3에서
retain_resource_access_token_user_after_revoke라는 플래그와 함께 만료 및 취소된 토큰 보기 기능이 도입되었습니다. 기본적으로 비활성화되어 있습니다. - GitLab 17.9에서 자동 삭제 전까지 만료 및 취소된 토큰 보기 기능이 일반적으로 사용 가능하게 되었습니다. 기능 플래그
retain_resource_access_token_user_after_revoke가 제거되었습니다.
토큰을 취소하면 즉시 무효화되고 더 이상 사용할 수 없습니다. 취소된 토큰은 즉시 삭제되지 않지만 활성 토큰만 표시하도록 토큰 목록을 필터링할 수 있습니다. 기본적으로 GitLab은 취소된 그룹 및 프로젝트 액세스 토큰을 30일 후에 삭제합니다. 자세한 내용은 비활성 토큰 보존을 참조하십시오.
이 작업은 취소할 수 없습니다. 취소된 액세스 토큰에 의존하는 도구는 새 토큰을 추가할 때까지 작동하지 않습니다.
프로젝트 액세스 토큰을 취소하려면:
- 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
- 왼쪽 사이드바에서 Settings > Access tokens를 선택합니다.
- 해당 토큰에 대해 Revoke ([remove])를 선택합니다.
- 확인 대화 상자에서 Revoke를 선택합니다.
액세스 토큰 만료#
개인, 그룹, 프로젝트 액세스 토큰은 만료 날짜의 UTC 자정에 만료됩니다. 만료된 후에는 더 이상 요청 인증에 사용할 수 없습니다.
GitLab 16.0 이상에서는 새 액세스 토큰에 반드시 만료 날짜가 있어야 합니다. 토큰 생성 시 만료 날짜를 명시적으로 설정하지 않으면 현재 날짜로부터 365일 후의 만료 날짜가 자동으로 적용됩니다. GitLab Ultimate에서 관리자는 액세스 토큰의 최대 허용 수명을 구성할 수 있습니다.
GitLab 버전 업그레이드 시 기존 액세스 토큰에 만료 날짜가 자동으로 적용될 수 있습니다. 자세한 내용은 만료 날짜 없는 액세스 토큰을 참조하세요.
프로젝트 액세스 토큰 만료 이메일#
히스토리
- GitLab 17.6에서
expiring_pats_30d_60d_notifications라는 플래그와 함께 60일 및 30일 만료 알림이 도입되었습니다. 기본적으로 비활성화되어 있습니다. - GitLab 17.7에서 60일 및 30일 알림이 일반적으로 사용 가능하게 되었습니다. 기능 플래그
expiring_pats_30d_60d_notifications가 제거되었습니다. - GitLab 17.7에서
pat_expiry_inherited_members_notification이라는 플래그와 함께 상속된 그룹 구성원에 대한 알림이 도입되었습니다. 기본적으로 비활성화되어 있습니다. - GitLab 17.10에서 기능 플래그
pat_expiry_inherited_members_notification이 기본적으로 활성화되었습니다. - GitLab
17.11에서 기능 플래그pat_expiry_inherited_members_notification이 제거되었습니다.
GitLab은 매일 UTC 오전 1시에 곧 만료되는 프로젝트 액세스 토큰을 식별하는 점검을 실행합니다. Maintainer 또는 Owner 역할을 가진 직접 멤버는 토큰 만료 7일 전에 이메일로 알림을 받습니다. GitLab 17.6 이상에서는 토큰 만료 30일 및 60일 전에도 알림이 전송됩니다.
GitLab 17.7 이상에서는 상속된 Maintainer 또는 Owner 역할을 가진 멤버도 이러한 이메일을 받을 수 있습니다. 이는 GitLab 인스턴스 또는 특정 상위 그룹에서 구성할 수 있습니다. 상위 그룹에 적용된 경우 이 설정은 모든 하위 그룹 및 프로젝트에 상속됩니다.
만료된 토큰은 자동 삭제될 때까지 비활성 프로젝트 액세스 토큰 섹션에 표시됩니다. GitLab Self-Managed에서는 이 보존 기간을 수정할 수 있습니다.
프로젝트의 봇 사용자#
히스토리
- GitLab 17.2에서
retain_resource_access_token_user_after_revoke라는 플래그와 함께 변경되었습니다. 기본적으로 비활성화되어 있습니다. 활성화되면 새 봇 사용자가 만료 날짜 없이 멤버로 추가되고, 나중에 토큰이 취소되거나 만료되면 봇 사용자는 30일 동안 보존됩니다. - GitLab 17.9에서 비활성 봇 사용자 보존이 일반적으로 사용 가능하게 되었습니다. 기능 플래그
retain_resource_access_token_user_after_revoke가 제거되었습니다.
프로젝트 액세스 토큰을 생성하면 GitLab은 봇 사용자를 생성하고 해당 토큰과 연결합니다.
봇 사용자의 속성은 다음과 같습니다:
- 연결된 액세스 토큰의 역할 및 범위에 해당하는 권한이 부여됩니다.
- 프로젝트의 멤버이지만 프로젝트에서 제거하거나 다른 그룹이나 프로젝트에 직접 추가할 수 없습니다.
- 청구되지 않는 사용자이며 라이선스 한도에 포함되지 않습니다.
- 기여는 봇 사용자 계정과 연결됩니다.
- 제거되면 기여가 ghost 사용자로 이동됩니다.
봇 사용자가 생성될 때 다음 속성이 정의됩니다:
| 속성 | 값 | 예시 |
|---|---|---|
| 이름 | 연결된 액세스 토큰의 이름. | Main token - Read registry |
| 사용자 이름 | 이 형식으로 생성됨: 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 |
프로젝트 액세스 토큰 생성 제한#
잠재적인 남용을 제한하기 위해 사용자가 최상위 그룹의 프로젝트에 대한 액세스 토큰을 생성하는 것을 제한할 수 있습니다. 기존 토큰은 만료되거나 수동으로 취소될 때까지 유효합니다.
자세한 내용은 그룹 및 프로젝트 액세스 토큰 생성 제한을 참조하십시오.