Skip to content

GitLab

Group-level protected environments API (PREMIUM)

Read more about group-level protected environments.

Valid access levels

The access levels are defined in the ProtectedEnvironment::DeployAccessLevel::ALLOWED_ACCESS_LEVELS method. Currently, these levels are recognized:

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

List group-level protected environments

Gets a list of protected environments from a group.

GET /groups/:id/protected_environments
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group maintained by the authenticated user. 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/protected_environments/"

Example response:

[
   {
      "name":"production",
      "deploy_access_levels":[
         {
            "access_level": 40,
            "access_level_description": "Maintainers",
            "user_id": null,
            "group_id": null
         }
      ],
     "required_approval_count": 0
   }
]

Get a single protected environment

Gets a single protected environment.

GET /groups/:id/protected_environments/:name
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group maintained by the authenticated user.
name string yes The deployment tier of the protected environment. One of production, staging, testing, development, or other. Read more about deployment tiers. 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/protected_environments/production"

Example response:

{
   "name":"production",
   "deploy_access_levels":[
      {
         "access_level":40,
         "access_level_description":"Maintainers",
         "user_id":null,
         "group_id":null
      }
   ],
   "required_approval_count": 0
}

Protect an environment

Protects a single environment.

POST /groups/:id/protected_environments
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group maintained by the authenticated user.
name string yes The deployment tier of the protected environment. One of production, staging, testing, development, or other. Read more about deployment tiers.
deploy_access_levels array yes Array of access levels allowed to deploy, with each described by a hash. One of user_id, group_id or access_level. They take the form of {user_id: integer}, {group_id: integer} or {access_level: integer} respectively.
required_approval_count integer no The number of approvals required to deploy to this environment. This is part of Deployment Approvals, which isn't yet available for use. For details, see issue.

The assignable user_id are the users who belong to the given group with the Maintainer role (or above). The assignable group_id are the sub-groups under the given group.

curl --header 'Content-Type: application/json' --request POST --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}]}' --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22034114/protected_environments"

Example response:

{
   "name":"production",
   "deploy_access_levels":[
      {
         "access_level": 40,
         "access_level_description": "protected-access-group",
         "user_id": null,
         "group_id": 9899826
      }
   ],
  "required_approval_count": 0
}

Unprotect environment

Unprotects the given protected environment.

DELETE /groups/:id/protected_environments/:name
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group maintained by the authenticated user.
name string yes The deployment tier of the protected environment. One of production, staging, testing, development, or other. Read more about deployment tiers. 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/protected_environments/staging"

The response should return a 200 code.