세밀한 개인 액세스 토큰

요약

- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated GitLab 18.10에서 베타로 도입됨. GitLab 19.2에서 일반 공급됨. 세밀한 개인 액세스 토큰은 사용자가 정의한 특정 리소스와 권한에만 액세스하도록 범위가 제한됩니다.

세밀한 개인 액세스 토큰#

  - 
  Tier: Free, Premium, Ultimate

- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

History

GitLab 18.10에서 베타로 도입됨.
GitLab 19.2에서 일반 공급됨.

세밀한 개인 액세스 토큰은 사용자가 정의한 특정 리소스와 권한에만 액세스하도록 범위가 제한됩니다. 토큰을 생성할 때 다음 속성을 정의합니다:

리소스: API 작업의 모음입니다. 리소스는 더 큰 범위(Group and project, User, Global)로 그룹화됩니다.
권한: 토큰이 리소스에 대해 수행할 수 있는 특정 작업입니다. 일반적으로 생성(Create), 읽기(Read), 업데이트(Update), 삭제(Delete) 작업을 따릅니다.

세밀한 개인 액세스 토큰 생성#

세밀한 개인 액세스 토큰을 생성하려면:

오른쪽 상단 모서리에서 아바타를 선택합니다.
**프로필 편집(Edit profile)**을 선택합니다.
왼쪽 사이드바에서 액세스(Access) > **개인 액세스 토큰(Personal access tokens)**을 선택합니다.
토큰 생성(Generate token) 드롭다운 목록에서 **세밀한 토큰(Fine-grained token)**을 선택합니다.
이름(Name) 및 설명(Description) 필드를 작성합니다.
만료 날짜(Expiration date) 텍스트 상자에 토큰의 만료 날짜를 입력합니다.

토큰은 해당 날짜의 자정 UTC에 만료됩니다.

날짜를 입력하지 않으면, 만료 날짜는 오늘부터 365일로 설정됩니다.
기본적으로 만료 날짜는 오늘부터 최대 365일을 초과할 수 없습니다. GitLab 17.6 이상에서 관리자는 액세스 토큰의 최대 수명을 수정할 수 있습니다.
그룹 또는 프로젝트 리소스를 추가하는 경우, **그룹 및 프로젝트 액세스(Group and project access)**에서 옵션을 선택합니다.
**리소스 권한 추가(Add resource permissions)**에서:

그룹 및 프로젝트(Group and project), 사용자(User) 또는 전역(Global) 탭을 사용하여 경계별로 리소스를 필터링합니다.

왼쪽 패널에서 하나 이상의 리소스를 선택합니다.
오른쪽 패널에서 각 리소스에 대해 사용 가능한 권한을 선택합니다.
**토큰 생성(Generate token)**을 선택합니다.

개인 액세스 토큰이 표시됩니다. 개인 액세스 토큰을 안전한 곳에 저장하세요. 페이지를 벗어나거나 새로 고침하면 다시 볼 수 없습니다.

sudo로 사용자 가장하기#

관리자는 REST API의 sudo 매개변수를 사용하여 다른 사용자를 가장할 수 있는 세밀한 개인 액세스 토큰을 생성할 수 있습니다.

sudo 기능이 있는 토큰은 관리자만 생성할 수 있습니다. 관리자가 아닌 사용자가 이를 생성하려고 하면 오류가 발생합니다.

세밀한 토큰은 가장하는 동안에도 자체 권한을 계속 적용합니다. 토큰은 다음 두 조건이 모두 참일 때만 작업을 수행할 수 있습니다:

가장 대상 사용자가 해당 작업을 수행할 수 있어야 합니다.
토큰이 해당 작업을 허용하는 권한을 가지고 있어야 합니다.

이 동작은 가장 대상 사용자로서 모든 작업을 수행할 수 있는 sudo 범위를 가진 레거시 개인 액세스 토큰과는 다릅니다.

sudo 기능이 있는 토큰은 모든 사용자로 작동할 수 있습니다. 권한과 경계를 필요한 최소한으로 제한하고 안전하게 저장하십시오.

사용 가능한 세밀한 권한#

세밀한 개인 액세스 토큰이 사용할 수 있는 권한은 토큰이 호출하는 엔드포인트에 따라 달라집니다:

세밀한 개인 액세스 토큰 적용#

History

GitLab 18.11에서 granular_personal_access_tokens_enforcement 및 granular_personal_access_tokens_enforcement_saas라는 이름의 기능 플래그와 함께 도입됨. 기본적으로 비활성화됨.
GitLab 19.2에서 GitLab Self-Managed에 일반 공급됨.

지정된 적용 날짜 이후에 사용자가 세밀한 개인 액세스 토큰을 채택하도록 요구할 수 있습니다. 이 날짜 이후에는 기존 레거시 개인 액세스 토큰이 사용자 프로필에 계속 나열되지만 리소스에 액세스하는 데 사용할 수 없습니다.

적용은 GitLab.com과 GitLab Self-Managed에서 다르게 작동합니다:

