Groups¶

Reference¶

v4 API:
GitLab API: https://docs.gitlab.com/ce/api/groups.html

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 status
visibility: limit by visibility. Allowed values are public, internal and private
search: limit to groups matching the given value
order_by: sort by criteria. Allowed values are id, name, path, created_at, updated_at and last_activity_at
sort: sort order: asc or desc
ci_enabled_first: return CI enabled groups first
include_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¶

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¶

v4 API:

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¶

v4 API:

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¶

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¶

v4 API:
GitLab API: https://docs.gitlab.com/ce/api/groups.html#hooks

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()

Test a group hook:

hook.test("push_events")

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.GroupServiceAccount
- gitlab.v4.objects.GroupServiceAccountManager
- 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'})