docs: variables: add note about filter for updating

JohnVillalovos · JohnVillalovos · commit 5706bec78eef · 2024-07-13T12:43:01.000-07: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,43 @@ 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.
