GitLab Protected branches API

openapi: 3.2.0
info:
  title: GitLab REST Protected branches API
  description: GitLab REST API used to interact with a GitLab installation.
  termsOfService: https://handbook.gitlab.com/handbook/legal/api-terms/
  version: '19.6'
  license:
    name: CC BY-SA 4.0
    url: https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE
    x-gitlab-description: The license applies to the OpenAPI specification document itself. For terms governing use of the GitLab API, see the termsOfService field.
servers:
- url: https://{hostname}
  description: GitLab REST API
  variables:
    hostname:
      default: gitlab.com
      description: Your GitLab instance hostname
security:
- http: []
- oauth2: []
- apiKey: []
tags:
- name: Protected branches
  description: 'Use this API to manage protected branches

    for a project, and the protected branch settings

    that all projects in a group inherit.


    GitLab Premium and GitLab Ultimate support more granular protections for pushing to branches.

    Administrators can grant permission to modify and push to protected branches only to deploy keys,

    instead of specific users.


    > [!warning]

    > Group protected branch settings are restricted to top-level groups. They support only

    > valid access levels,

    > and cannot name individual users or groups.'
  x-displayName: Protected branches
  externalDocs:
    url: https://docs.gitlab.com/api/protected_branches/
paths:
  /api/v4/groups/{id}/protected_branches:
    get:
      operationId: getApiV4GroupsIdProtectedBranches
      summary: List all protected branches
      description: Lists all protected branches from a group. If a wildcard is set, it is returned instead of the exact name of the branches that match that wildcard.
      tags:
      - Protected branches
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesGroupProtectedBranch'
        '404':
          description: 404 Group Not Found
        '401':
          description: 401 Unauthorized
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
      - name: search
        required: false
        description: Name or part of the name of protected branches to search for.
        schema:
          type:
          - string
          - 'null'
        in: query
        example: mai
      x-gitlab-tier: premium
    post:
      operationId: postApiV4GroupsIdProtectedBranches
      summary: Protect a repository branch
      description: Protects a specified repository branch. Protect multiple branches by using a wildcard in the `name`.
      tags:
      - Protected branches
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesGroupProtectedBranch'
        '422':
          description: name is missing
        '409':
          description: Protected branch 'main' already exists
        '404':
          description: 404 Group Not Found
        '401':
          description: 401 Unauthorized
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4GroupsIdProtectedBranchesRequest'
      x-gitlab-tier: premium
  /api/v4/groups/{id}/protected_branches/{name}:
    get:
      operationId: getApiV4GroupsIdProtectedBranchesName
      summary: Retrieve a protected branch
      description: Retrieves a specified protected branch. Retrieve multiple branches by using a wildcard in the `name`.
      tags:
      - Protected branches
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesGroupProtectedBranch'
        '404':
          description: 404 ProtectedBranch Not Found
        '401':
          description: 401 Unauthorized
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: name
        required: true
        description: Name of the branch or wildcard.
        schema:
          type: string
        in: path
        example: main
      x-gitlab-tier: premium
    patch:
      operationId: patchApiV4GroupsIdProtectedBranchesName
      summary: Update a protected branch
      description: Updates a protected branch for a specified group.
      tags:
      - Protected branches
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesGroupProtectedBranch'
        '422':
          description: Push access levels access level has already been taken
        '404':
          description: 404 ProtectedBranch Not Found
        '401':
          description: 401 Unauthorized
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: name
        required: true
        description: Name of the branch or wildcard.
        schema:
          type: string
        in: path
        example: main
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/patchApiV4GroupsIdProtectedBranchesNameRequest'
      x-gitlab-tier: premium
    delete:
      operationId: deleteApiV4GroupsIdProtectedBranchesName
      summary: Unprotect repository branches
      description: Unprotects a specified protected branch Unprotect multiple branches by using a wildcard in the `name`.
      tags:
      - Protected branches
      responses:
        '204':
          description: No Content
        '404':
          description: 404 ProtectedBranch Not Found
        '401':
          description: 401 Unauthorized
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the group.
        schema:
          type: string
        in: path
      - name: name
        required: true
        description: Name of the branch or wildcard.
        schema:
          type: string
        in: path
        example: main
      x-gitlab-tier: premium
  /api/v4/projects/{id}/protected_branches:
    get:
      operationId: getApiV4ProjectsIdProtectedBranches
      summary: List all protected branches
      description: Lists all protected branches for a specified project.
      tags:
      - Protected branches
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesProtectedBranch'
        '404':
          description: 404 Project Not Found
        '401':
          description: 401 Unauthorized
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
        example: gitlab-org/gitlab
      - name: page
        required: false
        description: Page number of results to retrieve.
        schema:
          type: integer
          default: 1
        in: query
        example: 1
      - name: per_page
        required: false
        description: Number of items to list per page.
        schema:
          type: integer
          default: 20
        in: query
        example: 20
      - name: search
        required: false
        description: Name or part of the name of protected branches to search for.
        schema:
          type:
          - string
          - 'null'
        in: query
        example: mai
    post:
      operationId: postApiV4ProjectsIdProtectedBranches
      summary: Protect repository branches
      description: Protects a specified repository branch or several project repository branches using a wildcard protected branch.
      tags:
      - Protected branches
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesProtectedBranch'
        '422':
          description: name is missing
        '409':
          description: Protected branch 'main' already exists
        '404':
          description: 404 Project Not Found
        '401':
          description: 401 Unauthorized
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
        example: gitlab-org/gitlab
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ProjectsIdProtectedBranchesRequest'
  /api/v4/projects/{id}/protected_branches/{name}:
    get:
      operationId: getApiV4ProjectsIdProtectedBranchesName
      summary: Retrieve a protected branch or wildcard protected branch
      description: Retrieves a specified protected branch or wildcard protected branch.
      tags:
      - Protected branches
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesProtectedBranch'
        '404':
          description: 404 Project Not Found
        '401':
          description: 401 Unauthorized
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
        example: gitlab-org/gitlab
      - name: name
        required: true
        description: Name of the branch or wildcard.
        schema:
          type: string
        in: path
        example: main
    patch:
      operationId: patchApiV4ProjectsIdProtectedBranchesName
      summary: Update a protected branch
      description: Updates a protected branch for a specified project.
      tags:
      - Protected branches
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesProtectedBranch'
        '422':
          description: Push access levels access level has already been taken
        '404':
          description: 404 Project Not Found
        '401':
          description: 401 Unauthorized
        '400':
          description: 400 Bad request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
        example: gitlab-org/gitlab
      - name: name
        required: true
        description: Name of the branch or wildcard.
        schema:
          type: string
        in: path
        example: main
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/patchApiV4ProjectsIdProtectedBranchesNameRequest'
    delete:
      operationId: deleteApiV4ProjectsIdProtectedBranchesName
      summary: Unprotect repository branches
      description: Unprotects a specified protected branch or wildcard protected branch.
      tags:
      - Protected branches
      responses:
        '204':
          description: No Content
        '404':
          description: 404 Project Not Found
        '401':
          description: 401 Unauthorized
        '400':
          description: Bad Request
      parameters:
      - name: id
        required: true
        description: ID or URL-encoded path of the project.
        schema:
          oneOf:
          - type: string
          - type: integer
        in: path
        example: gitlab-org/gitlab
      - name: name
        required: true
        description: Name of the branch or wildcard.
        schema:
          type: string
        in: path
        example: main
