그룹 수준 보호 브랜치 API

Tier: Premium, Ultimate
Offering: Self-managed

History

Introduced in GitLab 15.9 with a flag named group_protected_branches. 기본적으로 비활성화되어 있습니다.
Flag group_protected_branches renamed flag to allow_protected_branches_for_group GitLab 15.11.

Self-managed GitLab에서는 기본적으로 이 기능을 사용할 수 없습니다. 이 기능을 사용 가능하게 하려면 관리자가 allow_protected_branches_for_group라는 기능 플래그를 활성화할 수 있습니다.
GitLab.com 및 GitLab Dedicated에서는 이 기능을 사용할 수 없습니다.

그룹 수준 보호 브랜치 API를 사용하여 보호 브랜치 규칙을 관리하세요.
이 API는 그룹 내 프로젝트에 적용되는 보호 브랜치 규칙을 나열, 생성, 업데이트 및 삭제하는 엔드포인트를 제공합니다.

그룹 수준 보호 브랜치 설정은 최상위 그룹에만 제한됩니다.

유효한 액세스 수준

액세스 수준은 ProtectedRefAccess.allowed_access_levels 메서드에서 정의됩니다.
인식되는 수준은 다음과 같습니다:

0  => No access  
30 => Developer access  
40 => Maintainer access  
60 => Admin access

보호 브랜치 목록

그룹에서 보호 브랜치의 목록을 가져옵니다. 와일드카드가 설정되면 해당 와일드카드와 일치하는 브랜치의 정확한 이름 대신 반환됩니다.

GET /groups/:id/protected_branches

Attribute	Type	Required	Description
`id`	integer or string	yes	그룹의 ID 또는 URL 인코딩된 경로입니다.
`search`	string	no	검색할 보호 브랜치의 이름 또는 이름의 일부입니다.

curl --header "PRIVATE-TOKEN: <your_access_token>" \  
     "https://gitlab.example.com/api/v4/groups/5/protected_branches"  

예시 응답:

[  
  {  
    "id": 1,  
    "name": "main",  
    "push_access_levels": [  
      {  
        "id":  1,  
        "access_level": 40,  
        "user_id": null,  
        "group_id": 1234,  
        "access_level_description": "Maintainers"  
      }  
    ],  
    "merge_access_levels": [  
      {  
        "id":  1,  
        "access_level": 40,  
        "user_id": null,  
        "group_id": 1234,  
        "access_level_description": "Maintainers"  
      }  
    ],  
    "allow_force_push":false,  
    "code_owner_approval_required": false  
  },  
  {  
    "id": 1,  
    "name": "release/*",  
    "push_access_levels": [  
      {  
        "id":  1,  
        "access_level": 40,  
        "user_id": null,  
        "group_id": null,  
        "access_level_description": "Maintainers"  
      }  
    ],  
    "merge_access_levels": [  
      {  
        "id":  1,  
        "access_level": 40,  
        "user_id": null,  
        "group_id": 1234,  
        "access_level_description": "Maintainers"  
      }  
    ],  
    "allow_force_push":false,  
    "code_owner_approval_required": false  
  },  
  ...  
]  

단일 보호된 브랜치 또는 와일드카드 보호된 브랜치 가져오기

단일 보호된 브랜치 또는 와일드카드 보호된 브랜치를 가져옵니다.

GET /groups/:id/protected_branches/:name

속성	유형	필수	설명
`id`	integer or string	예	그룹의 ID 또는 URL-인코딩된 경로.
`name`	string	예	브랜치 또는 와일드카드의 이름.

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/5/protected_branches/main"

예시 응답:

{
  "id": 1,
  "name": "main",
  "push_access_levels": [
    {
      "id":  1,
      "access_level": 40,
      "user_id": null,
      "group_id": null,
      "access_level_description": "Maintainers"
    }
  ],
  "merge_access_levels": [
    {
      "id":  1,
      "access_level": null,
      "user_id": null,
      "group_id": 1234,
      "access_level_description": "Example Merge Group"
    }
  ],
  "allow_force_push":false,
  "code_owner_approval_required": false
}

저장소 브랜치 보호

와일드카드 보호된 브랜치를 사용하여 단일 저장소 브랜치를 보호합니다.

POST /groups/:id/protected_branches

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30&unprotect_access_level=40"

