Groups#
Groups#
Reference#
Examples#
List the groups:
groups = gl.groups.list()
Get a group’s detail:
group = gl.groups.get(group_id)
List a group’s projects:
projects = group.projects.list()
Note
GroupProject
objects returned by this API call are very limited, and do
not provide all the features of Project
objects. If you need to
manipulate projects, create a new Project
object:
first_group_project = group.projects.list()[0]
manageable_project = gl.projects.get(first_group_project.id, lazy=True)
You can filter and sort the result using the following parameters:
archived
: limit by archived statusvisibility
: limit by visibility. Allowed values arepublic
,internal
andprivate
search
: limit to groups matching the given valueorder_by
: sort by criteria. Allowed values areid
,name
,path
,created_at
,updated_at
andlast_activity_at
sort
: sort order:asc
ordesc
ci_enabled_first
: return CI enabled groups firstinclude_subgroups
: include projects in subgroups
Create a group:
group = gl.groups.create({'name': 'group1', 'path': 'group1'})
Create a subgroup under an existing group:
subgroup = gl.groups.create({'name': 'subgroup1', 'path': 'subgroup1', 'parent_id': parent_group_id})
Update a group:
group.description = 'My awesome group'
group.save()
Set the avatar image for a group:
# the avatar image can be passed as data (content of the file) or as a file
# object opened in binary mode
group.avatar = open('path/to/file.png', 'rb')
group.save()
Remove a group:
gl.groups.delete(group_id)
# or
group.delete()
Share/unshare the group with a group:
group.share(group2.id, gitlab.const.DEVELOPER_ACCESS)
group.unshare(group2.id)
Import / Export#
You can export groups from gitlab, and re-import them to create new groups.
Reference#
v4 API:
GitLab API: https://docs.gitlab.com/ce/api/group_import_export.html
Examples#
A group export is an asynchronous operation. To retrieve the archive generated by GitLab you need to:
Create an export using the API
Wait for the export to be done
Download the result
Warning
Unlike the Project Export API, GitLab does not provide an export_status for Group Exports. It is up to the user to ensure the export is finished.
However, Group Exports only contain metadata, so they are much faster than Project Exports.
# Create the export
group = gl.groups.get(my_group)
export = group.exports.create()
# Wait for the export to finish
time.sleep(3)
# Download the result
with open('/tmp/export.tgz', 'wb') as f:
export.download(streamed=True, action=f.write)
Import the group:
with open('/tmp/export.tgz', 'rb') as f:
gl.groups.import_group(f, path='imported-group', name="Imported Group")
Subgroups#
Reference#
Examples#
List the subgroups for a group:
subgroups = group.subgroups.list()
Note
The GroupSubgroup
objects don’t expose the same API as the Group
objects. If you need to manipulate a subgroup as a group, create a new
Group
object:
real_group = gl.groups.get(subgroup_id, lazy=True)
real_group.issues.list()
Descendant Groups#
Reference#
Examples#
List the descendant groups of a group:
descendant_groups = group.descendant_groups.list()
Note
Like the GroupSubgroup
objects described above, GroupDescendantGroup
objects do not expose the same API as the Group
objects. Create a new
Group
object instead if needed, as shown in the subgroup example.
Group custom attributes#
Reference#
Examples#
List custom attributes for a group:
attrs = group.customattributes.list()
Get a custom attribute for a group:
attr = group.customattributes.get(attr_key)
Set (create or update) a custom attribute for a group:
attr = group.customattributes.set(attr_key, attr_value)
Delete a custom attribute for a group:
attr.delete()
# or
group.customattributes.delete(attr_key)
Search groups by custom attribute:
group.customattributes.set('role': 'admin')
gl.groups.list(custom_attributes={'role': 'admin'})
Group members#
The following constants define the supported access levels:
gitlab.const.GUEST_ACCESS = 10
gitlab.const.REPORTER_ACCESS = 20
gitlab.const.DEVELOPER_ACCESS = 30
gitlab.const.MAINTAINER_ACCESS = 40
gitlab.const.OWNER_ACCESS = 50
Reference#
v4 API:
GitLab API: https://docs.gitlab.com/ce/api/members.html
Billable group members are only available in GitLab EE.
Examples#
List only direct group members:
members = group.members.list()
List the group members recursively (including inherited members through ancestor groups):
members = group.members_all.list(all=True)
Get only direct group member:
members = group.members.get(member_id)
Get a member of a group, including members inherited through ancestor groups:
members = group.members_all.get(member_id)
Add a member to the group:
member = group.members.create({'user_id': user_id,
'access_level': gitlab.const.GUEST_ACCESS})
Update a member (change the access level):
member.access_level = gitlab.const.DEVELOPER_ACCESS
member.save()
Remove a member from the group:
group.members.delete(member_id)
# or
member.delete()
List billable members of a group (top-level groups only):
billable_members = group.billable_members.list()
Remove a billable member from the group:
group.billable_members.delete(member_id)
# or
billable_member.delete()
List memberships of a billable member:
billable_member.memberships.list()
LDAP group links#
Add an LDAP group link to an existing GitLab group:
group.add_ldap_group_link(ldap_group_cn, gitlab.const.DEVELOPER_ACCESS, 'ldapmain')
Remove a link:
group.delete_ldap_group_link(ldap_group_cn, 'ldapmain')
Sync the LDAP groups:
group.ldap_sync()
You can use the ldapgroups
manager to list available LDAP groups:
# listing (supports pagination)
ldap_groups = gl.ldapgroups.list()
# filter using a group name
ldap_groups = gl.ldapgroups.list(search='foo')
# list the groups for a specific LDAP provider
ldap_groups = gl.ldapgroups.list(search='foo', provider='ldapmain')
Groups hooks#
Reference#
Examples#
List the group hooks:
hooks = group.hooks.list()
Get a group hook:
hook = group.hooks.get(hook_id)
Create a group hook:
hook = group.hooks.create({'url': 'http://my/action/url', 'push_events': 1})
Update a group hook:
hook.push_events = 0
hook.save()
Delete a group hook:
group.hooks.delete(hook_id)
# or
hook.delete()