Merge branch '30595-api-for-protected-environments-docs' into 'master'

Add docs for protected environments API

See merge request gitlab-org/gitlab!23964

doc/api/api_resources.md

@@ -56,6 +56,7 @@ The following API resources are available in the project context:
 | [Project milestones](milestones.md)                                 | `/projects/:id/milestones`                                                                                                                                                                            |
 | [Project snippets](project_snippets.md)                             | `/projects/:id/snippets`                                                                                                                                                                              |
 | [Project templates](project_templates.md)                           | `/projects/:id/templates`                                                                                                                                                                             |
+| [Protected_environments](protected_environments.md)                 | `/projects/:id/protected_environments`                                                                                                                                                                |
 | [Protected branches](protected_branches.md)                         | `/projects/:id/protected_branches`                                                                                                                                                                    |
 | [Protected tags](protected_tags.md)                                 | `/projects/:id/protected_tags`                                                                                                                                                                        |
 | [Releases](releases/index.md)                                       | `/projects/:id/releases`                                                                                                                                                                              |

doc/api/protected_environments.md

+# Protected environments API **(PREMIUM)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/30595) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8.
+
+## 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 protected environments
+
+Gets a list of protected environments from a project:
+
+```bash
+GET /projects/:id/protected_environments
+```
+
+| 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: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments/'
+```
+
+Example response:
+
+```json
+[
+   {
+      "name":"production",
+      "deploy_access_levels":[
+         {
+            "access_level":40,
+            "access_level_description":"Maintainers",
+            "user_id":null,
+            "group_id":null
+         }
+      ]
+   }
+]
+```
+
+## Get a single protected environment
+
+Gets a single protected environment:
+
+```bash
+GET /projects/:id/protected_environments/: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 protected environment |
+
+```bash
+curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments/production'
+```
+
+Example response:
+
+```json
+{
+   "name":"production",
+   "deploy_access_levels":[
+      {
+         "access_level":40,
+         "access_level_description":"Maintainers",
+         "user_id":null,
+         "group_id":null
+      }
+   ]
+}
+```
+
+## Protect repository environments
+
+Protects a single environment:
+
+```bash
+POST /projects/:id/protected_environments
+```
+
+```bash
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments?name=staging&deploy_access_levels%5B%5D%5Buser_id%5D=1'
+```
+
+| 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 environment. |
+| `deploy_access_levels`          | array          | yes | Array of access levels allowed to deploy, with each described by a hash. |
+
+Elements in the `deploy_access_levels` 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](../user/project/members/share_project_with_groups.md).
+
+Example response:
+
+```json
+{
+   "name":"staging",
+   "deploy_access_levels":[
+      {
+         "access_level":null,
+         "access_level_description":"Administrator",
+         "user_id":1,
+         "group_id":null
+      }
+   ]
+}
+```
+
+## Unprotect environment
+
+Unprotects the given protected environment:
+
+```bash
+DELETE /projects/:id/protected_environments/:name
+```
+
+```bash
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_environments/staging'
+```
+
+| 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 protected environment. |

ee/changelogs/unreleased/30595-api-for-protected-environments-docs.yml

+---
+title: Add API for protected environments
+merge_request: 23964
+author:
+type: added

ee/lib/api/protected_environments.rb

@@ -8,17 +8,13 @@ module API
 
     before { authorize_admin_project }
 
-    before do
-      not_found! unless Feature.enabled?(:protected_environments_api, user_project)
-    end
-
     params do
       requires :id, type: String, desc: 'The ID of a project'
     end
 
     resource :projects, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
       desc "Get a project's protected environments" do
-        detail 'This feature is gated by the :protected_environments_api feature flag.'
+        detail 'This feature was introduced in GitLab 12.8.'
         success ::EE::API::Entities::ProtectedEnvironment
       end
       params do
@@ -31,7 +27,7 @@ module API
       end
 
       desc 'Get a single protected environment' do
-        detail 'This feature is gated by the :protected_environments_api feature flag.'
+        detail 'This feature was introduced in GitLab 12.8.'
         success ::EE::API::Entities::ProtectedEnvironment
       end
       params do
@@ -42,7 +38,7 @@ module API
       end
 
       desc 'Protect a single environment' do
-        detail 'This feature is gated by the :protected_environments_api feature flag.'
+        detail 'This feature was introduced in GitLab 12.8.'
         success ::EE::API::Entities::ProtectedEnvironment
       end
       params do
@@ -77,7 +73,7 @@ module API
       end
 
       desc 'Unprotect a single environment' do
-        detail 'This feature is gated by the :protected_environments_api feature flag.'
+        detail 'This feature was introduced in GitLab 12.8.'
       end
       params do
         requires :name, type: String, desc: 'The name of the protected environment'

ee/spec/requests/api/protected_environments_spec.rb

@@ -39,14 +39,6 @@ describe API::ProtectedEnvironments do
         protected_environment_names = json_response.map { |x| x['name'] }
         expect(protected_environment_names).to match_array([protected_environment_name])
       end
-
-      context 'when feature is disabled' do
-        before do
-          stub_feature_flags(protected_environments_api: false)
-        end
-
-        it_behaves_like '404 response'
-      end
     end
 
     it_behaves_like 'requests for non-maintainers'