docs(variables): add docs for instance-level variables

nejch · nejch · commit f12ffc83f9cd · 2020-08-30T18:17:01.000+02:00
diff --git a/docs/api-objects.rst b/docs/api-objects.rst
@@ -48,5 +48,6 @@ API examples
    gl_objects/templates
    gl_objects/todos
    gl_objects/users
+   gl_objects/variables
    gl_objects/sidekiq
    gl_objects/wikis
diff --git a/docs/gl_objects/pipelines_and_jobs.rst b/docs/gl_objects/pipelines_and_jobs.rst
@@ -184,58 +184,6 @@ Delete a schedule variable::
 
     var.delete()
 
-Projects and groups variables
-=============================
-
-You can associate variables to projects and groups to modify the build/job
-scripts behavior.
-
-Reference
----------
-
-* v4 API
-
-  + :class:`gitlab.v4.objects.ProjectVariable`
-  + :class:`gitlab.v4.objects.ProjectVariableManager`
-  + :attr:`gitlab.v4.objects.Project.variables`
-  + :class:`gitlab.v4.objects.GroupVariable`
-  + :class:`gitlab.v4.objects.GroupVariableManager`
-  + :attr:`gitlab.v4.objects.Group.variables`
-
-* GitLab API
-
-  + https://docs.gitlab.com/ce/api/project_level_variables.html
-  + https://docs.gitlab.com/ce/api/group_level_variables.html
-
-Examples
---------
-
-List variables::
-
-    p_variables = project.variables.list()
-    g_variables = group.variables.list()
-
-Get a variable::
-
-    p_var = project.variables.get('key_name')
-    g_var = group.variables.get('key_name')
-
-Create a variable::
-
-    var = project.variables.create({'key': 'key1', 'value': 'value1'})
-    var = group.variables.create({'key': 'key1', 'value': 'value1'})
-
-Update a variable value::
-
-    var.value = 'new_value'
-    var.save()
-
-Remove a variable::
-
-    project.variables.delete('key_name')
-    group.variables.delete('key_name')
-    # or
-    var.delete()
 
 Jobs
 ====
diff --git a/docs/gl_objects/variables.rst b/docs/gl_objects/variables.rst
@@ -0,0 +1,102 @@
+###############
+CI/CD Variables
+###############
+
+You can configure variables at the instance-level (admin only), or associate
+variables to projects and groups, to modify pipeline/job scripts behavior.
+
+
+Instance-level variables
+========================
+
+This endpoint requires admin access.
+
+Reference
+---------
+
+* v4 API
+
+  + :class:`gitlab.v4.objects.Variable`
+  + :class:`gitlab.v4.objects.VariableManager`
+  + :attr:`gitlab.Gitlab.variables`
+
+* GitLab API
+
+  + https://docs.gitlab.com/ce/api/instance_level_ci_variables.html
+
+Examples
+--------
+
+List all instance variables::
+
+    variables = gl.variables.list()
+
+Get an instance variable by key::
+
+    variable = gl.variables.get('key_name')
+
+Create an instance variable::
+
+    variable = gl.variables.create({'key': 'key1', 'value': 'value1'})
+
+Update a variable value::
+
+    variable.value = 'new_value'
+    variable.save()
+
+Remove a variable::
+
+    gl.variables.delete('key_name')
+    # or
+    variable.delete()
+
+Projects and groups variables
+=============================
+
+Reference
+---------
+
+* v4 API
+
+  + :class:`gitlab.v4.objects.ProjectVariable`
+  + :class:`gitlab.v4.objects.ProjectVariableManager`
+  + :attr:`gitlab.v4.objects.Project.variables`
+  + :class:`gitlab.v4.objects.GroupVariable`
+  + :class:`gitlab.v4.objects.GroupVariableManager`
+  + :attr:`gitlab.v4.objects.Group.variables`
+
+* GitLab API
+
+  + https://docs.gitlab.com/ce/api/instance_level_ci_variables.html
+  + https://docs.gitlab.com/ce/api/project_level_variables.html
+  + https://docs.gitlab.com/ce/api/group_level_variables.html
+
+Examples
+--------
+
+List variables::
+
+    p_variables = project.variables.list()
+    g_variables = group.variables.list()
+
+Get a variable::
+
+    p_var = project.variables.get('key_name')
+    g_var = group.variables.get('key_name')
+
+Create a variable::
+
+    var = project.variables.create({'key': 'key1', 'value': 'value1'})
+    var = group.variables.create({'key': 'key1', 'value': 'value1'})
+
+Update a variable value::
+
+    var.value = 'new_value'
+    var.save()
+
+Remove a variable::
+
+    project.variables.delete('key_name')
+    group.variables.delete('key_name')
+    # or
+    var.delete()
