그룹 액세스 토큰은 그룹과 그 프로젝트에 대한 인증된 액세스를 제공합니다. 개인 액세스 토큰이나 프로젝트 액세스 토큰과 비슷하지만, 사용자나 프로젝트가 아니라 그룹에 연결됩니다. 그룹 액세스 토큰으로 다른 그룹 액세스 토큰, 프로젝트 액세스 토큰, 개인 액세스 토큰을 생성할 수는 없습니다.

그룹 액세스 토큰으로 다음과 같이 인증할 수 있습니다:

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

사전 요구 사항:

• 그룹에 대한 Owner 권한이 있어야 합니다.

그룹 액세스 토큰 생성#

히스토리

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

UI를 통해#

그룹 액세스 토큰을 생성하려면 다음과 같이 진행합니다:

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > Access tokens를 선택합니다.
3. Add new token을 선택합니다.
4. Token name에 이름을 입력합니다. 토큰 이름은 그룹을 볼 권한이 있는 모든 사용자에게 표시됩니다.
5. 선택 사항. Token description에 토큰 설명을 입력합니다.
6. Expiration date에 토큰의 만료일을 입력합니다.
   • 토큰은 해당 날짜의 UTC 자정에 만료됩니다.
   • 날짜를 입력하지 않으면 만료일은 오늘로부터 365일 후로 설정됩니다.
   • 기본적으로 만료일은 오늘로부터 365일을 넘길 수 없습니다. GitLab 17.6 이상에서는 관리자가 액세스 토큰의 최대 수명을 변경할 수 있습니다.
7. 토큰의 권한을 선택합니다.
8. 하나 이상의 그룹 액세스 토큰 범위를 선택합니다.
9. Create group access token을 선택합니다.

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

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

Rails 콘솔을 통해#

관리자라면 Rails 콘솔에서 그룹 액세스 토큰을 생성할 수 있습니다:

1. Rails 콘솔에서 다음 명령을 실행합니다:

   # Set the GitLab administration user to use. If user ID 1 is not available or is not an administrator, use 'admin = User.admins.first' instead to select an administrator.
   admin = User.find(1)
   
   # Set the group you want to create a token for. For example, group with ID 109.
   group = Group.find(109)
   
   # Create the group bot user. For further group access tokens, the username should be `group_{group_id}_bot_{random_string}` and email address `group_{group_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}`.
   random_string = SecureRandom.hex(16)
   service_response = Users::CreateService.new(admin, { name: 'group_token', username: "group_#{group.id}_bot_#{random_string}", email: "group_#{group.id}_bot_#{random_string}@noreply.#{Gitlab.config.gitlab.host}", user_type: :project_bot }).execute
   bot = service_response.payload[:user] if service_response.success?
   
   # Confirm the group bot.
   bot.confirm
   
   # Add the bot to the group with the required role.
   group.add_member(bot, :maintainer)
   
   # Give the bot a personal access token.
   token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token')
   
   # Get the token value.
   gtoken = token.token
   

2. 생성된 그룹 액세스 토큰이 동작하는지 확인합니다:

   1. GitLab REST API에서 PRIVATE-TOKEN 헤더에 그룹 액세스 토큰을 사용합니다. 예를 들면 다음과 같습니다:

      • 그룹에서 에픽 생성.
      • 그룹의 프로젝트 중 하나에서 프로젝트 파이프라인 생성.
      • 그룹의 프로젝트 중 하나에서 이슈 생성.

   2. 그룹 토큰을 사용해 HTTPS로 그룹의 프로젝트를 클론 합니다.

액세스 토큰 보기#

히스토리

• 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. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > Access tokens를 선택합니다.

활성 상태이며 사용 가능한 액세스 토큰은 Active group access tokens 섹션에 표시됩니다. 만료, 교체, 취소된 토큰은 Inactive group access tokens 섹션에 표시됩니다.

그룹 액세스 토큰 교체#

히스토리

• 만료 및 취소된 토큰 조회 기능이 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에서는 비활성 토큰의 보관 기간을 변경할 수 있습니다.

그룹 액세스 토큰을 교체하려면 다음과 같이 진행합니다:

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > Access tokens를 선택합니다.
3. 해당 토큰에서 Rotate ([retry])를 선택합니다.
4. 확인 대화 상자에서 Rotate를 선택합니다.

그룹 액세스 토큰 취소#

히스토리

