개인 액세스 토큰

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-Managed, GitLab Dedicated

개인 액세스 토큰은 OAuth2 대안으로 사용되며 다음과 같은 목적으로 사용될 수 있습니다:

  • GitLab API에서 인증.
  • HTTP 기본 인증을 사용하여 Git과 인증.

두 경우 모두 암호 대신 개인 액세스 토큰으로 인증합니다.

caution
만료일이 지정되지 않은 개인 액세스 토큰 생성 기능은 GitLab 15.4에서 사용 중단되었으며 GitLab 16.0에서 제거되었습니다. GitLab 16.0 이후, 만료일이 지정되지 않은 기존 개인 액세스 토큰은 자동으로 현재 날짜보다 365일 뒤의 만료일이 지정됩니다. 만료일이 자동으로 추가는 GitLab.com의 경우 16.0 마일스톤에서 이루어집니다. Self-Managed 인스턴스가 GitLab 16.0으로 업그레이드되는 경우에도 만료일이 자동으로 추가됩니다. 이 변경은 파기 변경사항입니다.

개인 액세스 토큰은:

note
개인 액세스 토큰을 사용하여 인증하는 경우 GitLab 사용자 이름은 무시됩니다. GitLab이 사용자 이름을 사용하도록 하는 issue가 있습니다.

개인 액세스 토큰을 사용하여 API에 대해 인증하는 방법의 예제는 API 문서를 참조하세요.

대안으로, GitLab 관리자는 가장하게 하는 토큰을 만들기 위해 API를 사용할 수 있습니다. 가장하게 하는 토큰을 사용하여 특정 사용자로의 인증을 자동화할 수 있습니다.

개인 액세스 토큰 생성

  • GitLab 15.3에서 도입되었으며, 기본 만료 기간으로 30일이 UI에 표시됩니다.
  • GitLab 16.0에서 만료되지 않는 개인 액세스 토큰 생성 기능이 제거되었습니다.

원하는 만큼 많은 개인 액세스 토큰을 생성할 수 있습니다.

  1. 왼쪽 사이드바에서 아바타를 선택하세요.
  2. 프로필 편집을 선택하세요.
  3. 왼쪽 사이드바에서 액세스 토큰을 선택하세요.
  4. 새 토큰 추가를 선택하세요.
  5. 토큰의 이름과 만료일을 입력하세요.
    • 해당 날짜에 토큰이 UTC 자정에 만료됩니다.
    • 만료일을 입력하지 않으면, 만료일이 자동으로 현재 날짜보다 365일 뒤로 설정됩니다.
    • 기본적으로, 날짜는 현재 날짜보다 최대 365일 뒤로 지정될 수 있습니다.
  6. 원하는 범위를 선택하세요.
  7. 개인 액세스 토큰 만들기을 선택하세요.

개인 액세스 토큰을 안전한 곳에 저장하세요. 페이지를 떠나면, 더 이상 토큰에 액세스할 수 없습니다.

개인 액세스 토큰 이름 및 범위 미리 채우기

개인 액세스 토큰 페이지로 직접 연결하고 이름 및 범위 디렉터리을 미리 채울 수 있습니다. 이를 위해 URL에 name 매개변수와 쉼표로 구분된 범위 디렉터리을 추가할 수 있습니다. 예를 들어:

https://gitlab.example.com/-/user_settings/personal_access_tokens?name=Example+Access+token&scopes=api,read_user,read_repository
caution
개인 액세스 토큰은 신중하게 다뤄져야 합니다. 개인 액세스 토큰을 관리하는데 대한 안내는 토큰 보안 고려 사항을 읽어보세요 (예: 짧은 만료 기간 설정 및 최소한의 범위 사용).

개인 액세스 토큰 취소

언제든지 개인 액세스 토큰을 취소할 수 있습니다.

  1. 왼쪽 사이드바에서 아바타를 선택하세요.
  2. 프로필 편집을 선택하세요.
  3. 왼쪽 사이드바에서 액세스 토큰을 선택하세요.
  4. 활성 개인 액세스 토큰 영역에서 해당 토큰의 취소를 선택하세요.
  5. 확인 대화상자에서 취소를 선택하세요.

개인 액세스 토큰 비활성화

Tier: Premium, Ultimate Offering: Self-Managed, GitLab Dedicated

필수 사항:

  • 관리자여야 합니다.

GitLab 15.7부터, 애플리케이션 설정 API를 사용하여 개인 액세스 토큰을 비활성화할 수 있습니다.

기업 사용자를 위한 개인 액세스 토큰 비활성화

  • 이름이 enterprise_disable_personal_access_tokens플래그와 함께, GitLab 16.11에서 도입되었습니다. 기본적으로 비활성화되어 있습니다.

필수 사항:

  • 기업 사용자가 속한 그룹에서 소유자 역할을 가져야 합니다.

