Group-level protected environments API

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use this API to interact with protected environments for groups.

Note

For protected environments, see protected environments API

Valid access levels

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

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

List all group-level protected environments

Lists all protected environments for a specified group.

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

Example response:

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

Retrieve a single protected environment

Retrieves a specified protected environment from a group.

GET /groups/:id/protected_environments/:name
Attribute Type Required Description
id integer or 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. Possible values: production, staging, testing, development, or other. 
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/protected_environments/production"

Example response:

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

Protect a single environment

Protects a single environment.

POST /groups/:id/protected_environments
Attribute Type Required Description
id integer or 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. Possible values: production, staging, testing, development, or other.
deploy_access_levels array yes Array of access levels allowed to deploy, with each described by a hash. Possible values: user_id, group_id or access_level. They take the form of {user_id: integer}, {group_id: integer} or {access_level: integer}.
approval_rules array no Array of access levels allowed to approve, with each described by a hash. Possible values: user_id, group_id or access_level. They take the form of {user_id: integer}, {group_id: integer} or {access_level: integer}. You can also specify the number of required approvals from the specified entity with required_approvals field. See Multiple approval rules for more information.

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 subgroups under the given group.

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

Example response:

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

An example with multiple approval rules:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/128/protected_environments" \
  --data '{
    "name": "production",
    "deploy_access_levels": [{"group_id": 138}],
    "approval_rules": [
      {"group_id": 134},
      {"group_id": 135, "required_approvals": 2}
    ]
  }'

In this configuration, the operator group "group_id": 138 can execute the deployment job to production only after the QA group "group_id": 134 and security group "group_id": 135 have approved the deployment.

Update a protected environment

Updates a single environment.

PUT /groups/:id/protected_environments/:name
Attribute Type Required Description
id integer or 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. Possible values: production, staging, testing, development, or other.
deploy_access_levels array no Array of access levels allowed to deploy, with each described by a hash. Possible values: user_id, group_id or access_level. They take the form of {user_id: integer}, {group_id: integer} or {access_level: integer}.
required_approval_count integer no The number of approvals required to deploy to this environment.
approval_rules array no Array of access levels allowed to approve, with each described by a hash. Possible values: user_id, group_id, or access_level. They take the form of {user_id: integer}, {group_id: integer}, or {access_level: integer}. You can also specify the number of required approvals from the specified entity with required_approvals field. See Multiple approval rules for more information.

To update:

  • user_id: Ensure the updated user belongs to the given group with the Maintainer role (or above). You must also pass the id of either a deploy_access_level or approval_rule in the respective hash.
  • group_id: Ensure the updated group is a subgroup of the group this protected environment belongs to. You must also pass the id of either a deploy_access_level or approval_rule in the respective hash.

To delete:

  • You must pass _destroy set to true. See the following examples.

Example: Create a deploy_access_level record

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

Example response:

{
   "name": "production",
   "deploy_access_levels": [
      {
         "id": 12,
         "access_level": 40,
         "access_level_description": "protected-access-group",
         "user_id": null,
         "group_id": 9899829,
         "group_inheritance_type": 1
      }
   ],
   "required_approval_count": 0
}

Example: Update a deploy_access_level record

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" \
  --data '{"deploy_access_levels": [{"id": 12, "group_id": 22034120}]}'
{
   "name": "production",
   "deploy_access_levels": [
      {
         "id": 12,
         "access_level": 40,
         "access_level_description": "protected-access-group",
         "user_id": null,
         "group_id": 22034120,
         "group_inheritance_type": 0
      }
   ],
   "required_approval_count": 2
}

Example: Delete a deploy_access_level record

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

Example response:

{
   "name": "production",
   "deploy_access_levels": [],
   "required_approval_count": 0
}

Example: Create an approval_rule record

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" \
  --data '{"approval_rules": [{"group_id": 134, "required_approvals": 1}]}'

Example response:

{
   "name": "production",
   "approval_rules": [
      {
         "id": 38,
         "user_id": null,
         "group_id": 134,
         "access_level": null,
         "access_level_description": "qa-group",
         "required_approvals": 1,
         "group_inheritance_type": 0
      }
   ]
}

Example: Update an approval_rule record

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" \
  --data '{"approval_rules": [{"id": 38, "group_id": 135, "required_approvals": 2}]}'
{
   "name": "production",
   "approval_rules": [
      {
         "id": 38,
         "user_id": null,
         "group_id": 135,
         "access_level": null,
         "access_level_description": "security-group",
         "required_approvals": 2,
         "group_inheritance_type": 0
      }
   ]
}

Example: Delete an approval_rule record

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/22034114/protected_environments/production" \
  --data '{"approval_rules": [{"id": 38, "_destroy": true}]}'

Example response:

{
   "name": "production",
   "approval_rules": []
}

Unprotect a single environment

Unprotects the given protected environment.

DELETE /groups/:id/protected_environments/:name
Attribute Type Required Description
id integer or 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. Possible values: production, staging, testing, development, or other. 
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/protected_environments/staging"

The response should return a 200 code.

SENASAG