GitLab.com에서는 최상위 그룹에 적용되며 모든 하위 그룹 및 프로젝트에 상속됩니다.
GitLab Self-Managed에서는 전체 인스턴스에 적용됩니다.

최상위 그룹에 세밀한 토큰 적용#

필수 조건:

최상위 그룹에 대한 소유자(Owner) 역할이 있어야 합니다.

GitLab.com에서 적용은 그룹과 그 하위 그룹 및 프로젝트에 적용되며, 적용 날짜 이후 레거시 개인 액세스 토큰이 해당 리소스에 액세스하는 것을 차단합니다. 사용자는 여전히 레거시 토큰을 생성할 수 있지만, 해당 토큰은 그룹의 적용된 리소스에 액세스할 수 없습니다.

이 설정은 GitLab Self-Managed에서 사용할 수 없습니다.

세밀한 토큰은 최상위 그룹에만 적용할 수 있습니다.

최상위 그룹에 세밀한 개인 액세스 토큰을 적용하려면:

왼쪽 사이드바에서 **검색 또는 이동(Search or go to)**을 선택하고 그룹을 찾습니다.
설정(Settings) > **일반(General)**을 선택합니다.
**권한 및 그룹 기능(Permissions and group features)**을 확장합니다.
**특정 날짜 이후 세밀한 개인 액세스 토큰 요구(Require fine-grained personal access tokens after a specific date)**를 선택합니다.
미래의 적용 날짜를 입력합니다. 적용 날짜는 협정 세계시(UTC)입니다.
**변경 사항 저장(Save changes)**을 선택합니다.

적용 날짜 이후, 사용자가 레거시 토큰을 사용하여 최상위 그룹, 하위 그룹 또는 프로젝트의 리소스에 액세스하려고 하면 오류가 발생합니다. 오류에는 세밀한 토큰에 필요한 리소스 경계와 권한이 나열됩니다. 예를 들면:

Access denied: This operation requires a fine-grained personal access token with the following project permissions: [Project: Read].

GitLab Self-Managed에 세밀한 토큰 적용#

필수 조건:

관리자여야 합니다.

GitLab Self-Managed에서 적용은 전체 인스턴스에 적용되며, 적용 날짜 이후 사용자가 레거시 개인 액세스 토큰을 생성하거나 순환하는 것을 차단합니다. 사용자는 세밀한 토큰만 생성할 수 있습니다. 기존 레거시 토큰은 만료될 때까지 계속 작동합니다.

인스턴스에 세밀한 개인 액세스 토큰을 적용하려면:

왼쪽 사이드바 하단에서 **관리자(Admin)**를 선택합니다.
설정(Settings) > **일반(General)**을 선택합니다.
**계정 및 제한(Account and limit)**을 확장합니다.
**특정 날짜 이후 세밀한 개인 액세스 토큰 요구(Require fine-grained personal access tokens after a specific date)**를 선택합니다.
**세밀한 개인 액세스 토큰 적용 날짜(Fine-grained personal access tokens enforcement date)**에 미래의 날짜를 입력합니다.
**변경 사항 저장(Save changes)**을 선택합니다.

적용 날짜 이후, 사용자가 레거시 토큰을 생성하거나 순환하려고 하면 오류가 발생합니다.

세밀한 개인 액세스 토큰

GitLab v19.2

원문 보기

번역일: 2026-07-17

요약

세밀한 개인 액세스 토큰#

  - 
  Tier: Free, Premium, Ultimate

- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

History

GitLab 18.10에서 베타로 도입됨.
GitLab 19.2에서 일반 공급됨.

세밀한 개인 액세스 토큰은 사용자가 정의한 특정 리소스와 권한에만 액세스하도록 범위가 제한됩니다. 토큰을 생성할 때 다음 속성을 정의합니다:

리소스: API 작업의 모음입니다. 리소스는 더 큰 범위(Group and project, User, Global)로 그룹화됩니다.
권한: 토큰이 리소스에 대해 수행할 수 있는 특정 작업입니다. 일반적으로 생성(Create), 읽기(Read), 업데이트(Update), 삭제(Delete) 작업을 따릅니다.

세밀한 개인 액세스 토큰 생성#

세밀한 개인 액세스 토큰을 생성하려면:

오른쪽 상단 모서리에서 아바타를 선택합니다.
**프로필 편집(Edit profile)**을 선택합니다.
왼쪽 사이드바에서 액세스(Access) > **개인 액세스 토큰(Personal access tokens)**을 선택합니다.
토큰 생성(Generate token) 드롭다운 목록에서 **세밀한 토큰(Fine-grained token)**을 선택합니다.
이름(Name) 및 설명(Description) 필드를 작성합니다.
만료 날짜(Expiration date) 텍스트 상자에 토큰의 만료 날짜를 입력합니다.

토큰은 해당 날짜의 자정 UTC에 만료됩니다.

