API: Add "masked" attribute to variables

changelogs/unreleased/api_masked_variables.yml

+---
+title: 'API: Allow to get and set "masked" attribute for variables'
+merge_request: 28381
+author: Mathieu Parent
+type: added

doc/api/project_level_variables.md

@@ -52,7 +52,9 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
 {
     "key": "TEST_VARIABLE_1",
     "variable_type": "env_var",
-    "value": "TEST_1"
+    "value": "TEST_1",
+    "protected": false,
+    "masked": true
 }
 ```
 
@@ -64,14 +66,15 @@ Create a new variable.
 POST /projects/:id/variables
 ```
 
-| Attribute           | Type    | required | Description           |
-|---------------------|---------|----------|-----------------------|
-| `id`                | integer/string | yes      | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user   |
-| `key`               | string  | yes      | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed |
-| `value`             | string  | yes      | The `value` of a variable |
-| `variable_type`     | string  | no       | The type of a variable. Available types are: `env_var` (default) and `file` |
-| `protected`         | boolean | no       | Whether the variable is protected |
-| `environment_scope` | string  | no       | The `environment_scope` of the variable |
+| Attribute       | Type    | required | Description           |
+|-----------------|---------|----------|-----------------------|
+| `id`            | integer/string | yes      | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user   |
+| `key`           | string  | yes      | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed |
+| `value`         | string  | yes      | The `value` of a variable |
+| `variable_type` | string  | no       | The type of a variable. Available types are: `env_var` (default) and `file` |
+| `protected`     | boolean | no       | Whether the variable is protected |
+| `environment_scope` | string  | no   | The `environment_scope` of the variable |
+| `masked`        | boolean | no       | Whether the variable is masked |
 
 ```
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables" --form "key=NEW_VARIABLE" --form "value=new value"
@@ -81,9 +84,10 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla
 {
     "key": "NEW_VARIABLE",
     "value": "new value",
-    "protected": false,
-    "environment_scope": "*"
     "variable_type": "env_var",
+    "protected": false,
+    "environment_scope": "*",
+    "masked": false
 }
 ```
 
@@ -95,14 +99,15 @@ Update a project's variable.
 PUT /projects/:id/variables/:key
 ```
 
-| Attribute           | Type    | required | Description             |
-|---------------------|---------|----------|-------------------------|
-| `id`                | integer/string | yes      | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user     |
-| `key`               | string  | yes      | The `key` of a variable   |
-| `value`             | string  | yes      | The `value` of a variable |
-| `variable_type`     | string  | no       | The type of a variable. Available types are: `env_var` (default) and `file` |
-| `protected`         | boolean | no       | Whether the variable is protected |
-| `environment_scope` | string  | no       | The `environment_scope` of the variable |
+| Attribute       | Type    | required | Description             |
+|-----------------|---------|----------|-------------------------|
+| `id`            | integer/string | yes      | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user     |
+| `key`           | string  | yes      | The `key` of a variable   |
+| `value`         | string  | yes      | The `value` of a variable |
+| `variable_type` | string  | no       | The type of a variable. Available types are: `env_var` (default) and `file` |
+| `protected`     | boolean | no       | Whether the variable is protected |
+| `environment_scope` | string | no    | The `environment_scope` of the variable |
+| `masked`        | boolean | no       | Whether the variable is masked |
 
 ```
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value"
@@ -114,7 +119,8 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab
     "value": "updated value",
     "variable_type": "env_var",
     "protected": true,
-    "environment_scope": "*"
+    "environment_scope": "*",
+    "masked": false
 }
 ```
 

lib/api/entities.rb

@@ -1303,6 +1303,7 @@ module API
     class Variable < Grape::Entity
       expose :variable_type, :key, :value
       expose :protected?, as: :protected, if: -> (entity, _) { entity.respond_to?(:protected?) }
+      expose :masked?, as: :masked, if: -> (entity, _) { entity.respond_to?(:masked?) }
     end
 
     class Pipeline < PipelineBasic

lib/api/variables.rb

@@ -55,6 +55,7 @@ module API
         requires :key, type: String, desc: 'The key of the variable'
         requires :value, type: String, desc: 'The value of the variable'
         optional :protected, type: String, desc: 'Whether the variable is protected'
+        optional :masked, type: String, desc: 'Whether the variable is masked'
         optional :variable_type, type: String, values: Ci::Variable.variable_types.keys, desc: 'The type of variable, must be one of env_var or file. Defaults to env_var'
 
         if Gitlab.ee?
@@ -81,6 +82,7 @@ module API
         optional :key, type: String, desc: 'The key of the variable'
         optional :value, type: String, desc: 'The value of the variable'
         optional :protected, type: String, desc: 'Whether the variable is protected'
+        optional :masked, type: String, desc: 'Whether the variable is masked'
         optional :variable_type, type: String, values: Ci::Variable.variable_types.keys, desc: 'The type of variable, must be one of env_var or file'
 
         if Gitlab.ee?

spec/requests/api/variables_spec.rb

@@ -43,6 +43,7 @@ describe API::Variables do
         expect(response).to have_gitlab_http_status(200)
         expect(json_response['value']).to eq(variable.value)
         expect(json_response['protected']).to eq(variable.protected?)
+        expect(json_response['masked']).to eq(variable.masked?)
         expect(json_response['variable_type']).to eq('env_var')
       end
 
@@ -74,13 +75,14 @@ describe API::Variables do
     context 'authorized user with proper permissions' do
       it 'creates variable' do
         expect do
-          post api("/projects/#{project.id}/variables", user), params: { key: 'TEST_VARIABLE_2', value: 'PROTECTED_VALUE_2', protected: true }
+          post api("/projects/#{project.id}/variables", user), params: { key: 'TEST_VARIABLE_2', value: 'PROTECTED_VALUE_2', protected: true, masked: true }
         end.to change {project.variables.count}.by(1)
 
         expect(response).to have_gitlab_http_status(201)
         expect(json_response['key']).to eq('TEST_VARIABLE_2')
         expect(json_response['value']).to eq('PROTECTED_VALUE_2')
         expect(json_response['protected']).to be_truthy
+        expect(json_response['masked']).to be_truthy
         expect(json_response['variable_type']).to eq('env_var')
       end
 
@@ -93,6 +95,7 @@ describe API::Variables do
         expect(json_response['key']).to eq('TEST_VARIABLE_2')
         expect(json_response['value']).to eq('VALUE_2')
         expect(json_response['protected']).to be_falsey
+        expect(json_response['masked']).to be_falsey
         expect(json_response['variable_type']).to eq('file')
       end