# Groups

### Reference

- v4 API:

  - `gitlab.v4.objects.Group`

  - `gitlab.v4.objects.GroupManager`

  - `gitlab.Gitlab.groups`

- GitLab API: https://docs.gitlab.com/api/groups

### Examples

List the groups:

    groups = gl.groups.list(get_all=True)

Get a group’s detail:

    group = gl.groups.get(group_id)

List a group’s projects:

    projects = group.projects.list(get_all=True)

List a group’s shared projects:

    projects = group.shared_projects.list(get_all=True)

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(get_all=False)[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 the avatar image for a group:

    group.avatar = ""
    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.v4.objects.GroupExport`

  - `gitlab.v4.objects.GroupExportManager`

  - `gitlab.v4.objects.Group.exports`

  - `gitlab.v4.objects.GroupImport`

  - `gitlab.v4.objects.GroupImportManager`

  - `gitlab.v4.objects.Group.imports`

  - `gitlab.v4.objects.GroupManager.import_group`

- GitLab API: https://docs.gitlab.com/api/group_import_export

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

- v4 API:

  - `gitlab.v4.objects.GroupSubgroup`

  - `gitlab.v4.objects.GroupSubgroupManager`

  - `gitlab.v4.objects.Group.subgroups`

### Examples

List the subgroups for a group:

    subgroups = group.subgroups.list(get_all=True)

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(get_all=True)

## Descendant Groups

### Reference

- v4 API:

  - `gitlab.v4.objects.GroupDescendantGroup`

  - `gitlab.v4.objects.GroupDescendantGroupManager`

  - `gitlab.v4.objects.Group.descendant_groups`

### Examples

List the descendant groups of a group:

    descendant_groups = group.descendant_groups.list(get_all=True)

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

- v4 API:

  - `gitlab.v4.objects.GroupCustomAttribute`

  - `gitlab.v4.objects.GroupCustomAttributeManager`

  - `gitlab.v4.objects.Group.customattributes`

- GitLab API: https://docs.gitlab.com/api/custom_attributes

### Examples

List custom attributes for a group:

    attrs = group.customattributes.list(get_all=True)

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'}, get_all=True)

## 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.v4.objects.GroupMember`

  - `gitlab.v4.objects.GroupMemberManager`

  - `gitlab.v4.objects.GroupMemberAllManager`

  - `gitlab.v4.objects.GroupBillableMember`

  - `gitlab.v4.objects.GroupBillableMemberManager`

  - `gitlab.v4.objects.Group.members`

  - `gitlab.v4.objects.Group.members_all`

  - `gitlab.v4.objects.Group.billable_members`

- GitLab API: https://docs.gitlab.com/api/members

Billable group members are only available in GitLab EE.

### Examples

List only direct group members:

    members = group.members.list(get_all=True)

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(get_all=True)

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(get_all=True)

## 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(get_all=True)

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(get_all=True)

    # filter using a group name
    ldap_groups = gl.ldapgroups.list(search='foo', get_all=True)

    # list the groups for a specific LDAP provider
    ldap_groups = gl.ldapgroups.list(search='foo', provider='ldapmain', get_all=True)

## 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_all=True)

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.v4.objects.GroupHook`

  - `gitlab.v4.objects.GroupHookManager`

  - `gitlab.v4.objects.Group.hooks`

- GitLab API: https://docs.gitlab.com/api/groups#hooks

### Examples

List the group hooks:

    hooks = group.hooks.list(get_all=True)

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

- v4 API:

  - `gitlab.v4.objects.GroupPushRules`

  - `gitlab.v4.objects.GroupPushRulesManager`

  - `gitlab.v4.objects.Group.pushrules`

- GitLab API: https://docs.gitlab.com/api/groups#push-rules

### 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/api/groups#service-accounts

### Examples

Create group service account (only allowed at top level group):

    group.serviceaccount.create({'name': 'group-service-account', 'username': 'group-service-account'})