그룹의 기업 사용자의 개인 액세스 토큰을 비활성화하면:

  • 기업 사용자는 새 개인 액세스 토큰을 만드는 것이 불가능해집니다. 이 동작은 기업 사용자가 그룹의 관리자인 경우에도 적용됩니다.
  • 기업 사용자의 기존 개인 액세스 토큰이 비활성화됩니다.
note
기업 사용자의 개인 액세스 토큰을 비활성화하는 것은 서비스 계정의 개인 액세스 토큰을 비활성화하지 않습니다.

기업 사용자의 개인 액세스 토큰을 비활성화하려면:

  1. 왼쪽 사이드바에서 찾기 또는 이동을 선택하여 그룹 또는 하위 그룹을 찾으세요.
  2. 설정 > 일반을 선택하세요.
  3. 권한과 그룹 피처를 확장하세요.
  4. 개인 액세스 토큰 비활성화를 선택하세요.
  5. 변경 사항 저장을 선택하세요.

토큰 사용한 마지막 시간보기

  • GitLab 16.0 이전에, 토큰 사용 정보는 24시간마다 업데이트됩니다.
  • 토큰 사용 정보 업데이트 빈도는 GitLab 16.1부터 24시간에서 10분으로 변경되었습니다.

토큰 사용 정보는 10분마다 업데이트됩니다. GitLab은 토큰이 다음과 같을 때 토큰을 사용된 것으로 간주합니다:

  • REST 또는 GraphQL API를 사용하여 인증한 경우.
  • Git 작업을 수행한 경우.

토큰이 사용된 마지막 시간을 보려면:

  1. 왼쪽 사이드바에서 아바타를 선택하세요.
  2. 프로필 편집을 선택하세요.
  3. 왼쪽 사이드바에서 액세스 토큰을 선택하세요.
  4. 활성 개인 액세스 토큰 영역에서 해당 토큰의 마지막 사용일을 확인하세요.

개인 액세스 토큰 범위

개인 액세스 토큰은 할당된 범위에 따라 작업을 수행할 수 있습니다.

