Skip to content

Commit 4d871aa

Browse files
author
Gauvain Pocentek
committed
docs: groups API documentation
1 parent 048b1cf commit 4d871aa

File tree

3 files changed

+178
-0
lines changed

3 files changed

+178
-0
lines changed

‎docs/api-objects.rst

+1
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ API objects manipulation
66

77
gl_objects/branches
88
gl_objects/builds
9+
gl_objects/groups
910
gl_objects/projects
1011
gl_objects/runners
1112
gl_objects/users

‎docs/gl_objects/groups.py

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# list
2+
groups = gl.groups.list()
3+
# end list
4+
5+
# search
6+
groups = gl.groups.search('group')
7+
# end search
8+
9+
# get
10+
group = gl.groups.get(group_id)
11+
# end get
12+
13+
# projects list
14+
projects = group.projects.list()
15+
# or
16+
projects = gl.group_projects.list(group_id)
17+
# end projects list
18+
19+
# create
20+
group = gl.groups.create({'name': 'group1', 'path': 'group1'})
21+
# end create
22+
23+
# update
24+
group.description = 'My awesome group'
25+
group.save()
26+
# end update
27+
28+
# delete
29+
gl.group.delete(group_id)
30+
# or
31+
group.delete()
32+
# end delete
33+
34+
# member list
35+
members = gl.group_members.list(group_id=1)
36+
# or
37+
members = group.members.list()
38+
# end member list
39+
40+
# member get
41+
members = gl.group_members.get(member_id)
42+
# or
43+
members = group.members.get(member_id)
44+
# end member get
45+
46+
# member create
47+
member = gl.group_members.create({'user_id': user_id,
48+
'access_level': Group.GUEST_ACCESS},
49+
group_id=1)
50+
# or
51+
member = group.members.create({'user_id': user_id,
52+
'access_level': Group.GUEST_ACCESS})
53+
# end member create
54+
55+
# member update
56+
member.access_level = Group.DEVELOPER_ACCESS
57+
member.save()
58+
# end member update
59+
60+
# member delete
61+
gl.group_members.delete(member_id, group_id=1)
62+
# or
63+
group.members.delete(member_id)
64+
# or
65+
member.delete()
66+
# end member delete

‎docs/gl_objects/groups.rst

+111
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
######
2+
Groups
3+
######
4+
5+
Groups
6+
======
7+
8+
Use :class:`~gitlab.objects.Group` objects to manipulate groups. The
9+
:attr:`gitlab.Gitlab.groups` manager object provides helper functions.
10+
11+
Examples
12+
--------
13+
14+
List the groups:
15+
16+
.. literalinclude:: groups.py
17+
:start-after: # list
18+
:end-before: # end list
19+
20+
Search groups:
21+
22+
.. literalinclude:: groups.py
23+
:start-after: # search
24+
:end-before: # end search
25+
26+
Get a group's detail:
27+
28+
.. literalinclude:: groups.py
29+
:start-after: # get
30+
:end-before: # end get
31+
32+
List a group's projects:
33+
34+
.. literalinclude:: groups.py
35+
:start-after: # projects list
36+
:end-before: # end projects list
37+
38+
You can filter and sort the result using the following parameters:
39+
40+
* ``archived``: limit by archived status
41+
* ``visibility``: limit by visibility. Allowed values are ``public``,
42+
``internal`` and ``private``
43+
* ``search``: limit to groups matching the given value
44+
* ``order_by``: sort by criteria. Allowed values are ``id``, ``name``, ``path``,
45+
``created_at``, ``updated_at`` and ``last_activity_at``
46+
* ``sort``: sort order: ``asc`` or ``desc``
47+
* ``ci_enabled_first``: return CI enabled groups first
48+
49+
Create a group:
50+
51+
.. literalinclude:: groups.py
52+
:start-after: # create
53+
:end-before: # end create
54+
55+
Update a group:
56+
57+
.. literalinclude:: groups.py
58+
:start-after: # update
59+
:end-before: # end update
60+
61+
Remove a group:
62+
63+
.. literalinclude:: groups.py
64+
:start-after: # delete
65+
:end-before: # end delete
66+
67+
Group members
68+
=============
69+
70+
Use :class:`~gitlab.objects.GroupMember` objects to manipulate groups. The
71+
:attr:`gitlab.Gitlab.group_members` and :attr:`Group.members
72+
<gitlab.objects.Group.members>` manager objects provide helper functions.
73+
74+
The following :class:`~gitlab.objects.Group` attributes define the supported
75+
access levels:
76+
77+
* ``GUEST_ACCESS = 10``
78+
* ``REPORTER_ACCESS = 20``
79+
* ``DEVELOPER_ACCESS = 30``
80+
* ``MASTER_ACCESS = 40``
81+
* ``OWNER_ACCESS = 50``
82+
83+
List group members:
84+
85+
.. literalinclude:: groups.py
86+
:start-after: # member list
87+
:end-before: # end member list
88+
89+
Get a group member:
90+
91+
.. literalinclude:: groups.py
92+
:start-after: # member get
93+
:end-before: # end member get
94+
95+
Add a member to the group:
96+
97+
.. literalinclude:: groups.py
98+
:start-after: # member create
99+
:end-before: # end member create
100+
101+
Update a member (change the access level):
102+
103+
.. literalinclude:: groups.py
104+
:start-after: # member update
105+
:end-before: # end member update
106+
107+
Remove a member from the group:
108+
109+
.. literalinclude:: groups.py
110+
:start-after: # member delete
111+
:end-before: # end member delete

0 commit comments

Comments
 (0)