or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

additional-resources.mdcicd.mdclient-configuration.mdgroups.mdindex.mdissues.mdmerge-requests.mdpackage-registries.mdprojects.mdrepository-management.mdusers.md
tile.json

groups.mddocs/

Groups

Group management capabilities including creation, configuration, member management, subgroups, epics (Premium/Ultimate), and group-level settings.

Capabilities

Group Operations

List, create, show, edit, and delete groups with extensive querying and configuration options.

/**
 * Groups resource class for group management
 */
class Groups<C extends boolean = false> {
  /**
   * List all groups with filtering and pagination
   * @param options - Query options for filtering groups
   * @returns Array of groups
   */
  all<E extends boolean = false, P extends PaginationTypes = 'keyset'>(
    options?: AllGroupsOptions & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<GroupSchema[], C, E, P>>;

  /**
   * Get details of a single group
   * @param groupId - Group ID or URL-encoded path
   * @returns Group details with projects and shared projects
   */
  show<E extends boolean = false>(
    groupId: string | number,
    options?: BaseRequestOptions<E>
  ): Promise<GitlabAPIResponse<ExpandedGroupSchema, C, E, void>>;

  /**
   * Create a new group
   * @param name - Group name
   * @param path - Group path (URL segment)
   * @param options - Group configuration
   * @returns Created group
   */
  create<E extends boolean = false>(
    name: string,
    path: string,
    options?: CreateGroupOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ExpandedGroupSchema, C, E, void>>;

  /**
   * Update an existing group
   * @param groupId - Group ID or URL-encoded path
   * @param options - Fields to update
   * @returns Updated group
   */
  edit<E extends boolean = false>(
    groupId: string | number,
    options?: EditGroupOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ExpandedGroupSchema, C, E, void>>;

  /**
   * Delete a group
   * @param groupId - Group ID or URL-encoded path
   * @param options - Additional deletion options
   */
  remove<E extends boolean = false>(
    groupId: string | number,
    options?: { permanentlyRemove?: boolean | string; fullPath?: string } & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Usage Examples:

import { Gitlab } from '@gitbeaker/rest';

const api = new Gitlab({ token: process.env.GITLAB_TOKEN });

// List all accessible groups
const groups = await api.Groups.all({
  orderBy: 'name',
  sort: 'asc'
});

// Get group details
const group = await api.Groups.show('my-group');

// Create a new group
const newGroup = await api.Groups.create('Engineering Team', 'engineering', {
  description: 'Engineering department',
  visibility: 'private',
  lfsEnabled: true
});

// Update group settings
await api.Groups.edit('engineering', {
  description: 'Updated description',
  visibility: 'internal'
});

// Delete group
await api.Groups.remove('old-group');

Group Query Options

/**
 * Options for filtering and querying groups
 */
type AllGroupsOptions = {
  /** Skip groups with these IDs */
  skipGroups?: number[];
  /** Show all available groups */
  allAvailable?: boolean;
  /** Search term */
  search?: string;
  /** Order results by field */
  orderBy?: 'name' | 'path' | 'id';
  /** Sort direction */
  sort?: 'asc' | 'desc';
  /** Filter by visibility level */
  visibility?: 'public' | 'internal' | 'private';
  /** Include statistics */
  statistics?: boolean;
  /** Include custom attributes */
  withCustomAttributes?: boolean;
  /** Limit to owned groups */
  owned?: boolean;
  /** Minimum access level required */
  minAccessLevel?: Exclude<AccessLevel, AccessLevel.ADMIN>;
  /** Show only top-level groups */
  topLevelOnly?: boolean;
  /** Filter by marked for deletion date */
  markedForDeletionOn?: string;
  /** Show only active groups */
  active?: boolean;
  /** Include archived projects */
  archived?: boolean;
};

Subgroups and Hierarchy

Manage subgroups and navigate group hierarchies.

/**
 * List direct subgroups of a group
 * @param groupId - Parent group ID
 * @param options - Query options
 * @returns Array of subgroups
 */
allSubgroups<E extends boolean = false, P extends PaginationTypes = 'offset'>(
  groupId: string | number,
  options?: AllGroupsOptions & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<GroupSchema[], C, E, P>>;

/**
 * List all descendant groups (recursive)
 * @param groupId - Parent group ID
 * @param options - Query options
 * @returns Array of all descendant groups
 */
allDescendantGroups<E extends boolean = false, P extends PaginationTypes = 'offset'>(
  groupId: string | number,
  options?: AllGroupsOptions & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<GroupSchema[], C, E, P>>;

/**
 * Transfer group to different parent
 * @param groupId - Group ID to transfer
 * @param options - Target group ID
 */
transfer<E extends boolean = false>(
  groupId: string | number,
  options?: { groupId?: number } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

/**
 * List groups this group can be transferred to
 * @param groupId - Group ID
 * @returns Array of potential parent groups
 */
allTransferLocations<E extends boolean = false, P extends PaginationTypes = 'offset'>(
  groupId: string | number,
  options?: { search?: string } & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<SimpleGroupSchema[], C, E, P>>;

Usage Examples:

// Create subgroup
const subgroup = await api.Groups.create('Platform Team', 'platform', {
  parentId: 123,  // Parent group ID
  visibility: 'private'
});

// List direct subgroups
const subgroups = await api.Groups.allSubgroups(123);

// List all descendants (recursive)
const allDescendants = await api.Groups.allDescendantGroups(123, {
  statistics: true
});

// Transfer group to new parent
await api.Groups.transfer(456, {
  groupId: 789  // New parent group ID
});

Group Projects

Access projects within a group.

/**
 * List all projects in a group
 * @param groupId - Group ID
 * @param options - Query and filter options
 * @returns Array of projects
 */
allProjects<E extends boolean = false, P extends PaginationTypes = 'offset'>(
  groupId: string | number,
  options?: AllGroupProjectsOptions & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ProjectSchema[], C, E, P>>;

/**
 * List projects shared with the group
 * @param groupId - Group ID
 * @param options - Query options
 * @returns Array of shared projects
 */
allSharedProjects<E extends boolean = false, P extends PaginationTypes = 'offset'>(
  groupId: string | number,
  options?: AllGroupProjectsOptions & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ProjectSchema[], C, E, P>>;

/**
 * Transfer project to group
 * @param groupId - Group ID
 * @param projectId - Project ID to transfer
 */
transferProject<E extends boolean = false>(
  groupId: string | number,
  projectId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

Usage Examples:

// List group projects
const projects = await api.Groups.allProjects(123, {
  includeSubgroups: true,
  orderBy: 'last_activity_at',
  sort: 'desc'
});

// List shared projects
const sharedProjects = await api.Groups.allSharedProjects(123);

// Filter by archived status
const activeProjects = await api.Groups.allProjects(123, {
  archived: false,
  withIssuesEnabled: true
});

// Transfer project to group
await api.Groups.transferProject(123, 456);

Group Sharing

Share groups with other groups.

/**
 * Share group with another group
 * @param groupId - Group to share
 * @param sharedGroupId - Group to share with
 * @param groupAccess - Access level
 * @param options - Additional options (expiration date)
 * @returns Updated group
 */
share<E extends boolean = false>(
  groupId: string | number,
  sharedGroupId: string | number,
  groupAccess: number,
  options: { expiresAt?: string } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ExpandedGroupSchema, C, E, void>>;

/**
 * Remove group share
 * @param groupId - Group ID
 * @param sharedGroupId - Shared group ID to remove
 */
unshare<E extends boolean = false>(
  groupId: string | number,
  sharedGroupId: string | number,
  options: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

Usage Examples:

import { AccessLevel } from '@gitbeaker/rest';

// Share group with another group (Developer access)
await api.Groups.share(123, 456, AccessLevel.DEVELOPER, {
  expiresAt: '2024-12-31'
});

// Remove share
await api.Groups.unshare(123, 456);

SCIM Provisioning

Manage SCIM-provisioned users (Premium/Ultimate).

/**
 * List provisioned users in the group
 * @param groupId - Group ID
 * @param options - Filter options
 * @returns Array of provisioned users
 */
allProvisionedUsers<E extends boolean = false, P extends PaginationTypes = 'offset'>(
  groupId: string | number,
  options?: AllProvisionedUsersOptions & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<SimpleUserSchema[], C, E, P>>;

type AllProvisionedUsersOptions = {
  /** Filter by username */
  username?: string;
  /** Search term */
  search?: string;
  /** Filter active users */
  active?: boolean;
  /** Filter blocked users */
  blocked?: boolean;
  /** Filter by creation date (after) */
  createdAfter?: string;
  /** Filter by creation date (before) */
  createdBefore?: string;
};

Group Search

Search for groups by name or path.

/**
 * Search for groups
 * @param nameOrPath - Search term
 * @param options - Additional options
 * @returns Matching groups
 */
search<E extends boolean = false>(
  nameOrPath: string,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<GroupSchema[], C, E, void>>;

Group Avatars

Manage group avatars.

/**
 * Upload group avatar
 * @param groupId - Group ID
 * @param content - Image blob
 * @param options - Filename option
 * @returns Avatar URL
 */
uploadAvatar<E extends boolean = false>(
  groupId: string | number,
  content: Blob,
  options?: { filename?: string } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<{ avatar_url: string }, C, E, void>>;

/**
 * Download group avatar
 * @param groupId - Group ID
 * @returns Avatar image blob
 */
downloadAvatar<E extends boolean = false>(
  groupId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<Blob, void, E, void>>;

/**
 * Remove group avatar
 * @param groupId - Group ID
 */
removeAvatar<E extends boolean = false>(
  groupId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

Usage Examples:

// Upload avatar
const result = await api.Groups.uploadAvatar(123, avatarBlob, {
  filename: 'avatar.png'
});

// Download avatar
const avatarBlob = await api.Groups.downloadAvatar(123);

// Remove avatar
await api.Groups.removeAvatar(123);

Restore Deleted Groups

Restore groups marked for deletion (Premium/Ultimate).

/**
 * Restore a deleted group
 * @param groupId - Group ID
 */
restore<E extends boolean = false>(
  groupId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

Usage Example:

// Restore deleted group
await api.Groups.restore(123);

Related Group Resources

For managing specific group aspects, see the following resource classes:

Group Members and Access

  • GroupMembers - Manage group member access and permissions
  • GroupAccessRequests - Handle access requests to groups
  • GroupAccessTokens - Manage group access tokens
  • GroupInvitations - Send and manage group invitations
  • GroupMemberRoles - Custom member roles (Ultimate)

Group Configuration

  • GroupBadges - Configure group badges
  • GroupCustomAttributes - Store custom metadata
  • GroupHooks - Configure group-level webhooks
  • GroupLabels - Create and manage group labels
  • GroupMilestones - Track group-level milestones
  • GroupVariables - Manage group CI/CD variables
  • GroupProtectedEnvironments - Configure protected environments
  • GroupPushRules - Set up push rules for all projects
  • GroupLDAPLinks - LDAP group synchronization

Group Planning and Boards

  • GroupEpicBoards - Epic boards (Premium/Ultimate)
  • GroupIssueBoards - Group issue boards
  • GroupIterations - Manage iterations/sprints

Epics (Premium/Ultimate)

  • Epics - Epic management
  • EpicAwardEmojis - Emoji reactions on epics
  • EpicDiscussions - Epic discussions and threads
  • EpicIssues - Link issues to epics
  • EpicLabelEvents - Epic label change tracking
  • EpicLinks - Epic relationships (parent/child)
  • EpicNotes - Comments on epics
  • LinkedEpics - Link related epics

SAML and SCIM (Premium/Ultimate)

  • GroupSAMLIdentities - SAML identity management
  • GroupSAMLLinks - SAML group links
  • GroupSCIMIdentities - SCIM identity provisioning

Other Group Resources

  • GroupDORA4Metrics - DORA metrics for groups
  • GroupImportExports - Import/export groups
  • GroupMarkdownUploads - Upload files via Markdown
  • GroupRelationExports - Export group relations
  • GroupReleases - Group-level releases view
  • GroupRepositoryStorageMoves - Repository migration
  • GroupWikis - Group wikis
  • GroupActivityAnalytics - Group activity analytics
  • GroupServiceAccounts - Service account management

See Additional Resources for detailed documentation of these resource classes.