개인 액세스 토큰은 GitLab 에 인증된 접근을 제공합니다. OAuth2 토큰 의 대안이며 그룹 액세스 토큰과 프로젝트 액세스 토큰과 비슷하지만, 그룹이나 프로젝트가 아니라 사용자에 연결됩니다.

개인 액세스 토큰으로 다음에 인증할 수 있습니다:

• GitLab API.
• HTTPS 를 통한 Git. 다음을 사용합니다:
  • 사용자 이름으로는 비어 있지 않은 임의의 값.
  • 비밀번호로는 개인 액세스 토큰.

사용자 이름이 필요한 일부 GitLab 기능은 GitLab 관리형 Terraform 상태 백엔드 와 컨테이너 레지스트리 처럼 GitLab 사용자 이름과 함께 개인 액세스 토큰을 사용합니다. 이런 경우 사용자 이름은 필수이지만 인증의 일부로 평가되지는 않습니다. 자세한 내용은 이슈 212953 을 참고합니다.

GitLab Self-Managed 및 GitLab Dedicated 인스턴스에서는 관리자가 사용자 토큰 API 로 특정 사용자로 인증하는 가장 토큰을 생성할 수 있습니다.

개인 액세스 토큰 만들기#

히스토리

• GitLab 17.6 에서 buffered_token_expiration_limit 이라는 기능 플래그와 함께 최대 허용 수명 한도가 400일로 연장되었습니다. 기본적으로 비활성화되어 있습니다.
• 개인 액세스 토큰 설명이 GitLab 17.7 에서 도입되었습니다.

개인 액세스 토큰을 만들려면 다음을 수행합니다:

1. 오른쪽 위에서 아바타를 선택합니다.
2. Edit profile 을 선택합니다.
3. 왼쪽 사이드바에서 Access > Personal access tokens 를 선택합니다.
4. Generate token 드롭다운 목록에서 Legacy token 을 선택합니다.
5. Token name 에 토큰 이름을 입력합니다.
6. 선택 사항. Token description 에 토큰 설명을 입력합니다.
7. Expiration date 에 토큰 만료 날짜를 입력합니다.
   • 토큰은 그 날짜의 UTC 자정에 만료됩니다.
   • 날짜를 입력하지 않으면 만료 날짜는 오늘부터 365일 후로 설정됩니다.
   • 기본적으로 만료 날짜는 오늘부터 365일을 넘을 수 없습니다. GitLab 17.6 이상에서는 관리자가 액세스 토큰의 최대 수명을 변경할 수 있습니다.
8. 개인 액세스 토큰 스코프 를 하나 이상 선택합니다.
9. Generate token 을 선택합니다.

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

모든 액세스 토큰은 개인 액세스 토큰에 구성된 기본 접두사 설정 을 상속합니다.

개인 액세스 토큰 세부 정보 미리 채우기#

name, description, scopes 매개변수를 URL에 덧붙여 개인 액세스 토큰의 세부 정보를 미리 채울 수 있습니다. 예를 들면 다음과 같습니다.

https://gitlab.example.com/-/user_settings/personal_access_tokens?name=Example+Access+token&description=My+description&scopes=api,read_user

URL에는 유효한 스코프가 하나 이상 포함되어야 합니다. name과 description 매개변수는 URL에서 선택 사항이지만, URL에 토큰 이름이 없으면 생성 양식에 토큰 이름을 입력해야 합니다.