날짜를 입력하지 않으면, 만료 날짜는 오늘부터 365일로 설정됩니다.
기본적으로 만료 날짜는 오늘부터 최대 365일을 초과할 수 없습니다. GitLab 17.6 이상에서 관리자는 액세스 토큰의 최대 수명을 수정할 수 있습니다.
그룹 또는 프로젝트 리소스를 추가하는 경우, **그룹 및 프로젝트 액세스(Group and project access)**에서 옵션을 선택합니다.
**리소스 권한 추가(Add resource permissions)**에서:

그룹 및 프로젝트(Group and project), 사용자(User) 또는 전역(Global) 탭을 사용하여 경계별로 리소스를 필터링합니다.

왼쪽 패널에서 하나 이상의 리소스를 선택합니다.
오른쪽 패널에서 각 리소스에 대해 사용 가능한 권한을 선택합니다.
**토큰 생성(Generate token)**을 선택합니다.

개인 액세스 토큰이 표시됩니다. 개인 액세스 토큰을 안전한 곳에 저장하세요. 페이지를 벗어나거나 새로 고침하면 다시 볼 수 없습니다.

sudo로 사용자 가장하기#

관리자는 REST API의 sudo 매개변수를 사용하여 다른 사용자를 가장할 수 있는 세밀한 개인 액세스 토큰을 생성할 수 있습니다.

sudo 기능이 있는 토큰은 관리자만 생성할 수 있습니다. 관리자가 아닌 사용자가 이를 생성하려고 하면 오류가 발생합니다.

세밀한 토큰은 가장하는 동안에도 자체 권한을 계속 적용합니다. 토큰은 다음 두 조건이 모두 참일 때만 작업을 수행할 수 있습니다:

가장 대상 사용자가 해당 작업을 수행할 수 있어야 합니다.
토큰이 해당 작업을 허용하는 권한을 가지고 있어야 합니다.

이 동작은 가장 대상 사용자로서 모든 작업을 수행할 수 있는 sudo 범위를 가진 레거시 개인 액세스 토큰과는 다릅니다.

sudo 기능이 있는 토큰은 모든 사용자로 작동할 수 있습니다. 권한과 경계를 필요한 최소한으로 제한하고 안전하게 저장하십시오.

사용 가능한 세밀한 권한#

세밀한 개인 액세스 토큰이 사용할 수 있는 권한은 토큰이 호출하는 엔드포인트에 따라 달라집니다:

세밀한 개인 액세스 토큰 적용#

History

GitLab 18.11에서 granular_personal_access_tokens_enforcement 및 granular_personal_access_tokens_enforcement_saas라는 이름의 기능 플래그와 함께 도입됨. 기본적으로 비활성화됨.
GitLab 19.2에서 GitLab Self-Managed에 일반 공급됨.

적용은 GitLab.com과 GitLab Self-Managed에서 다르게 작동합니다:

GitLab.com에서는 최상위 그룹에 적용되며 모든 하위 그룹 및 프로젝트에 상속됩니다.
GitLab Self-Managed에서는 전체 인스턴스에 적용됩니다.

최상위 그룹에 세밀한 토큰 적용#

필수 조건:

최상위 그룹에 대한 소유자(Owner) 역할이 있어야 합니다.

이 설정은 GitLab Self-Managed에서 사용할 수 없습니다.

세밀한 토큰은 최상위 그룹에만 적용할 수 있습니다.

최상위 그룹에 세밀한 개인 액세스 토큰을 적용하려면:

왼쪽 사이드바에서 **검색 또는 이동(Search or go to)**을 선택하고 그룹을 찾습니다.
설정(Settings) > **일반(General)**을 선택합니다.
**권한 및 그룹 기능(Permissions and group features)**을 확장합니다.
**특정 날짜 이후 세밀한 개인 액세스 토큰 요구(Require fine-grained personal access tokens after a specific date)**를 선택합니다.
미래의 적용 날짜를 입력합니다. 적용 날짜는 협정 세계시(UTC)입니다.
**변경 사항 저장(Save changes)**을 선택합니다.

Access denied: This operation requires a fine-grained personal access token with the following project permissions: [Project: Read].

GitLab Self-Managed에 세밀한 토큰 적용#

필수 조건:

관리자여야 합니다.

인스턴스에 세밀한 개인 액세스 토큰을 적용하려면:

왼쪽 사이드바 하단에서 **관리자(Admin)**를 선택합니다.
설정(Settings) > **일반(General)**을 선택합니다.
**계정 및 제한(Account and limit)**을 확장합니다.
**특정 날짜 이후 세밀한 개인 액세스 토큰 요구(Require fine-grained personal access tokens after a specific date)**를 선택합니다.
**세밀한 개인 액세스 토큰 적용 날짜(Fine-grained personal access tokens enforcement date)**에 미래의 날짜를 입력합니다.
**변경 사항 저장(Save changes)**을 선택합니다.

적용 날짜 이후, 사용자가 레거시 토큰을 생성하거나 순환하려고 하면 오류가 발생합니다.