• 만료 및 취소된 토큰 조회 기능이 GitLab 17.3에서 retain_resource_access_token_user_after_revoke라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• 만료 및 취소된 토큰을 자동 삭제 전까지 조회하는 기능이 GitLab 17.9에서 일반 공개되었습니다. 기능 플래그 retain_resource_access_token_user_after_revoke는 제거되었습니다.

토큰을 취소하면 즉시 무효화되어 더 이상 사용할 수 없습니다. 취소된 토큰이 즉시 삭제되지는 않지만, 토큰 목록을 필터링해 활성 토큰만 표시할 수 있습니다. 기본적으로 GitLab은 취소된 그룹 및 프로젝트 액세스 토큰을 30일 후에 삭제합니다. 자세한 내용은 비활성 토큰 보관을 참고합니다.

그룹 액세스 토큰을 취소하려면 다음과 같이 진행합니다:

1. 상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 Settings > Access tokens를 선택합니다.
3. 해당 토큰에서 Revoke ([remove])를 선택합니다.
4. 확인 대화 상자에서 Revoke를 선택합니다.

액세스 토큰 만료#

개인, 그룹, 프로젝트 액세스 토큰은 만료일의 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 17.7에서 pat_expiry_inherited_members_notification이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• 기능 플래그 pat_expiry_inherited_members_notification 이 GitLab 17.10에서 기본적으로 활성화되었습니다.
• 기능 플래그 pat_expiry_inherited_members_notification 이 GitLab 17.11에서 제거되었습니다

GitLab은 매일 UTC 오전 1시에 곧 만료되는 그룹 액세스 토큰을 확인합니다. Owner 권한을 가진 직접 멤버는 토큰 만료 7일 전에 이메일로 알림을 받습니다. GitLab 17.6 이상에서는 만료 30일 전과 60일 전에도 알림이 발송됩니다.

GitLab 17.7 이상에서는 Owner 권한을 가진 상속 멤버도 이 이메일을 받을 수 있습니다. GitLab 인스턴스 단위 또는 특정 그룹 단위로 이를 구성할 수 있습니다. 상위 그룹에 적용하면 이 설정은 모든 하위 그룹과 프로젝트에 상속됩니다.

만료된 토큰은 자동으로 삭제될 때까지 비활성 그룹 액세스 토큰 섹션에 표시됩니다. GitLab Self-Managed에서는 이 보관 기간을 변경할 수 있습니다.

그룹을 위한 봇 사용자#

그룹 액세스 토큰을 생성하면 GitLab은 봇 사용자를 만들어 해당 토큰과 연결합니다.

봇 사용자는 다음과 같은 특성을 가집니다:

• 연결된 액세스 토큰의 권한 및 범위에 대응하는 권한을 부여받습니다.
• 그룹의 멤버이며 하위 그룹과 프로젝트의 멤버십을 상속하지만, 다른 그룹이나 프로젝트에 직접 추가할 수는 없습니다.
• 비과금 사용자이며 라이선스 한도에 포함되지 않습니다.
• 봇 사용자의 기여 내역은 봇 사용자 계정에 연결됩니다.
• 봇 사용자가 제거되면 기여 내역은 고스트 사용자로 이전됩니다.

봇 사용자가 생성될 때 다음 속성이 정의됩니다:

그룹 및 프로젝트 액세스 토큰 생성 제한#

오용 가능성을 줄이기 위해 사용자가 그룹 및 프로젝트 액세스 토큰을 생성하지 못하도록 제한할 수 있습니다. 이 제한은 모든 하위 그룹과 그 프로젝트를 포함해 그룹 전체에 적용됩니다. 기존 토큰은 만료되거나 취소할 때까지 계속 유효합니다.

사전 요구 사항:

• 그룹에 대한 Owner 권한이 있어야 합니다.
• 그룹은 최상위 그룹이어야 합니다.
• GitLab.com에서는 그룹에 Premium 또는 Ultimate 구독이 있어야 합니다.

액세스 토큰 생성을 제한하려면 다음과 같이 진행합니다:

1. 상단 바에서 Search or go to를 선택하고 최상위 그룹을 찾습니다.
2. Settings > General을 선택합니다.
3. Permissions and group features를 확장합니다.
4. Users can create group access tokens and project access tokens in this group 체크박스를 선택 해제합니다.
5. Save changes를 선택합니다.

관련 주제#

• 개인 액세스 토큰
• 프로젝트 액세스 토큰
• 그룹 액세스 토큰 API