###### Groups ###### Groups ====== Reference --------- * v4 API: + :class:`gitlab.v4.objects.Group` + :class:`gitlab.v4.objects.GroupManager` + :attr:`gitlab.Gitlab.groups` * 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() .. 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.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: + :class:`gitlab.v4.objects.GroupExport` + :class:`gitlab.v4.objects.GroupExportManager` + :attr:`gitlab.v4.objects.Group.exports` + :class:`gitlab.v4.objects.GroupImport` + :class:`gitlab.v4.objects.GroupImportManager` + :attr:`gitlab.v4.objects.Group.imports` + :attr:`gitlab.v4.objects.GroupManager.import_group` * 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 --------- * v4 API: + :class:`gitlab.v4.objects.GroupSubgroup` + :class:`gitlab.v4.objects.GroupSubgroupManager` + :attr:`gitlab.v4.objects.Group.subgroups` 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: + :class:`gitlab.v4.objects.GroupDescendantGroup` + :class:`gitlab.v4.objects.GroupDescendantGroupManager` + :attr:`gitlab.v4.objects.Group.descendant_groups` 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 --------- * v4 API: + :class:`gitlab.v4.objects.GroupCustomAttribute` + :class:`gitlab.v4.objects.GroupCustomAttributeManager` + :attr:`gitlab.v4.objects.Group.customattributes` * GitLab API: https://docs.gitlab.com/ce/api/custom_attributes.html 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: + :class:`gitlab.v4.objects.GroupMember` + :class:`gitlab.v4.objects.GroupMemberManager` + :class:`gitlab.v4.objects.GroupMemberAllManager` + :class:`gitlab.v4.objects.GroupBillableMember` + :class:`gitlab.v4.objects.GroupBillableMemberManager` + :attr:`gitlab.v4.objects.Group.members` + :attr:`gitlab.v4.objects.Group.members_all` + :attr:`gitlab.v4.objects.Group.billable_members` * 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 --------- * v4 API: + :class:`gitlab.v4.objects.GroupHook` + :class:`gitlab.v4.objects.GroupHookManager` + :attr:`gitlab.v4.objects.Group.hooks` * 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() Delete a group hook:: group.hooks.delete(hook_id) # or hook.delete()