protected_branches.md 3.79 KB
Newer Older
Eric's avatar
Eric committed
1 2 3 4 5 6
# Protected branches API

>**Note:** This feature was introduced in GitLab 9.5

**Valid access levels**

7
The access levels are defined in the `ProtectedRefAccess::ALLOWED_ACCESS_LEVELS` constant. Currently, these levels are recognized:
Eric's avatar
Eric committed
8 9 10
```
0  => No access
30 => Developer access
Mark Chao's avatar
Mark Chao committed
11
40 => Maintainer access
Eric's avatar
Eric committed
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
```

## List protected branches

Gets a list of protected branches from a project.

```
GET /projects/:id/protected_branches
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |

```bash
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches'
```

Example response:

```json
[
  {
    "name": "master",
    "push_access_levels": [
      {
        "access_level": 40,
Mark Chao's avatar
Mark Chao committed
39
        "access_level_description": "Maintainers"
Eric's avatar
Eric committed
40 41 42 43 44
      }
    ],
    "merge_access_levels": [
      {
        "access_level": 40,
Mark Chao's avatar
Mark Chao committed
45
        "access_level_description": "Maintainers"
Eric's avatar
Eric committed
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
      }
    ]
  },
  ...
]
```

## Get a single protected branch or wildcard protected branch

Gets a single protected branch or wildcard protected branch.

```
GET /projects/:id/protected_branches/:name
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `name` | string | yes | The name of the branch or wildcard |

```bash
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches/master'
```

Example response:

```json
{
  "name": "master",
  "push_access_levels": [
    {
      "access_level": 40,
Mark Chao's avatar
Mark Chao committed
78
      "access_level_description": "Maintainers"
Eric's avatar
Eric committed
79 80 81 82 83
    }
  ],
  "merge_access_levels": [
    {
      "access_level": 40,
Mark Chao's avatar
Mark Chao committed
84
      "access_level_description": "Maintainers"
Eric's avatar
Eric committed
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106
    }
  ]
}
```

## Protect repository branches

Protects a single repository branch or several project repository
branches using a wildcard protected branch.

```
POST /projects/:id/protected_branches
```

```bash
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30'
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `name` | string | yes | The name of the branch or wildcard |
Mark Chao's avatar
doc  
Mark Chao committed
107 108
| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, maintainer access level) |
| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, maintainer access level) |
Eric's avatar
Eric committed
109 110 111 112 113 114 115 116 117

Example response:

```json
{
  "name": "*-stable",
  "push_access_levels": [
    {
      "access_level": 30,
Mark Chao's avatar
Mark Chao committed
118
      "access_level_description": "Developers + Maintainers"
Eric's avatar
Eric committed
119 120 121 122 123
    }
  ],
  "merge_access_levels": [
    {
      "access_level": 30,
Mark Chao's avatar
Mark Chao committed
124
      "access_level_description": "Developers + Maintainers"
Eric's avatar
Eric committed
125 126 127 128 129 130 131 132 133 134 135 136 137 138
    }
  ]
}
```

## Unprotect repository branches

Unprotects the given protected branch or wildcard protected branch.

```
DELETE /projects/:id/protected_branches/:name
```

```bash
139
curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/5/protected_branches/*-stable'
Eric's avatar
Eric committed
140 141 142 143 144 145
```

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
| `name` | string | yes | The name of the branch |