Skip to content

Commit 8e6a944

Browse files
author
Gauvain Pocentek
committed
docs: Add builds-related API docs
1 parent e0cf1c2 commit 8e6a944

File tree

3 files changed

+247
-0
lines changed

3 files changed

+247
-0
lines changed

‎docs/api-objects.rst

+1
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ API objects manipulation
55
.. toctree::
66

77
gl_objects/branches
8+
gl_objects/builds
89
gl_objects/projects
910
gl_objects/runners
1011
gl_objects/users

‎docs/gl_objects/builds.py

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# var list
2+
variables = gl.project_variables.list(project_id=1)
3+
# or
4+
variables = project.variables.list()
5+
# end var list
6+
7+
# var get
8+
var = gl.project_variables.get(var_key, project_id=1)
9+
# or
10+
var = project.variables.get(var_key)
11+
# end var get
12+
13+
# var create
14+
var = gl.project_variables.create({'key': 'key1', 'value': 'value1'},
15+
project_id=1)
16+
# or
17+
var = project.variables.create({'key': 'key1', 'value': 'value1'})
18+
# end var create
19+
20+
# var update
21+
var.value = 'new_value'
22+
var.save()
23+
# end var update
24+
25+
# var delete
26+
gl.project_variables.delete(var_key)
27+
# or
28+
project.variables.delete()
29+
# or
30+
var.delete()
31+
# end var delete
32+
33+
# trigger list
34+
triggers = gl.project_triggers.list(project_id=1)
35+
# or
36+
triggers = project.triggers.list()
37+
# end trigger list
38+
39+
# trigger get
40+
trigger = gl.project_triggers.get(trigger_token, project_id=1)
41+
# or
42+
trigger = project.triggers.get(trigger_token)
43+
# end trigger get
44+
45+
# trigger create
46+
trigger = gl.project_triggers.create({}, project_id=1)
47+
# or
48+
trigger = project.triggers.create({})
49+
# end trigger create
50+
51+
# trigger delete
52+
gl.project_triggers.delete(trigger_token)
53+
# or
54+
project.triggers.delete()
55+
# or
56+
trigger.delete()
57+
# end trigger delete
58+
59+
# list
60+
builds = gl.project_builds.list(project_id=1)
61+
# or
62+
builds = project.builds.list()
63+
# end list
64+
65+
# commit list
66+
commit = gl.project_commits.get(commit_sha, project_id=1)
67+
builds = commit.builds()
68+
# end commit list
69+
70+
# get
71+
build = gl.project_builds.get(build_id, project_id=1)
72+
# or
73+
project.builds.get(build_id)
74+
# end get
75+
76+
# artifacts
77+
build.artifacts()
78+
# end artifacts
79+
80+
# keep artifacts
81+
build.keep_artifacts()
82+
# end keep artifacts
83+
84+
# trace
85+
build.trace()
86+
# end trace
87+
88+
# retry
89+
build.cancel()
90+
build.retry()
91+
# end retry
92+
93+
# delete
94+
gl.project_builds.delete(build_id, project_id=1)
95+
# or
96+
project.builds.delete(build_id)
97+
# or
98+
build.delete()
99+
# end delete

‎docs/gl_objects/builds.rst

+147
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
######
2+
Builds
3+
######
4+
5+
Build triggers
6+
==============
7+
8+
Use :class:`~gitlab.objects.ProjectTrigger` objects to manipulate build
9+
triggers. The :attr:`gitlab.Gitlab.project_triggers` and
10+
:attr:`gitlab.objects.Projeect.triggers` manager objects provide helper
11+
functions.
12+
13+
Examples
14+
--------
15+
16+
List triggers:
17+
18+
.. literalinclude:: builds.py
19+
:start-after: # trigger list
20+
:end-before: # end trigger list
21+
22+
Get a trigger:
23+
24+
.. literalinclude:: builds.py
25+
:start-after: # trigger get
26+
:end-before: # end trigger get
27+
28+
Create a trigger:
29+
30+
.. literalinclude:: builds.py
31+
:start-after: # trigger create
32+
:end-before: # end trigger create
33+
34+
Remove a trigger:
35+
36+
.. literalinclude:: builds.py
37+
:start-after: # trigger delete
38+
:end-before: # end trigger delete
39+
40+
Build variables
41+
===============
42+
43+
Use :class:`~gitlab.objects.ProjectVariable` objects to manipulate build
44+
variables. The :attr:`gitlab.Gitlab.project_variables` and
45+
:attr:`gitlab.objects.Projeect.variables` manager objects provide helper
46+
functions.
47+
48+
Examples
49+
--------
50+
51+
List variables:
52+
53+
.. literalinclude:: builds.py
54+
:start-after: # var list
55+
:end-before: # end var list
56+
57+
Get a variable:
58+
59+
.. literalinclude:: builds.py
60+
:start-after: # var get
61+
:end-before: # end var get
62+
63+
Create a variable:
64+
65+
.. literalinclude:: builds.py
66+
:start-after: # var create
67+
:end-before: # end var create
68+
69+
Update a variable value:
70+
71+
.. literalinclude:: builds.py
72+
:start-after: # var update
73+
:end-before: # end var update
74+
75+
Remove a variable:
76+
77+
.. literalinclude:: builds.py
78+
:start-after: # var delete
79+
:end-before: # end var delete
80+
81+
Builds
82+
======
83+
84+
Use :class:`~gitlab.objects.ProjectBuild` objects to manipulate builds. The
85+
:attr:`gitlab.Gitlab.project_builds` and :attr:`gitlab.objects.Projeect.builds`
86+
manager objects provide helper functions.
87+
88+
Examples
89+
--------
90+
91+
List builds for the project:
92+
93+
.. literalinclude:: builds.py
94+
:start-after: # list
95+
:end-before: # end list
96+
97+
To list builds for a specific commit, create a
98+
:class:`~gitlab.objects.ProjectCommit` object and use its
99+
:attr:`~gitlab.objects.ProjectCommit.builds` method:
100+
101+
.. literalinclude:: builds.py
102+
:start-after: # commit list
103+
:end-before: # end commit list
104+
105+
Get a build:
106+
107+
.. literalinclude:: builds.py
108+
:start-after: # get
109+
:end-before: # end get
110+
111+
Get a build artifacts:
112+
113+
.. literalinclude:: builds.py
114+
:start-after: # artifacts
115+
:end-before: # end artifacts
116+
117+
.. warning::
118+
119+
Artifacts are entirely stored in memory.
120+
121+
Mark a build artifact as kept when expiration is set:
122+
123+
.. literalinclude:: builds.py
124+
:start-after: # keep artifacts
125+
:end-before: # end keep artifacts
126+
127+
Get a build trace:
128+
129+
.. literalinclude:: builds.py
130+
:start-after: # trace
131+
:end-before: # end trace
132+
133+
.. warning::
134+
135+
Traces are entirely stored in memory.
136+
137+
Cancel/retry a build:
138+
139+
.. literalinclude:: builds.py
140+
:start-after: # retry
141+
:end-before: # end retry
142+
143+
Erase a build:
144+
145+
.. literalinclude:: builds.py
146+
:start-after: # delete
147+
:end-before: # end delete

0 commit comments

Comments
 (0)