components:
  schemas:
    patchApiV4GroupsIdProtectedBranchesNameRequest:
      type: object
      properties:
        allow_force_push:
          type:
          - boolean
          - 'null'
          description: If `true`, members who can push to this branch can also force push.
        unprotect_access_level:
          type:
          - integer
          - 'null'
          enum:
          - 30
          - 40
          - 60
          - null
          description: Access level allowed to unprotect. Defaults to `40` (Maintainer role). Does not support custom roles. Use `allowed_to_unprotect` with `member_role_id` instead.
        allowed_to_push:
          type:
          - array
          - 'null'
          items:
            type: object
          description: Array of users, groups, deploy keys, or access levels allowed to push to protected branches
        allowed_to_merge:
          type:
          - array
          - 'null'
          items:
            type: object
          description: Array of users, groups, or access levels allowed to merge protected branches
        allowed_to_unprotect:
          type:
          - array
          - 'null'
          items:
            type: object
          description: Array of users, groups, or access levels allowed to unprotect protected branches
        code_owner_approval_required:
          type:
          - boolean
          - 'null'
          description: Prevent pushes to this branch if it matches an item in CODEOWNERS
    patchApiV4ProjectsIdProtectedBranchesNameRequest:
      type: object
      properties:
        allow_force_push:
          type:
          - boolean
          - 'null'
          description: If `true`, members who can push to this branch can also force push.
        allowed_to_push:
          type:
          - array
          - 'null'
          items:
            type: object
          description: Array of users, groups, deploy keys, or access levels allowed to push to protected branches
        unprotect_access_level:
          type:
          - integer
          - 'null'
          enum:
          - 30
          - 40
          - 60
          - null
          description: Access level allowed to unprotect. Defaults to `40` (Maintainer role). Does not support custom roles. Use `allowed_to_unprotect` with `member_role_id` instead.
        allowed_to_merge:
          type:
          - array
          - 'null'
          items:
            type: object
          description: Array of users, groups, or access levels allowed to merge protected branches
        allowed_to_unprotect:
          type:
          - array
          - 'null'
          items:
            type: object
          description: Array of users, groups, or access levels allowed to unprotect protected branches
        code_owner_approval_required:
          type:
          - boolean
          - 'null'
          description: Prevent pushes to this branch if it matches an item in CODEOWNERS
    postApiV4ProjectsIdProtectedBranchesRequest:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Name of the branch or wildcard.
          example: main
        push_access_level:
          type:
          - integer
          - 'null'
          enum:
          - 30
          - 40
          - 60
          - 0
          - null
          description: Access level allowed to push. Defaults to `40` (Maintainer role).
        merge_access_level:
          type:
          - integer
          - 'null'
          enum:
          - 30
          - 40
          - 60
          - 0
          - null
          description: Access level allowed to merge. Defaults to `40` (Maintainer role).
        allow_force_push:
          type: boolean
          description: If `true`, members who can push to this branch can also force push.
          default: false
        allowed_to_push:
          type:
          - array
          - 'null'
          items:
            type: object
          description: Array of users, groups, deploy keys, or access levels allowed to push to protected branches
        unprotect_access_level:
          type:
          - integer
          - 'null'
          enum:
          - 30
          - 40
          - 60
          - null
          description: Access level allowed to unprotect. Defaults to `40` (Maintainer role). Does not support custom roles. Use `allowed_to_unprotect` with `member_role_id` instead.
        allowed_to_merge:
          type:
          - array
          - 'null'
          items:
            type: object
          description: Array of users, groups, or access levels allowed to merge protected branches
        allowed_to_unprotect:
          type:
          - array
          - 'null'
          items:
            type: object
          description: Array of users, groups, or access levels allowed to unprotect protected branches
        code_owner_approval_required:
          type:
          - boolean
          - 'null'
          description: Prevent pushes to this branch if it matches an item in CODEOWNERS
      required:
      - name
    APIEntitiesProtectedBranch:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: main
        push_access_levels:
          type: array
          items:
            $ref: '#/components/schemas/APIEntitiesProtectedRefAccess'
        merge_access_levels:
          type: array
          items:
            $ref: '#/components/schemas/APIEntitiesProtectedRefAccess'
        allow_force_push:
          type: boolean
        unprotect_access_levels:
          type: array
          items:
            $ref: '#/components/schemas/APIEntitiesProtectedRefAccess'
        code_owner_approval_required:
          type: boolean
        inherited:
          type: boolean
    APIEntitiesProtectedRefAccess:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        access_level:
          type: integer
          example: 40
        access_level_description:
          type: string
          example: Maintainers
        deploy_key_id:
          type: integer
          format: int64
          example: 1
        user_id:
          type: integer
          format: int64
          example: 1
        group_id:
          type: integer
          format: int64
          example: 1
        member_role_id:
          type: integer
          format: int64
          example: 42
        member_role_name:
          type: string
          example: Lead Developer
    postApiV4GroupsIdProtectedBranchesRequest:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Name of the branch or wildcard.
          example: main
        push_access_level:
          type:
          - integer
          - 'null'
          enum:
          - 30
          - 40
          - 60
          - 0
          - null
          description: Access level allowed to push. Defaults to `40` (Maintainer role). Does not support custom roles. Use `allowed_to_push` with `member_role_id` instead.
        merge_access_level:
          type:
          - integer
          - 'null'
          enum:
          - 30
          - 40
          - 60
          - 0
          - null
          description: Access level allowed to merge. Defaults to `40` (Maintainer role). Does not support custom roles. Use `allowed_to_merge` with `member_role_id` instead.
        allow_force_push:
          type: boolean
          description: If `true`, members who can push to this branch can also force push.
          default: false
        unprotect_access_level:
          type:
          - integer
          - 'null'
          enum:
          - 30
          - 40
          - 60
          - null
          description: Access level allowed to unprotect. Defaults to `40` (Maintainer role). Does not support custom roles. Use `allowed_to_unprotect` with `member_role_id` instead.
        allowed_to_push:
          type:
          - array
          - 'null'
          items:
            type: object
          description: Array of users, groups, deploy keys, or access levels allowed to push to protected branches
        allowed_to_merge:
          type:
          - array
          - 'null'
          items:
            type: object
          description: Array of users, groups, or access levels allowed to merge protected branches
        allowed_to_unprotect:
          type:
          - array
          - 'null'
          items:
            type: object
          description: Array of users, groups, or access levels allowed to unprotect protected branches
        code_owner_approval_required:
          type:
          - boolean
          - 'null'
          description: Prevent pushes to this branch if it matches an item in CODEOWNERS
      required:
      - name
    APIEntitiesGroupProtectedBranch:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: main
        push_access_levels:
          type: array
          items:
            $ref: '#/components/schemas/APIEntitiesProtectedRefAccess'
        merge_access_levels:
          type: array
          items:
            $ref: '#/components/schemas/APIEntitiesProtectedRefAccess'
        allow_force_push:
          type: boolean
        unprotect_access_levels:
          type: array
          items:
            $ref: '#/components/schemas/APIEntitiesProtectedRefAccess'
        code_owner_approval_required:
          type: boolean
  securitySchemes:
    http:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://gitlab.com/oauth/authorize
          tokenUrl: https://gitlab.com/oauth/token
          refreshUrl: https://gitlab.com/oauth/token
          scopes:
            api: Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry.
            read_api: Grants read access to the API, including all groups and projects, the container registry, and the package registry.
            read_user: Grants read-only access to your profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.
            create_runner: Grants create access to the runners.
            manage_runner: Grants access to manage the runners.
            k8s_proxy: Grants permission to perform Kubernetes API calls using the agent for Kubernetes.
            self_rotate: Grants permission for token to rotate itself.
            mcp: Grants read-write access to remote Model Context Protocol (MCP) server for tools execution.
            mcp_orbit: Grants access to the Orbit Knowledge Graph MCP server for graph queries and schema retrieval.
    apiKey:
      type: apiKey
      name: PRIVATE-TOKEN
      in: header