Skip to content

Protected branches API

Note: This feature was introduced in GitLab 9.5

Valid access levels

The access levels are defined in the ProtectedRefAccess.allowed_access_levels method. Currently, these levels are recognized:

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

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 owned by the authenticated user 
curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches'

Example response:

[
  {
    "name": "master",
    "push_access_levels": [
      {
        "access_level": 40,
        "access_level_description": "Maintainers"
      }
    ],
    "merge_access_levels": [
      {
        "access_level": 40,
        "access_level_description": "Maintainers"
      }
    ],
    "code_owner_approval_required": "false"
  },
  ...
]

Users on GitLab Starter, Bronze, or higher will also see the user_id and group_id parameters:

Example response:

[
  {
    "name": "master",
    "push_access_levels": [
      {
        "access_level": 40,
        "user_id": null,
        "group_id": null,
        "access_level_description": "Maintainers"
      }
    ],
    "merge_access_levels": [
      {
        "access_level": null,
        "user_id": null,
        "group_id": 1234,
        "access_level_description": "Example Merge Group"
      }
    ],
    "code_owner_approval_required": "false"
  },
  ...
]

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 owned by the authenticated user
name string yes The name of the branch or wildcard 
curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches/master'

Example response:

{
  "name": "master",
  "push_access_levels": [
    {
      "access_level": 40,
      "access_level_description": "Maintainers"
    }
  ],
  "merge_access_levels": [
    {
      "access_level": 40,
      "access_level_description": "Maintainers"
    }
  ],
  "code_owner_approval_required": "false"
}

Users on GitLab Starter, Bronze, or higher will also see the user_id and group_id parameters:

Example response:

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

Protect repository branches

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

POST /projects/:id/protected_branches
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30&unprotect_access_level=40'
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project owned by the authenticated user
name string yes The name of the branch or wildcard
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)
unprotect_access_level string no Access levels allowed to unprotect (defaults: 40, maintainer access level)
allowed_to_push array no (STARTER) Array of access levels allowed to push, with each described by a hash
allowed_to_merge array no (STARTER) Array of access levels allowed to merge, with each described by a hash
allowed_to_unprotect array no (STARTER) Array of access levels allowed to unprotect, with each described by a hash
code_owner_approval_required boolean no (PREMIUM) Prevent pushes to this branch if it matches an item in the CODEOWNERS file. (defaults: false)

Example response:

{
  "name": "*-stable",
  "push_access_levels": [
    {
      "access_level": 30,
      "access_level_description": "Developers + Maintainers"
    }
  ],
  "merge_access_levels": [
    {
      "access_level": 30,
      "access_level_description": "Developers + Maintainers"
    }
  ],
  "unprotect_access_levels": [
    {
      "access_level": 40,
      "access_level_description": "Maintainers"
    }
  ],
  "code_owner_approval_required": "false"
}

Users on GitLab Starter, Bronze, or higher will also see the user_id and group_id parameters:

Example response:

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

Example with user / group level access (STARTER)

Elements in the allowed_to_push / allowed_to_merge / allowed_to_unprotect array should take the form {user_id: integer}, {group_id: integer} or {access_level: integer}. Each user must have access to the project and each group must have this project shared. These access levels allow more granular control over protected branch access and were added to the API in in GitLab 10.3 EE.

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

Example response:

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

Unprotect repository branches

Unprotects the given protected branch or wildcard protected branch.

DELETE /projects/:id/protected_branches/:name
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches/*-stable'
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project owned by the authenticated user
name string yes The name of the branch

Require code owner approvals for a single branch

Update the "code owner approval required" option for the given protected branch protected branch.

PATCH /projects/:id/protected_branches/:name
curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches/feature-branch'
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project owned by the authenticated user
name string yes The name of the branch
code_owner_approval_required boolean no (PREMIUM) Prevent pushes to this branch if it matches an item in the CODEOWNERS file. (defaults: false)