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()
List a group’s shared projects:
projects = group.shared_projects.list()
Note
GroupProject
and SharedProject
objects returned by these two API calls
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'})
Warning
On GitLab.com, creating top-level groups is currently not permitted using the API. You can only use the API to create subgroups.
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()
Restore a Group marked for deletion (Premium only)::
group.restore()
Share/unshare the group with a group:
group.share(group2.id, gitlab.const.AccessLevel.DEVELOPER)
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.AccessLevel.GUEST = 10
gitlab.const.AccessLevel.REPORTER = 20
gitlab.const.AccessLevel.DEVELOPER = 30
gitlab.const.AccessLevel.MAINTAINER = 40
gitlab.const.AccessLevel.OWNER = 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(get_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.AccessLevel.GUEST})
Update a member (change the access level):
member.access_level = gitlab.const.AccessLevel.DEVELOPER
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:
ldap_link = group.ldap_group_links.create({
'provider': 'ldapmain',
'group_access': gitlab.const.AccessLevel.DEVELOPER,
'cn: 'ldap_group_cn'
})
List a group’s LDAP group links:
group.ldap_group_links.list()
Remove a link:
ldap_link.delete()
# or by explicitly providing the CN or filter
group.ldap_group_links.delete(provider='ldapmain', cn='ldap_group_cn')
group.ldap_group_links.delete(provider='ldapmain', filter='(cn=Common Name)')
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')
SAML group links¶
Add a SAML group link to an existing GitLab group:
saml_link = group.saml_group_links.create({
"saml_group_name": "<your_saml_group_name>",
"access_level": <chosen_access_level>
})
List a group’s SAML group links:
group.saml_group_links.list()
Get a SAML group link:
group.saml_group_links.get("<your_saml_group_name>")
Remove a link:
saml_link.delete()
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()
Group push rules¶
Reference¶
Examples¶
Create group push rules (at least one rule is necessary):
group.pushrules.create({'deny_delete_tag': True})
Get group push rules:
pr = group.pushrules.get()
Edit group push rules:
pr.branch_name_regex = '^(master|develop|support-\d+|release-\d+\..+|hotfix-.+|feature-.+)$'
pr.save()
Delete group push rules:
pr.delete()
Group Service Account¶
Reference¶
v4 API:
gitlab.v4.objects.Group.serviceaccounts
GitLab API: https://docs.gitlab.com/ee/api/groups.html#service-accounts
Examples¶
Create group service account (only allowed at top level group):
group.serviceaccount.create({'name': 'group-service-account', 'username': 'group-service-account'})