docs: variables: add note about filter for updating

JohnVillalovos · nejch · commit c378817389a9 · 2024-07-15T13:36:16.000+02:00
Add a note about using `filter` when updating a variable. Closes: #2835 Closes: #1387 Closes: #1125
diff --git a/docs/gl_objects/variables.rst b/docs/gl_objects/variables.rst
@@ -90,21 +90,46 @@ Get a variable::
     p_var = project.variables.get('key_name')
     g_var = group.variables.get('key_name')
 
+.. note::
+
+   If there are multiple variables with the same key, use ``filter`` to select
+   the correct ``environment_scope``. See the GitLab API docs for more
+   information.
+
 Create a variable::
 
     var = project.variables.create({'key': 'key1', 'value': 'value1'})
     var = group.variables.create({'key': 'key1', 'value': 'value1'})
 
+.. note::
+
+   If a variable with the same key already exists, the new variable must have a
+   different ``environment_scope``. Otherwise, GitLab returns a message similar
+   to: ``VARIABLE_NAME has already been taken``. See the GitLab API docs for
+   more information.
+
 Update a variable value::
 
     var.value = 'new_value'
     var.save()
     # or
     project.variables.update("key1", {"value": "new_value"})
 
+.. note::
+
+   If there are multiple variables with the same key, use ``filter`` to select
+   the correct ``environment_scope``. See the GitLab API docs for more
+   information.
+
 Remove a variable::
 
     project.variables.delete('key_name')
     group.variables.delete('key_name')
     # or
     var.delete()
+
+.. note::
+
+   If there are multiple variables with the same key, use ``filter`` to select
+   the correct ``environment_scope``. See the GitLab API docs for more
+   information.
