GitLab의 기본 역할은 config/authz/roles/의 YAML 파일을 사용하여 정의됩니다. 각 파일은 단일 역할, 해당 권한 및 상속 계층 구조를 정의합니다.

Authz::Role 클래스는 런타임에 이 파일들을 로드하고, 상속된 권한을 확인하며, 할당 가능한 권한 그룹을 구성 원시 권한으로 확장합니다.

YAML 스키마#

각 역할 정의 파일은 다음 구조를 따릅니다:

# config/authz/roles/<role_name>.yml
---
name: developer
description: Developer role
inherits_from:
  - reporter
raw_permissions:
  - push_code
  - create_pipeline
permissions:
  - read_work_item

권한이 확인되는 방법#

Authz::Role.get(:developer)가 호출될 때:

1. config/authz/roles/developer.yml의 YAML 파일이 로드되고 캐시됩니다.
2. inherits_from 목록이 재귀적으로 확인됩니다. 각 상위 역할에 대해 동일한 로드 및 확인 프로세스가 적용됩니다.
3. permissions에 나열된 할당 가능한 권한 그룹 이름은 Authz::PermissionGroups::Assignable을 통해 확장됩니다. 각 그룹은 하나 이상의 원시 권한으로 매핑됩니다.
4. 최종 권한 집합은 다음의 합집합입니다:
   • 이 역할의 raw_permissions
   • 이 역할의 확장된 permissions(할당 가능한 그룹)
   • 상위 역할에서 상속된 모든 권한(재귀적으로)

확인 예시#

다음 역할 정의가 주어진 경우:

# guest.yml
name: guest
inherits_from: []
raw_permissions:
  - read_issue
  - create_issue

# reporter.yml
name: reporter
inherits_from:
  - guest
raw_permissions:
  - read_code
  - download_code

# developer.yml
name: developer
inherits_from:
  - reporter
raw_permissions:
  - push_code
  - create_pipeline

Authz::Role.get(:developer).permissions를 호출하면 다음을 반환합니다:

[:read_issue, :create_issue,     # guest에서 상속
 :read_code, :download_code,     # reporter에서 상속
 :push_code, :create_pipeline]   # developer에서 직접

권한 아키텍처와의 관계#

역할 YAML 파일은 GitLab 권한 아키텍처의 한 레이어입니다. 다른 구성 요소와의 관계 이해:

원시 권한#

config/authz/permissions/<resource>/<action>.yml에 정의됩니다. 이것들은 인증의 원자 단위입니다 — 각각은 단일 리소스에 대한 단일 작업을 나타냅니다(예: read_issue, create_pipeline). 원시 권한은 역할 YAML 파일의 raw_permissions 배열에서 직접 참조되고 정책 enable/prevent 호출에서 사용됩니다.

원시 권한 생성 및 명명에 대한 자세한 내용은 권한 규칙을 참조하십시오.

할당 가능한 권한 그룹#

config/authz/permission_groups/assignable_permissions/<category>/<resource>/<action>.yml에 정의됩니다. 이것들은 역할에 할당되거나 세분화된 PAT 범위 지정에 사용할 수 있는 사용자 대면 기능 집합으로 여러 원시 권한을 번들로 묶습니다.

예를 들어, read_pipeline 할당 가능한 권한 그룹은 다음으로 확장될 수 있습니다:

# config/authz/permission_groups/assignable_permissions/ci_cd/pipeline/read.yml
name: read_pipeline
description: Grants the ability to read pipelines
permissions:
  - read_pipeline
  - read_pipeline_bridge
  - read_pipeline_job
boundaries:
  - project

역할 YAML 파일이 permissions 필드 아래에 read_pipeline을 나열하면 세 가지 원시 권한 모두가 해당 역할에 부여됩니다.

정책 파일#

DeclarativePolicy 클래스(app/policies/)는 사용자가 작업을 수행할 수 있는지 여부를 평가하는 런타임 인증 규칙을 정의합니다. 정책 규칙은 enable 및 prevent 호출을 통해 원시 권한을 참조합니다. 역할 YAML 파일은 사용자의 역할에 따라 사용자가 보유한 권한을 결정하고, 정책은 해당 권한이 평가되는 조건을 결정합니다.

사용자 지정 ability#

ee/config/custom_abilities/에 정의됩니다. 이를 통해 Ultimate 고객이 특정 ability로 사용자 지정 역할을 생성할 수 있습니다. 사용자 지정 ability YAML 파일에는 역할 YAML 파일이 raw_permissions를 사용하는 방식과 유사하게 원시 권한에 매핑되는 project_permissions 및 group_permissions 필드가 포함됩니다. 자세한 내용은 사용자 지정 역할을 참조하십시오.

기존 역할 수정#

역할에서 권한을 추가하거나 제거할 때:

• 역할에 권한을 추가할 때는 할당 가능한 권한 그룹을 사용해야 합니다. 권한이 새로운 것이라면 할당 가능한 권한 그룹을 먼저 생성하거나 기존 할당 가능한 권한 그룹에 추가해야 합니다. 권한이 기존에 있지만 역할 정의로 이동해야 하는 경우에는 raw_permission으로 할당하는 것이 허용됩니다.
• 권한을 제거할 때는 다른 기능에 의존하지 않는지 확인하십시오. GITLAB_DEBUG_POLICIES=true(자세한 내용은 사용자 지정 역할 참조)를 사용하여 권한이 확인되는 위치를 추적하십시오.