[토큰 보안 고려 사항](../../security/tokens/_index.md#security-considerations) 을 참고합니다.

액세스 토큰으로 인증#

액세스 토큰으로 GitLab REST API, HTTPS 를 통한 Git, GitLab 과 통합되는 서드파티 도구에 인증합니다.

REST API 사용#

PRIVATE-TOKEN 헤더에 토큰을 전달합니다:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects"

자세한 내용은 REST API 인증 을 참고합니다.

HTTPS 를 통한 Git 사용#

Git 이 자격 증명을 요청할 때 토큰을 비밀번호로 사용합니다:

• Username: 비어 있지 않은 아무 문자열(GitLab 은 이 값을 검증하지 않습니다).
• Password: 개인 액세스 토큰.

예를 들면 다음과 같습니다:

git clone https://oauth2:<your_access_token>@gitlab.example.com/gitlab-org/gitlab.git

서드파티 도구 및 IDE 확장 프로그램 사용#

IDE 확장 프로그램, CI/CD 도구, 자동화 스크립트처럼 GitLab 과 통합되는 도구는 인증에 개인 액세스 토큰을 받습니다. 각 도구의 문서에는 필요한 스코프와 토큰을 입력하는 방법이 설명되어 있습니다:

• GitLab CLI (glab)
• GitLab for VS Code 확장 프로그램
• JetBrains IDE 용 GitLab Duo 플러그인
• GitLab for Visual Studio 확장 프로그램
• GitLab for Eclipse
• Neovim 용 GitLab 플러그인

CI/CD 파이프라인에는 CI/CD job 토큰 을 대신 사용하는 것을 권장합니다.

개인 액세스 토큰 보안 안내는 토큰 보안 고려 사항 을 참고합니다.

토큰 사용 정보 보기#

히스토리

• IP 주소를 볼 수 있는 기능이 GitLab 17.8 에서 pat_ip 이라는 기능 플래그와 함께 도입되었습니다. 17.9 에서 기본적으로 활성화되었습니다.
• IP 주소를 볼 수 있는 기능이 GitLab 17.10 에서 일반 공개되었습니다. 기능 플래그 pat_ip 는 제거되었습니다.

개인 액세스 토큰 페이지에는 액세스 토큰에 관한 정보가 표시됩니다.

이 페이지에서 다음 작업을 수행할 수 있습니다:

• 개인 액세스 토큰을 생성하고 교체하고 취소합니다.
• 활성 및 비활성 개인 액세스 토큰 전체를 봅니다.
• 스코프, 부여된 권한, 만료 날짜 등 토큰 정보를 봅니다.
• 사용 날짜와 최근 서로 다른 연결 IP 주소 5개 등 사용 정보를 봅니다.

  [!note] GitLab 은 토큰이 Git 작업을 수행하거나 REST 또는 GraphQL API 로 작업을 인증할 때 토큰 사용 정보를 주기적으로 업데이트합니다. 토큰 사용 시각은 10분마다 업데이트됩니다. 토큰 사용 IP 주소는 1분마다 업데이트됩니다.

개인 액세스 토큰을 보려면 다음을 수행합니다:

1. 오른쪽 위에서 아바타를 선택합니다.
2. Edit profile 을 선택합니다.
3. 왼쪽 사이드바에서 Access > Personal access tokens 를 선택합니다.

토큰 이름을 선택하면 세부 정보 패널이 열립니다. 기본적으로 활성 토큰만 표시됩니다. 검색 바로 액세스 토큰 목록을 필터링합니다.

개인 액세스 토큰 교체#

히스토리

• UI 로 개인 액세스 토큰을 교체하는 기능이 GitLab 17.7 에서 도입되었습니다.
• GitLab 18.1 에서 UI 가 업데이트되었습니다.

토큰을 교체하면 원래 토큰과 같은 권한과 스코프를 가진 새 토큰이 생성됩니다. 원래 토큰은 즉시 비활성 상태가 되고, GitLab 은 감사 목적으로 두 버전을 모두 보관합니다.

개인 액세스 토큰을 교체하려면 다음을 수행합니다:

1. 오른쪽 위에서 아바타를 선택합니다.
2. Edit profile 을 선택합니다.
3. 왼쪽 사이드바에서 Access > Personal access tokens 를 선택합니다.
4. 활성 토큰 옆에서 세로 줄임표(⋮)를 선택합니다.
5. Rotate ([retry]) 를 선택합니다.
6. 확인 대화 상자에서 Rotate 를 선택합니다.

개인 액세스 토큰 취소#

히스토리

• GitLab 18.1 에서 UI 가 업데이트되었습니다.

토큰을 취소하면 즉시 무효화되어 더 이상 사용할 수 없습니다. GitLab 은 감사 목적으로 토큰을 보관합니다. 토큰을 영구적으로 삭제할 수는 없지만, 토큰 목록을 필터링해 활성 토큰만 표시할 수 있습니다.

개인 액세스 토큰을 취소하려면 다음을 수행합니다:

1. 오른쪽 위에서 아바타를 선택합니다.
2. Edit profile 을 선택합니다.
3. 왼쪽 사이드바에서 Access > Personal access tokens 를 선택합니다.
4. 활성 토큰 옆에서 세로 줄임표(⋮)를 선택합니다.
5. Revoke ([remove]) 를 선택합니다.
6. 확인 대화 상자에서 Revoke 를 선택합니다.

액세스 토큰 만료#

개인, 그룹, 프로젝트, 가장(impersonation) 액세스 토큰은 만료 날짜의 UTC 자정에 만료됩니다. 만료된 토큰은 요청을 인증하는 데 더 이상 사용할 수 없으며 다시 활성화할 수 없습니다. 대신 새 토큰을 생성해야 합니다.

기본적으로 새 액세스 토큰에는 만료 날짜가 있어야 합니다. 토큰을 생성할 때 만료 날짜를 명시적으로 설정하지 않으면 현재 날짜로부터 365일 후가 만료 날짜로 적용됩니다. 관리자가 이 요구 사항을 끄면, 만료 날짜 없이 생성한 새 토큰은 만료되지 않습니다. GitLab Ultimate 에서는 관리자가 액세스 토큰의 최대 허용 수명 을 구성할 수 있습니다.

GitLab 버전과 오퍼링에 따라 GitLab 버전을 업그레이드할 때 기존 액세스 토큰에 만료 날짜가 자동으로 적용될 수 있습니다. 자세한 내용은 만료되지 않는 액세스 토큰을 참고합니다.

개인 액세스 토큰 만료 이메일#

히스토리

• 60일 및 30일 만료 알림이 GitLab 17.6 에서 expiring_pats_30d_60d_notifications 이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• 60일 및 30일 알림이 GitLab 17.7 에서 일반 공개되었습니다. 기능 플래그 expiring_pats_30d_60d_notifications 는 제거되었습니다.

GitLab 은 매일 UTC 오전 1시에 곧 만료되는 개인 액세스 토큰을 확인합니다. 사용자는 토큰이 만료되기 7일 전에 이메일로 알림을 받습니다. GitLab 17.6 이상에서는 만료 30일 전과 60일 전에도 알림이 전송됩니다.

개인 액세스 토큰 만료 캘린더#

각 토큰의 만료 날짜에 해당하는 이벤트가 들어 있는 iCalendar 엔드포인트를 구독할 수 있습니다. 로그인한 뒤에는 이 엔드포인트를 /-/user_settings/personal_access_tokens.ics 에서 사용할 수 있습니다.

만료 날짜 없이 서비스 계정 개인 액세스 토큰 만들기#

만료 날짜 없이 서비스 계정용 개인 액세스 토큰을 생성할 수 있습니다. 이러한 개인 액세스 토큰은 만료되지 않습니다.

GitLab.com#

사전 요구 사항:

• 최상위 그룹의 Owner 권한이 있어야 합니다.

1. 상단 바에서 Search or go to 를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > General 을 선택합니다.
3. Permissions and group features 를 확장합니다.
4. Personal access tokens 아래에서 Require expiration dates for service accounts 체크박스를 선택 해제합니다.

이제 만료 날짜 없이 서비스 계정 사용자의 개인 액세스 토큰을 생성할 수 있습니다.

GitLab Self-Managed#

사전 요구 사항:

• GitLab Self-Managed 인스턴스의 관리자여야 합니다.

1. 오른쪽 위에서 Admin 을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General 을 선택합니다.
3. Account and limit 를 확장합니다.
4. Require expiration date for service accounts 체크박스를 선택 해제합니다.

이제 만료 날짜 없이 서비스 계정 사용자의 개인 액세스 토큰을 생성할 수 있습니다.

GitLab Self-Managed Community Edition(CE)에서는 Require expiration date for service accounts 체크박스를 사용할 수 없습니다. 대신 Require expiration date 설정을 사용합니다.

개인 액세스 토큰으로 리포지터리 복제#

SSH 가 비활성화된 상태에서 리포지터리를 복제하려면 다음 명령을 실행해 개인 액세스 토큰으로 복제합니다:

git clone https://<username>:<personal_token>@gitlab.com/gitlab-org/gitlab.git

이 방법은 개인 액세스 토큰을 bash 히스토리에 남깁니다. 이를 피하려면 다음 명령을 실행합니다:

git clone https://<username>@gitlab.com/gitlab-org/gitlab.git

https://gitlab.com 의 비밀번호를 물으면 개인 액세스 토큰을 입력합니다.

clone 명령의 username 은 다음과 같습니다:

• 아무 문자열 값이 될 수 있습니다.
• 빈 문자열이어서는 안 됩니다.

인증에 의존하는 자동화 파이프라인을 설정할 때는 이 점을 기억합니다.

액세스 토큰 비활성화#

히스토리

• GitLab 17.3 에서 Disable access tokens 설정이 도입되었습니다.

사전 요구 사항:

• 관리자 접근 권한.

GitLab 인스턴스 전체에서 사용자가 액세스 토큰으로 인증하지 못하도록 막을 수 있습니다. 이 설정은 개인 액세스 토큰, 그룹 액세스 토큰, 프로젝트 액세스 토큰, 가장 토큰에 영향을 줍니다. 이 설정은 서비스 계정용 개인 액세스 토큰에도 적용됩니다.

액세스 토큰을 비활성화하면 다음 규칙이 적용됩니다:

• 사용자가 개인 액세스 토큰으로 GitLab 에 로그인할 수 없습니다.
• 개인 액세스 토큰 페이지가 404 Not Found 오류를 반환합니다.
• RSS, Atom, 캘린더 피드용 피드 토큰이 동작을 멈춥니다.
• 개인 액세스 토큰으로 인증한 API 요청이 거부됩니다.

인스턴스에서 액세스 토큰을 비활성화하려면 다음을 수행합니다:

1. 오른쪽 위에서 Admin 을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General 을 선택합니다.
3. Account and limit 를 확장합니다.
4. Disable access tokens 체크박스를 선택합니다.
5. Save changes 를 선택합니다.

애플리케이션 설정 API 의 disable_personal_access_tokens 속성 을 사용할 수도 있습니다.

엔터프라이즈 사용자를 위한 개인 액세스 토큰 비활성화#

히스토리

• GitLab 16.11 에서 enterprise_disable_personal_access_tokens 이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab 17.2 에서 GitLab.com 에 활성화되었습니다
• GitLab 17.3 에서 일반 공개되었습니다 . 기능 플래그 enterprise_disable_personal_access_tokens 는 제거되었습니다.

사전 요구 사항:

• 엔터프라이즈 사용자가 속한 그룹의 Owner 권한.

그룹의 엔터프라이즈 사용자 개인 액세스 토큰을 비활성화하면 다음과 같습니다:

• 엔터프라이즈 사용자가 새 개인 액세스 토큰을 생성할 수 없습니다. 이 동작은 엔터프라이즈 사용자가 그룹의 관리자인 경우에도 적용됩니다.
• 엔터프라이즈 사용자의 기존 개인 액세스 토큰이 비활성화됩니다.

엔터프라이즈 사용자의 개인 액세스 토큰을 비활성화하려면 다음을 수행합니다:

1. 상단 바에서 Search or go to 를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > General 을 선택합니다.
3. Permissions and group features 를 확장합니다.
4. Enterprise users 아래에서 Disable personal access tokens 를 선택합니다.
5. Save changes 를 선택합니다.

엔터프라이즈 사용자 계정을 삭제하거나 차단하면 해당 사용자의 개인 액세스 토큰이 자동으로 취소됩니다.

프로그래밍 방식으로 개인 액세스 토큰 만들기#

테스트나 자동화의 일부로 미리 정해 둔 개인 액세스 토큰을 생성할 수 있습니다.

사전 요구 사항:

• GitLab 인스턴스에서 Rails 콘솔 세션 을 실행할 충분한 접근 권한이 필요합니다.

프로그래밍 방식으로 개인 액세스 토큰을 생성하려면 다음을 수행합니다:

1. Rails 콘솔을 엽니다:

   sudo gitlab-rails console
   

2. 다음 명령을 실행해 사용자 이름, 토큰, 스코프를 지정합니다.

   토큰은 20자여야 합니다. 스코프는 유효해야 하며 소스 코드 에서 확인할 수 있습니다.

   예를 들어 사용자 이름이 automation-bot 인 사용자에게 속하고 1년 후에 만료되는 토큰을 생성하려면 다음과 같이 합니다:

   user = User.find_by_username('automation-bot')
   token = user.personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token', expires_at: 365.days.from_now)
   token.set_token('token-string-here123')
   token.save!
   

이 코드는 Rails runner 를 사용해 한 줄 셸 명령으로 줄일 수 있습니다:

sudo gitlab-rails runner "token = User.find_by_username('automation-bot').personal_access_tokens.create(scopes: ['read_user', 'read_repository'], name: 'Automation token', expires_at: 365.days.from_now); token.set_token('token-string-here123'); token.save!"

프로그래밍 방식으로 개인 액세스 토큰 취소#

테스트나 자동화의 일부로 개인 액세스 토큰을 프로그래밍 방식으로 취소할 수 있습니다.

사전 요구 사항:

• GitLab 인스턴스에서 Rails 콘솔 세션 을 실행할 충분한 접근 권한이 필요합니다.

프로그래밍 방식으로 토큰을 취소하려면 다음을 수행합니다:

1. Rails 콘솔을 엽니다:

   sudo gitlab-rails console
   

2. token-string-here123 토큰을 취소하려면 다음 명령을 실행합니다:

   token = PersonalAccessToken.find_by_token('token-string-here123')
   token.revoke!
   

이 코드는 Rails runner 를 사용해 한 줄 셸 명령으로 줄일 수 있습니다:

sudo gitlab-rails runner "PersonalAccessToken.find_by_token('token-string-here123').revoke!"

개인 액세스 토큰과 함께 DPoP 사용#

히스토리

• GitLab 17.10 에서 dpop_authentication 이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.

Demonstrating Proof of Possession(DPoP)은 개인 액세스 토큰의 보안을 강화하고 의도하지 않은 토큰 유출의 영향을 최소화합니다. 계정에서 이 기능을 활성화하면 PAT 가 포함된 모든 REST 및 GraphQL API 요청에 서명된 DPoP 헤더도 함께 제공해야 합니다. 서명된 DPoP 헤더를 만들려면 그에 대응하는 개인 SSH 키가 필요합니다.

사전 요구 사항:

• 계정에 공개 SSH 키를 하나 이상 추가해야 하며, Usage type 은 Signing 또는 Authentication & Signing 이어야 합니다.
  • SSH 키 유형은 RSA 여야 합니다.
• GitLab 계정에 GitLab CLI 를 설치하고 구성해 두어야 합니다.

REST 및 GraphQL API 의 모든 호출에 DPoP 를 요구하려면 다음을 수행합니다:

1. 오른쪽 위에서 아바타를 선택합니다.

2. Edit profile 을 선택합니다.

3. 왼쪽 사이드바에서 Access > Personal access tokens 를 선택합니다.

4. Use Demonstrating Proof of Possession (DPoP) 섹션으로 이동해 Enable DPoP 를 선택합니다.

5. Save changes 를 선택합니다.

6. GitLab CLI 로 DPoP 헤더를 생성하려면 터미널에서 다음 명령을 실행합니다. <your_access_token> 은 액세스 토큰으로, ~/.ssh/id_rsa 는 개인 키의 위치로 바꿉니다:

    glab auth dpop-gen --pat "<your_access_token>" --private-key ~/.ssh/id_rsa
   

CLI 에서 생성한 DPoP 헤더는 다음과 같이 사용할 수 있습니다:

• REST API 와 함께 사용합니다:

  curl --header "PRIVATE-TOKEN: <your_access_token>" \
    --header "DPoP: <dpop-from-glab>" \
    "https://gitlab.example.com/api/v4/projects"
  

• GraphQL 과 함께 사용합니다:

   curl --request POST \
   --header "Content-Type: application/json" \
   --header "PRIVATE-TOKEN: <your_access_token>" \
   --header "DPoP: <dpop-from-glab>" \
   --data '{
   "query": "query { currentUser { id } }"
   }' \
   "https://gitlab.example.com/api/graphql"
  

DPoP 에 관해 자세히 알아보려면 블루프린트 Sender Constraining Personal Access Tokens 를 참고합니다.

개인 액세스 토큰의 대안#

HTTPS 를 통한 Git 에서는 개인 액세스 토큰의 대안으로 OAuth 자격 증명 헬퍼를 사용할 수 있습니다.

CI/CD job 의 인증에는 다음을 고려합니다:

• 파이프라인 인증을 위한 세분화된 권한이 있는 CI/CD job 토큰
• 프로젝트별 자동화를 위한, 필요한 최소 권한만 가진 프로젝트 액세스 토큰

관련 주제#

• 그룹 액세스 토큰
• 프로젝트 액세스 토큰
• 개인 액세스 토큰 API
• 세분화된 개인 액세스 토큰
• Permissions Assistant, 토큰을 생성할 때 세분화된 권한을 선택하도록 도와주는 GitLab Duo 에이전트