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

프로젝트 액세스 토큰으로 다음과 같이 인증할 수 있습니다.

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

사전 요구 사항:

• 프로젝트의 Maintainer 또는 Owner 권한.

프로젝트 액세스 토큰 생성#

히스토리

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

프로젝트 액세스 토큰을 생성하려면 다음 절차를 따릅니다.

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 project access token을 선택합니다.

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

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

액세스 토큰 보기#

히스토리

• GitLab 17.8에서 pat_ip라는 기능 플래그와 함께 IP 주소 확인 기능이 도입됨. 17.9에서 기본적으로 활성화됨.
• GitLab 17.10에서 IP 주소 확인 기능이 정식 출시됨. 기능 플래그 pat_ip 제거됨.

프로젝트 액세스 토큰 페이지에는 액세스 토큰에 관한 정보가 표시됩니다.

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

• 프로젝트 액세스 토큰을 생성, 교체, 취소합니다.
• 활성 및 비활성 프로젝트 액세스 토큰을 모두 확인합니다.
• 범위, 할당된 권한, 만료 날짜 등 토큰 정보를 확인합니다.
• 사용 날짜와 최근 접속 IP 주소 5개 등 사용 정보를 확인합니다.

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

프로젝트 액세스 토큰을 확인하려면 다음 절차를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Access tokens를 선택합니다.

활성 상태이며 사용할 수 있는 액세스 토큰은 Active project access tokens 섹션에 표시됩니다. 만료, 교체 또는 취소된 토큰은 Inactive project 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 버전을 업그레이드할 때 기존 액세스 토큰에 만료 날짜가 자동으로 적용될 수 있습니다. 자세한 내용은 만료되지 않는 액세스 토큰을 참고합니다.

프로젝트 액세스 토큰 만료 이메일#

히스토리

• GitLab 17.6에서 expiring_pats_30d_60d_notifications라는 기능 플래그와 함께 60일 및 30일 만료 알림이 도입됨. 기본적으로 비활성화되어 있습니다.
• GitLab 17.7에서 60일 및 30일 알림이 정식 출시됨. 기능 플래그 expiring_pats_30d_60d_notifications 제거됨.
• GitLab 17.7에서 pat_expiry_inherited_members_notification이라는 기능 플래그와 함께 상속된 그룹 멤버 대상 알림이 도입됨. 기본적으로 비활성화되어 있습니다.
• 기능 플래그 pat_expiry_inherited_members_notification이 GitLab 17.10에서 기본적으로 활성화됨.
• GitLab 17.11에서 기능 플래그 pat_expiry_inherited_members_notification 제거됨

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

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

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

프로젝트의 봇 사용자#

히스토리

• GitLab 17.2에서 retain_resource_access_token_user_after_revoke라는 기능 플래그와 함께 변경됨. 기본적으로 비활성화되어 있습니다. 활성화하면 새 봇 사용자가 만료 날짜 없이 멤버로 추가되고, 이후 토큰이 취소되거나 만료되면 봇 사용자는 30일 동안 보존됩니다.
• GitLab 17.9에서 비활성 봇 사용자 보존이 정식 출시됨. 기능 플래그 retain_resource_access_token_user_after_revoke 제거됨.

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

봇 사용자의 속성은 다음과 같습니다.

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

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

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

악용 가능성을 줄이기 위해 최상위 그룹의 프로젝트에 대해 사용자가 액세스 토큰을 생성하지 못하도록 제한할 수 있습니다. 기존 토큰은 만료되거나 수동으로 취소될 때까지 유효합니다.

자세한 내용은 그룹 및 프로젝트 액세스 토큰 생성 제한을 참고합니다.

관련 주제#

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