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 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'})

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.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:

  1. Create an export using the API

  2. Wait for the export to be done

  3. 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#

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

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