속성	유형	필수	설명
`id`	integer or string	예	그룹의 ID 또는 URL-인코딩된 경로.
`name`	string	예	브랜치 또는 와일드카드의 이름.
`allow_force_push`	boolean	아니	모든 푸시 접근 권한이 있는 사용자가 강제 푸시를 허용합니다. 기본값: `false`.
`allowed_to_merge`	array	아니	병합을 허용하는 접근 수준의 배열, 각 접근 수준은 `{user_id: integer}`, `{group_id: integer}`, 또는 `{access_level: integer}`의 해시로 설명됩니다.
`allowed_to_push`	array	아니	푸시를 허용하는 접근 수준의 배열, 각 접근 수준은 `{user_id: integer}`, `{group_id: integer}`, 또는 `{access_level: integer}`의 해시로 설명됩니다.
`allowed_to_unprotect`	array	아니	보호 해제를 허용하는 접근 수준의 배열, 각 접근 수준은 `{user_id: integer}`, `{group_id: integer}`, 또는 `{access_level: integer}`의 해시로 설명됩니다.
`code_owner_approval_required`	boolean	아니	`CODEOWNERS` 파일의 항목과 일치하는 경우 이 브랜치에 대한 푸시를 방지합니다. 기본값: `false`.
`merge_access_level`	integer	아니	병합을 허용하는 접근 수준. 기본값: `40`, Maintainer 역할.
`push_access_level`	integer	아니	푸시를 허용하는 접근 수준. 기본값: `40`, Maintainer 역할.
`unprotect_access_level`	integer	아니	보호 해제를 허용하는 접근 수준. 기본값: `40`, Maintainer 역할.

예시 응답:

{
  "id": 1,
  "name": "*-stable",
  "push_access_levels": [
    {
      "id":  1,
      "access_level": 30,
      "user_id": null,
      "group_id": null,
      "access_level_description": "Developers + Maintainers"
    }
  ],
  "merge_access_levels": [
    {
      "id":  1,
      "access_level": 30,
      "user_id": null,
      "group_id": null,
      "access_level_description": "Developers + Maintainers"
    }
  ],
  "unprotect_access_levels": [
    {
      "id":  1,
      "access_level": 40,
      "user_id": null,
      "group_id": null,
      "access_level_description": "Maintainers"
    }
  ],
  "allow_force_push":false,
  "code_owner_approval_required": false
}

사용자 / 그룹 수준 액세스의 예

allowed_to_push / allowed_to_merge / allowed_to_unprotect 배열의 요소는 {user_id: integer}, {group_id: integer}, 또는 {access_level: integer} 형태를 가져야 합니다. 각 사용자는 프로젝트에 대한 액세스 권한이 있어야 하며, 각 그룹은
이 프로젝트를 공유해야 합니다. 이러한 액세스 수준은
보호된 브랜치 액세스에 대한 보다 세부적인 제어를 허용합니다.

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/5/protected_branches?name=*-stable&allowed_to_push%5B%5D%5Buser_id%5D=1"

예시 응답:

{
  "id": 1,
  "name": "*-stable",
  "push_access_levels": [
    {
      "id":  1,
      "access_level": null,
      "user_id": 1,
      "group_id": null,
      "access_level_description": "Administrator"
    }
  ],
  "merge_access_levels": [
    {
      "id":  1,
      "access_level": 40,
      "user_id": null,
      "group_id": null,
      "access_level_description": "Maintainers"
    }
  ],
  "unprotect_access_levels": [
    {
      "id":  1,
      "access_level": 40,
      "user_id": null,
      "group_id": null,
      "access_level_description": "Maintainers"
    }
  ],
  "allow_force_push":false,
  "code_owner_approval_required": false
}

푸시 허용 및 병합 허용 액세스의 예

예시 요청:

curl --request POST \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{
      "name": "main",
      "allowed_to_push": [{"access_level": 30}],
      "allowed_to_merge": [{
          "access_level": 30
        },{
          "access_level": 40
        }
      ]}'
     "https://gitlab.example.com/api/v4/groups/5/protected_branches"

예시 응답:

{
    "id": 5,
    "name": "main",
    "push_access_levels": [
        {
            "id": 1,
            "access_level": 30,
            "access_level_description": "Developers + Maintainers",
            "user_id": null,
            "group_id": null
        }
    ],
    "merge_access_levels": [
        {
            "id": 1,
            "access_level": 30,
            "access_level_description": "Developers + Maintainers",
            "user_id": null,
            "group_id": null
        },
        {
            "id": 2,
            "access_level": 40,
            "access_level_description": "Maintainers",
            "user_id": null,
            "group_id": null
        }
    ],
    "unprotect_access_levels": [
        {
            "id": 1,
            "access_level": 40,
            "access_level_description": "Maintainers",
            "user_id": null,
            "group_id": null
        }
    ],
    "allow_force_push":false,
    "code_owner_approval_required": false
}

리포지토리 브랜치 보호 해제

주어진 보호 브랜치 또는 와일드카드 보호 브랜치를 보호 해제합니다.

