gitlab_*_variable: add description option (#10812)

changelogs/fragments/10812-gitlab-variable-add-description.yml

@@ -0,0 +1,4 @@
+minor_changes:
+  - gitlab_group_variable - add ``description`` option (https://github.com/ansible-collections/community.general/pull/10812).
+  - gitlab_instance_variable - add ``description`` option (https://github.com/ansible-collections/community.general/pull/10812).
+  - gitlab_project_variable - add ``description`` option (https://github.com/ansible-collections/community.general/pull/10812, https://github.com/ansible-collections/community.general/issues/8584, https://github.com/ansible-collections/community.general/issues/10809).

plugins/module_utils/gitlab.py

@@ -134,7 +134,7 @@ def gitlab_authentication(module, min_version=None):
 def filter_returned_variables(gitlab_variables):
     # pop properties we don't know
     existing_variables = [dict(x.attributes) for x in gitlab_variables]
-    KNOWN = ['key', 'value', 'masked', 'hidden', 'protected', 'variable_type', 'environment_scope', 'raw']
+    KNOWN = ['key', 'value', 'description', 'masked', 'hidden', 'protected', 'variable_type', 'environment_scope', 'raw']
     for item in existing_variables:
         for key in list(item.keys()):
             if key not in KNOWN:
@@ -151,6 +151,7 @@ def vars_to_variables(vars, module):
                 {
                     "name": item,
                     "value": str(value),
+                    "description": None,
                     "masked": False,
                     "protected": False,
                     "hidden": False,
@@ -163,6 +164,7 @@ def vars_to_variables(vars, module):
             new_item = {
                 "name": item,
                 "value": value.get('value'),
+                "description": value.get('description'),
                 "masked": value.get('masked'),
                 "hidden": value.get('hidden'),
                 "protected": value.get('protected'),

plugins/modules/gitlab_group_variable.py

@@ -87,6 +87,12 @@ options:
           - The variable value.
           - Required when O(state=present).
         type: str
+      description:
+        description:
+          - A description for the variable.
+          - Support for descriptions requires GitLab >= 16.2.
+        type: str
+        version_added: '11.4.0'
       masked:
         description:
           - Whether variable value is masked or not.
@@ -240,6 +246,7 @@ class GitlabGroupVariables(object):
         var = {
             "key": var_obj.get('key'),
             "value": var_obj.get('value'),
+            "description": var_obj.get('description'),
             "masked": var_obj.get('masked'),
             "masked_and_hidden": var_obj.get('hidden'),
             "protected": var_obj.get('protected'),
@@ -348,14 +355,13 @@ def native_python_main(this_gitlab, purge, requested_variables, state, module):
                     return_value['removed'].append(item)
 
     elif state == 'absent':
-        # value does not matter on removing variables.
+        # value, type, and description do not matter on removing variables.
-        # key and environment scope are sufficient
+        keys_ignored_on_deletion = ['value', 'variable_type', 'description']
-        for item in existing_variables:
+        for key in keys_ignored_on_deletion:
-            item.pop('value')
+            for item in existing_variables:
-            item.pop('variable_type')
+                item.pop(key)
-        for item in requested_variables:
+            for item in requested_variables:
-            item.pop('value')
+                item.pop(key)
-            item.pop('variable_type')
 
         if not purge:
             remove_requested = [x for x in requested_variables if x in existing_variables]
@@ -392,6 +398,7 @@ def main():
         variables=dict(type='list', elements='dict', default=list(), options=dict(
             name=dict(type='str', required=True),
             value=dict(type='str', no_log=True),
+            description=dict(type='str'),
             masked=dict(type='bool', default=False),
             hidden=dict(type='bool', default=False),
             protected=dict(type='bool', default=False),

plugins/modules/gitlab_instance_variable.py

@@ -64,6 +64,12 @@ options:
           - The variable value.
           - Required when O(state=present).
         type: str
+      description:
+        description:
+          - A description for the variable.
+          - Support for descriptions requires GitLab >= 16.8.
+        type: str
+        version_added: '11.4.0'
       masked:
         description:
           - Whether variable value is masked or not.
@@ -165,6 +171,7 @@ class GitlabInstanceVariables(object):
         var = {
             "key": var_obj.get('key'),
             "value": var_obj.get('value'),
+            "description": var_obj.get('description'),
             "masked": var_obj.get('masked'),
             "protected": var_obj.get('protected'),
             "raw": var_obj.get('raw'),
@@ -265,14 +272,13 @@ def native_python_main(this_gitlab, purge, requested_variables, state, module):
                     return_value['removed'].append(item)
 
     elif state == 'absent':
-        # value does not matter on removing variables.
+        # value, type, and description do not matter on removing variables.
-        # key and environment scope are sufficient
+        keys_ignored_on_deletion = ['value', 'variable_type', 'description']
-        for item in existing_variables:
+        for key in keys_ignored_on_deletion:
-            item.pop('value')
+            for item in existing_variables:
-            item.pop('variable_type')
+                item.pop(key)
-        for item in requested_variables:
+            for item in requested_variables:
-            item.pop('value')
+                item.pop(key)
-            item.pop('variable_type')
 
         if not purge:
             remove_requested = [x for x in requested_variables if x in existing_variables]
@@ -305,6 +311,7 @@ def main():
         variables=dict(type='list', elements='dict', default=list(), options=dict(
             name=dict(type='str', required=True),
             value=dict(type='str', no_log=True),
+            description=dict(type='str'),
             masked=dict(type='bool', default=False),
             protected=dict(type='bool', default=False),
             raw=dict(type='bool', default=False),

plugins/modules/gitlab_project_variable.py

@@ -86,6 +86,12 @@ options:
           - The variable value.
           - Required when O(state=present).
         type: str
+      description:
+        description:
+          - A description for the variable.
+          - Support for descriptions requires GitLab >= 16.2.
+        type: str
+        version_added: '11.4.0'
       masked:
         description:
           - Whether variable value is masked or not.
@@ -260,6 +266,7 @@ class GitlabProjectVariables(object):
         var = {
             "key": var_obj.get('key'),
             "value": var_obj.get('value'),
+            "description": var_obj.get('description'),
             "masked": var_obj.get('masked'),
             "masked_and_hidden": var_obj.get('hidden'),
             "protected": var_obj.get('protected'),
@@ -370,14 +377,13 @@ def native_python_main(this_gitlab, purge, requested_variables, state, module):
                     return_value['removed'].append(item)
 
     elif state == 'absent':
-        # value does not matter on removing variables.
+        # value, type, and description do not matter on removing variables.
-        # key and environment scope are sufficient
+        keys_ignored_on_deletion = ['value', 'variable_type', 'description']
-        for item in existing_variables:
+        for key in keys_ignored_on_deletion:
-            item.pop('value')
+            for item in existing_variables:
-            item.pop('variable_type')
+                item.pop(key)
-        for item in requested_variables:
+            for item in requested_variables:
-            item.pop('value')
+                item.pop(key)
-            item.pop('variable_type')
 
         if not purge:
             remove_requested = [x for x in requested_variables if x in existing_variables]
@@ -414,6 +420,7 @@ def main():
         variables=dict(type='list', elements='dict', default=list(), options=dict(
             name=dict(type='str', required=True),
             value=dict(type='str', no_log=True),
+            description=dict(type='str'),
             masked=dict(type='bool', default=False),
             hidden=dict(type='bool', default=False),
             protected=dict(type='bool', default=False),