그룹 액세스 토큰은 그룹과 그 프로젝트에 대한 인증된 액세스를 제공합니다. 퍼스널 액세스 토큰 및 프로젝트 액세스 토큰과 유사하지만, 사용자나 프로젝트가 아닌 그룹에 연결됩니다. 그룹 액세스 토큰을 사용하여 다른 그룹, 프로젝트 또는 퍼스널 액세스 토큰을 생성할 수 없습니다.

그룹 액세스 토큰을 사용하여 다음 작업을 인증할 수 있습니다:

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

사전 요구사항:

• 그룹의 Owner 권한.

액세스 토큰 보기#

그룹 액세스 토큰 페이지에는 액세스 토큰에 대한 정보가 표시됩니다.

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

• 그룹 액세스 토큰 생성, 교체, 취소.
• 모든 활성 및 비활성 그룹 액세스 토큰 보기.
• 스코프, 할당된 권한, 만료일 등의 토큰 정보 보기.
• 사용 날짜, 마지막 5개의 고유 연결 IP 주소 등의 사용 정보 보기.

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

그룹 액세스 토큰을 보려면:

1. 상단 바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 설정 > 액세스 토큰을 선택합니다.

활성 상태이며 사용 가능한 액세스 토큰은 활성 그룹 액세스 토큰 섹션에 저장됩니다. 만료, 교체 또는 취소된 토큰은 비활성 그룹 액세스 토큰 섹션에 저장됩니다.

그룹 액세스 토큰 생성#

UI를 통해#

그룹 액세스 토큰을 생성하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 설정 > 액세스 토큰을 선택합니다.
3. 새 토큰 추가를 선택합니다.
4. 토큰 이름에 이름을 입력합니다. 토큰 이름은 그룹을 볼 수 있는 권한이 있는 모든 사용자에게 표시됩니다.
5. 선택 사항. 토큰 설명에 토큰에 대한 설명을 입력합니다.
6. 만료일에 토큰의 만료일을 입력합니다.
   • 토큰은 해당 날짜의 UTC 자정에 만료됩니다.
   • 날짜를 입력하지 않으면 만료일이 오늘로부터 365일로 설정됩니다.
   • 기본적으로 만료일은 오늘로부터 365일을 초과할 수 없습니다. GitLab 17.6 이상에서는 관리자가 액세스 토큰의 최대 수명을 수정할 수 있습니다.
7. 토큰의 권한을 선택합니다.
8. 하나 이상의 그룹 액세스 토큰 스코프를 선택합니다.
9. 그룹 액세스 토큰 생성을 선택합니다.

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

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

Rails 콘솔을 통해#

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

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

   # 사용할 GitLab 관리 사용자를 설정합니다. 사용자 ID 1이 없거나 관리자가 아닌 경우, 'admin = User.admins.first'를 사용하여 관리자를 선택합니다.
   admin = User.find(1)
   
   # 토큰을 생성할 그룹을 설정합니다. 예를 들어, ID가 109인 그룹.
   group = Group.find(109)
   
   # 그룹 봇 사용자를 생성합니다. 추가 그룹 액세스 토큰의 경우 사용자 이름은 `group_{group_id}_bot_{random_string}`이고 이메일 주소는 `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?
   
   # 그룹 봇을 확인합니다.
   bot.confirm
   
   # 필요한 권한으로 봇을 그룹에 추가합니다.
   group.add_member(bot, :maintainer)
   
   # 봇에게 퍼스널 액세스 토큰을 부여합니다.
   token = bot.personal_access_tokens.create(scopes:[:api, :write_repository], name: 'group_token')
   
   # 토큰 값을 가져옵니다.
   gtoken = token.token
   

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

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

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

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

그룹 액세스 토큰 스코프#

스코프는 그룹 액세스 토큰으로 인증할 때 사용 가능한 작업을 정의합니다.

그룹 액세스 토큰 교체#

토큰을 교체하면 원본과 동일한 권한 및 스코프를 가진 새 토큰이 생성됩니다. 원본 토큰은 즉시 비활성화되며, GitLab은 감사 목적으로 두 버전을 모두 보존합니다. 액세스 토큰 페이지에서 활성 및 비활성 토큰을 모두 볼 수 있습니다.

GitLab Self-Managed와 GitLab Dedicated에서는 비활성 토큰의 보존 기간을 수정할 수 있습니다.

그룹 액세스 토큰을 교체하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 설정 > 액세스 토큰을 선택합니다.
3. 관련 토큰에 대해 교체 ([retry])를 선택합니다.
4. 확인 대화상자에서 교체를 선택합니다.

그룹 액세스 토큰 취소#

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

그룹 액세스 토큰을 취소하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 설정 > 액세스 토큰을 선택합니다.
3. 관련 토큰에 대해 취소 ([remove])를 선택합니다.
4. 확인 대화상자에서 취소를 선택합니다.

액세스 토큰 만료#

퍼스널, 그룹, 프로젝트 액세스 토큰은 만료일의 UTC 자정에 만료됩니다. 만료 후에는 더 이상 요청 인증에 사용할 수 없습니다.

GitLab 16.0 이상에서는 새 액세스 토큰에 반드시 만료일이 있어야 합니다. 토큰 생성 시 만료일을 명시적으로 설정하지 않으면 현재 날짜로부터 365일 후의 만료일이 자동으로 적용됩니다. GitLab Ultimate에서는 관리자가 액세스 토큰의 최대 허용 수명을 구성할 수 있습니다.

GitLab 버전을 업그레이드할 때 기존 액세스 토큰에 만료일이 자동으로 적용될 수 있습니다. 자세한 내용은 만료되지 않는 액세스 토큰을 참조하세요.

그룹 액세스 토큰 만료 이메일#

GitLab은 매일 UTC 오전 1:00에 곧 만료될 그룹 액세스 토큰을 식별하는 일일 검사를 실행합니다. Owner 권한을 가진 직접 멤버는 토큰이 만료되기 7일 전에 이메일로 알림을 받습니다. GitLab 17.6 이상에서는 토큰이 만료되기 30일 및 60일 전에도 알림이 발송됩니다.

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

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

그룹을 위한 봇 사용자#

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

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

• 연결된 액세스 토큰의 권한 및 스코프에 해당하는 권한이 부여됩니다.
• 그룹의 멤버이며 하위 그룹 및 프로젝트의 멤버십을 상속하지만, 다른 그룹이나 프로젝트에 직접 추가할 수 없습니다.
• 청구 대상이 아닌 사용자이며 라이선스 제한에 포함되지 않습니다.
• 기여는 봇 사용자 계정과 연결됩니다.
• 제거되면 기여가 고스트 사용자로 이동됩니다.

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

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

잠재적인 남용을 제한하기 위해 최상위 그룹과 모든 하위 서브그룹 또는 프로젝트에서 사용자가 액세스 토큰을 생성하지 못하도록 제한할 수 있습니다. 기존 토큰은 만료되거나 수동으로 취소될 때까지 유효합니다.

액세스 토큰 생성을 제한하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 최상위 그룹을 찾습니다.
2. 설정 > 일반을 선택합니다.
3. 권한 및 그룹 기능을 확장합니다.
4. 사용자가 이 그룹에서 그룹 액세스 토큰 및 프로젝트 액세스 토큰을 생성할 수 있습니다 체크박스의 선택을 취소합니다.
5. 변경 사항 저장을 선택합니다.

관련 주제#

• 퍼스널 액세스 토큰
• 프로젝트 액세스 토큰
• 그룹 액세스 토큰 API