범위 액세스
api API에 대한 완전한 읽기/쓰기 액세스를 부여합니다. 그룹 및 프로젝트, 컨테이너 레지스트리, 의존성 프록시 및 패키지 레지스트리에 대한 완전한 읽기/쓰기 액세스를 부여합니다. 또한, Git을 통해 레지스트리 및 리포지터리에 대한 완전한 읽기/쓰기 액세스를 부여합니다.
read_user /user API 엔드포인트를 통해 인증된 사용자의 프로필에 대한 읽기 전용 액세스를 부여합니다. 이는 사용자 이름, 공개 이메일 및 전체 이름을 포함하는 곳입니다. 또한 /users 아래의 읽기 전용 API 엔드포인트에 대한 액세스를 부여합니다.
read_api 그룹 및 프로젝트, 컨테이너 레지스트리 및 패키지 레지스트리에 대한 읽기 액세스를 부여합니다.
read_repository Git-over-HTTP 또는 리포지터리 파일 API를 사용하여 비공개 프로젝트의 리포지터리에 대한 읽기 전용 액세스를 부여합니다.
write_repository Git-over-HTTP를 사용하여 비공개 프로젝트의 리포지터리에 대한 읽기/쓰기 액세스를 부여합니다(API를 사용하지 않음).
read_registry 프로젝트가 비공개이며 인가가 필요한 경우, 컨테이너 레지스트리 이미지에 대한 읽기 전용(풀) 액세스를 부여합니다. 이는 컨테이너 레지스트리가 활성화된 경우에만 사용 가능합니다.
write_registry 프로젝트가 비공개이며 인가가 필요한 경우, 컨테이너 레지스트리 이미지에 대한 읽기/쓰기(푸시) 액세스를 부여합니다. 이는 컨테이너 레지스트리가 활성화된 경우에만 사용 가능합니다.
sudo 관리자로 인증된 경우, 시스템에서 임의의 사용자로 API 작업을 수행할 수 있는 권한을 부여합니다.
admin_mode 관리자 모드가 활성화된 경우, 관리자로 API 작업을 수행할 수 있는 권한을 부여합니다. (GitLab 15.8에서 도입.)
create_runner 실행자를 만드는 권한을 부여합니다.
ai_features GitLab Duo에서 API 작업을 수행할 수 있는 권한을 부여합니다. 이 범위는 JetBrains용 GitLab Duo 플러그인과 함께 작동하도록 설계되었습니다. 기타 확장 프로그램의 경우에는 범위 요구 사항을 확인하세요.
k8s_proxy 쿠버네티스 에이전트를 사용하여 쿠버네티스 API 호출을 수행할 수 있는 권한을 부여합니다.
read_service_ping 관리자로 인증된 경우, API를 통해 서비스 핑 페이로드를 다운로드할 수 있는 권한을 부여합니다. (GitLab 16.8에서 도입.
caution
외부 인증을 활성화하면, 개인 액세스 토큰으로 컨테이너 레지스트리 또는 패키지 레지스트리에 액세스할 수 없습니다. 이러한

개인 액세스 토큰 만료 시기

개인 액세스 토큰은 사용자가 정의한 날짜에 UTC 기준으로 자정인 00:00 AM에 만료됩니다.

  • GitLab은 매일 01:00 AM UTC에 7일 내에 만료되는 개인 액세스 토큰을 식별하기 위해 확인을 실행합니다. 이러한 토큰의 소유자에게 이메일로 알림이 전송됩니다.
  • GitLab은 매일 02:00 AM UTC에 현재 날짜에 만료되는 개인 액세스 토큰을 식별하기 위해 확인을 실행합니다. 이러한 토큰의 소유자에게 이메일로 알림이 전송됩니다.
  • GitLab Ultimate에서는 관리자가 액세스 토큰의 허용 가능한 수명을 제한할 수 있습니다. 설정되지 않으면 개인 액세스 토큰의 최대 허용 수명은 365일입니다.
  • GitLab Free 및 Premium에서는 개인 액세스 토큰의 최대 허용 수명이 365일입니다.
  • 개인 액세스 토큰을 만들 때 만료 날짜를 설정하지 않으면 만료 날짜가 토큰의 최대 허용 수명으로 설정됩니다. 최대 허용 수명이 설정되지 않으면 기본 만료 날짜는 생성일로부터 365일 후로 설정됩니다.

만료 날짜가 없는 서비스 계정 개인 액세스 토큰 생성

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

note
서비스 계정에 대한 개인 액세스 토큰을 만료 날짜 없이 생성할 수 있도록 하는 것은 설정 변경 후에 생성된 토큰에만 영향을 미칩니다. 기존 토큰에는 영향을 미치지 않습니다.

GitLab.com

전제 조건:

  • 최상위 그룹에서 소유자 역할을 가져야 합니다.
  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
  2. 설정 > 일반 > 권한 및 그룹 기능을 선택합니다.
  3. 서비스 계정 토큰 만료 확인란을 해제합니다.

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

자체 호스팅된 GitLab

전제 조건:

  • 자체 호스팅된 인스턴스의 관리자여아 합니다.
  1. 왼쪽 사이드바에서 가장 아래에 있는 관리 영역을 선택합니다.
  2. 설정 > 일반을 선택합니다.
  3. 계정 및 제한을 확장합니다.
  4. 서비스 계정 토큰 만료 확인란을 해제합니다.

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

프로그래밍 방식으로 개인 액세스 토큰 생성

Tier: Free, Premium, Ultimate Offering: Self-Managed, GitLab Dedicated

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

전제 조건:

프로그래밍 방식으로 개인 액세스 토큰을 생성하려면:

  1. Rails 콘솔을 엽니다:

    sudo gitlab-rails console
    
  2. 다음 명령을 실행하여 사용자 이름, 토큰 및 스코프를 참조합니다.

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

    예를 들어, 1년 후에 만료되는 username이 automation-bot인 토큰을 생성하려면:

    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!"

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

Tier: Free, Premium, Ultimate Offering: Self-Managed, GitLab Dedicated

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

전제 조건:

프로그래밍 방식으로 토큰을 취소하려면:

  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!"

개인 액세스 토큰을 사용하여 리포지터리 복제

Tier: Free, Premium, Ultimate Offering: Self-Managed, GitLab Dedicated

SSH가 비활성화된 경우, 개인 액세스 토큰을 사용하여 리포지터리를 클론하려면 다음 명령을 실행합니다:

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

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

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

clone 명령의 username:

  • 어떤 문자열 값이든 사용할 수 있습니다.
  • 빈 문자열이 아니어야 합니다.

인증에 의존하는 자동화 파이프라인을 설정하는 경우 이를 기억하세요.

문제 해결

개인 액세스 토큰 취소 취소

Tier: Free, Premium, Ultimate Offering: Self-Managed, GitLab Dedicated

어떤 방법으로든 실수로 개인 액세스 토큰을 취소하는 경우, 관리자는 해당 토큰을 다시 활성화할 수 있습니다. 기본적으로 매일 1:00 AM 시스템 시간에 취소된 토큰이 삭제되는 일일 작업이 실행됩니다.

caution
다음 명령은 데이터를 직접 변경합니다. 올바르게 수행되지 않거나 적절한 조건에서 실행되지 않으면 손상될 수 있습니다. 이러한 명령을 먼저 테스트 환경에서 실행하고 인스턴스의 백업이 준비되어 있다면 그 백업으로 복원할 수 있도록합니다.
  1. Rails 콘솔을 엽니다.
  2. 토큰을 활성화합니다:

    token = PersonalAccessToken.find_by_token('<token_string>')
    token.update!(revoked:false)
    

    예를 들어, token-string-here123의 토큰을 취소 취소하려면:

    token = PersonalAccessToken.find_by_token('token-string-here123')
    token.update!(revoked:false)
    

개인 액세스 토큰의 대체 방법

HTTPS를 통한 Git의 경우, 개인 액세스 토큰 대신 OAuth 자격 증명 도우미를 사용할 수 있습니다.