DELETE /groups/:id/protected_branches/:name

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/5/protected_branches/*-stable"

속성	유형	필수	설명
`id`	integer 또는 string	예	그룹의 ID 또는 URL-인코딩 경로.
`name`	string	예	브랜치의 이름.

예제 응답:

{
   "name": "main",
   "push_access_levels": [
      {
         "id": 12,
         "access_level": 40,
         "access_level_description": "Maintainers",
         "user_id": null,
         "group_id": null
      }
   ]
}

보호 브랜치 업데이트

보호 브랜치를 업데이트합니다.

PATCH /groups/:id/protected_branches/:name

curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/5/protected_branches/feature-branch?allow_force_push=true&code_owner_approval_required=true"

속성	유형	필수	설명
`id`	integer 또는 string	예	그룹의 ID 또는 URL-인코딩 경로.
`name`	string	예	브랜치의 이름.
`allow_force_push`	boolean	아니오	활성화되면 이 브랜치에 푸시할 수 있는 멤버가 강제 푸시도 할 수 있습니다.
`allowed_to_push`	array	아니오	각 항목이 해시로 설명된 푸시 접근 수준의 배열.
`allowed_to_merge`	array	아니오	각 항목이 해시로 설명된 병합 접근 수준의 배열.
`allowed_to_unprotect`	array	아니오	각 항목이 해시로 설명된 보호 해제 접근 수준의 배열.
`code_owner_approval_required`	boolean	아니오	`CODEOWNERS` 파일에서 항목과 일치할 경우 이 브랜치에 푸시를 방지합니다. 기본값: `false`.

allowed_to_push, allowed_to_merge, allowed_to_unprotect 배열의 요소는 다음 중 하나여야 합니다:

user_id, group_id, 또는 access_level.
{user_id: integer}, {group_id: integer}, 또는 {access_level: integer} 형식을 가져야 합니다.

업데이트하려면:

user_id: 업데이트된 사용자가 프로젝트에 액세스할 수 있는지 확인해야 합니다. 해당 해시에서 access_level의 id도 전달해야합니다.
group_id: 업데이트된 그룹이 이 프로젝트를 공유하는지 확인해야 합니다. 해당 해시에서 access_level의 id도 전달해야 합니다.

삭제하려면:

_destroy를 true로 설정해야 합니다. 다음 예제를 참조하세요.

예제: `push_access_level` 레코드 생성

curl --header 'Content-Type: application/json' --request PATCH \
     --data '{"allowed_to_push": [{access_level: 40}]}' \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/22034114/protected_branches/main"

예제 응답:

{
   "name": "main",
   "push_access_levels": [
      {
         "id": 12,
         "access_level": 40,
         "access_level_description": "Maintainers",
         "user_id": null,
         "group_id": null
      }
   ]
}

예제: `push_access_level` 레코드 업데이트

curl --header 'Content-Type: application/json' --request PATCH \
     --data '{"allowed_to_push": [{"id": 12, "access_level": 0}]' \
     --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22034114/protected_branches/main"

예제 응답:

{
   "name": "main",
   "push_access_levels": [
      {
         "id": 12,
         "access_level": 0,
         "access_level_description": "No One",
         "user_id": null,
         "group_id": null
      }
   ]
}

예제: `push_access_level` 레코드 삭제

curl --header 'Content-Type: application/json' --request PATCH \
     --data '{"allowed_to_push": [{"id": 12, "_destroy": true}]}' \
     --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22034114/protected_branches/main"

예제 응답:

{
   "name": "main",
   "push_access_levels": []
}

On this page

그룹 수준 보호 브랜치 API

유효한 액세스 수준

보호 브랜치 목록

단일 보호된 브랜치 또는 와일드카드 보호된 브랜치 가져오기

저장소 브랜치 보호

사용자 / 그룹 수준 액세스의 예

푸시 허용 및 병합 허용 액세스의 예

리포지토리 브랜치 보호 해제

보호 브랜치 업데이트

예제: `push_access_level` 레코드 생성

예제: `push_access_level` 레코드 업데이트

예제: `push_access_level` 레코드 삭제

도움말

기능 사용 가능성과 제품 평가판

도움받기

On this page

On this page

그룹 수준 보호 브랜치 API

유효한 액세스 수준

보호 브랜치 목록

단일 보호된 브랜치 또는 와일드카드 보호된 브랜치 가져오기

저장소 브랜치 보호

사용자 / 그룹 수준 액세스의 예

푸시 허용 및 병합 허용 액세스의 예

리포지토리 브랜치 보호 해제

보호 브랜치 업데이트

예제: push_access_level 레코드 생성

예제: push_access_level 레코드 업데이트

예제: push_access_level 레코드 삭제

도움말

기능 사용 가능성과 제품 평가판

도움받기

On this page

예제: `push_access_level` 레코드 생성

예제: `push_access_level` 레코드 업데이트

예제: `push_access_level` 레코드 삭제