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

issues.mddocs/

Issues

Comprehensive issue tracking capabilities including creation, editing, comments, labels, milestones, time tracking, relationships, and metric images.

Capabilities

Issue Operations

Create, read, update, and delete issues with extensive filtering and query options.

/**
 * Issues resource class for issue management
 */
class Issues<C extends boolean = false> {
  /**
   * List issues with filtering and pagination
   * @param options - Query options including projectId, groupId, or global
   * @returns Array of issues
   */
  all<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    options?: OneOrNoneOf<{ projectId: string | number; groupId: string | number }>
      & AllIssuesOptions & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<IssueSchema[], C, E, P>>;

  /**
   * Get details of a single issue
   * @param issueId - Issue IID (internal ID)
   * @param options - Optional projectId for scoping
   * @returns Issue details
   */
  show<E extends boolean = false>(
    issueId: number,
    options?: { projectId?: string | number } & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<IssueSchema, C, E, void>>;

  /**
   * Create a new issue
   * @param projectId - Project ID or path
   * @param title - Issue title
   * @param options - Issue configuration
   * @returns Created issue
   */
  create<E extends boolean = false>(
    projectId: string | number,
    title: string,
    options?: CreateIssueOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<IssueSchema, C, E, void>>;

  /**
   * Update an existing issue
   * @param projectId - Project ID or path
   * @param issueIid - Issue IID
   * @param options - Fields to update
   * @returns Updated issue
   */
  edit<E extends boolean = false>(
    projectId: string | number,
    issueIid: number,
    options?: EditIssueOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<IssueSchema, C, E, void>>;

  /**
   * Delete an issue
   * @param projectId - Project ID or path
   * @param issueIid - Issue IID
   */
  remove<E extends boolean = false>(
    projectId: string | number,
    issueIid: number,
    options?: 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 issues in a project
const issues = await api.Issues.all({
  projectId: 123,
  state: 'opened',
  orderBy: 'created_at',
  sort: 'desc'
});

// Get specific issue
const issue = await api.Issues.show(5, { projectId: 123 });

// Create new issue
const newIssue = await api.Issues.create(123, 'Bug: Login not working', {
  description: 'Users cannot log in with SSO',
  labels: 'bug,priority::high',
  assigneeIds: [456],
  milestoneId: 10
});

// Update issue
await api.Issues.edit(123, 5, {
  stateEvent: 'close',
  labels: 'bug,resolved'
});

// Delete issue
await api.Issues.remove(123, 5);

Issue Query Options

/**
 * Options for filtering and querying issues
 */
type AllIssuesOptions = {
  /** Filter by assignee user ID */
  assigneeId?: number;
  /** Filter by assignee usernames */
  assigneeUsername?: string[];
  /** Filter by author user ID */
  authorId?: number;
  /** Filter by author username */
  authorUsername?: string;
  /** Filter confidential issues */
  confidential?: boolean;
  /** Created after date (ISO 8601) */
  createdAfter?: string;
  /** Created before date (ISO 8601) */
  createdBefore?: string;
  /** Filter by due date */
  dueDate?: string;
  /** Filter by epic ID (Premium/Ultimate) */
  epicId?: number;
  /** Filter by health status */
  healthStatus?: string;
  /** Filter by issue IIDs */
  iids?: number[];
  /** Search in specific fields */
  in?: string;
  /** Filter by issue type */
  issueType?: string;
  /** Filter by iteration ID */
  iterationId?: number;
  /** Filter by iteration title */
  iterationTitle?: string;
  /** Filter by labels (comma-separated) */
  labels?: string;
  /** Filter by milestone title */
  milestone?: string;
  /** Filter by milestone ID */
  milestoneId?: string;
  /** Filter by reaction emoji */
  myReactionEmoji?: string;
  /** Exclude archived projects */
  nonArchived?: boolean;
  /** Negation filters */
  not?: Record<string, string>;
  /** Order results by field */
  orderBy?: string;
  /** Filter scope */
  scope?: string;
  /** Search term */
  search?: string;
  /** Sort direction */
  sort?: string;
  /** Filter by state */
  state?: string;
  /** Updated after date */
  updatedAfter?: string;
  /** Updated before date */
  updatedBefore?: string;
  /** Filter by weight (Premium/Ultimate) */
  weight?: number;
  /** Return expanded label details */
  withLabelsDetails?: boolean;
};

Time Tracking

Track time estimates and spent time on issues.

/**
 * Add time spent on an issue
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @param duration - Duration string (e.g., "1h 30m", "2d")
 * @param options - Optional summary
 * @returns Updated time stats
 */
addSpentTime<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  duration: string,
  options?: { summary?: string } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<TimeStatsSchema, C, E, void>>;

/**
 * Set time estimate for an issue
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @param duration - Duration string (e.g., "3h", "1d 4h")
 * @returns Updated time stats
 */
addTimeEstimate<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  duration: string,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<TimeStatsSchema, C, E, void>>;

/**
 * Reset time spent to zero
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @returns Updated time stats
 */
resetSpentTime<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<TimeStatsSchema, C, E, void>>;

/**
 * Reset time estimate to zero
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @returns Updated time stats
 */
resetTimeEstimate<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<TimeStatsSchema, C, E, void>>;

/**
 * Get time tracking stats for an issue
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @returns Time stats
 */
showTimeStats<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<TimeStatsSchema, C, E, void>>;

Usage Examples:

// Add time spent (1 hour 30 minutes)
await api.Issues.addSpentTime(123, 5, '1h 30m', {
  summary: 'Fixed login bug'
});

// Set time estimate (3 days)
await api.Issues.addTimeEstimate(123, 5, '3d');

// Get time stats
const timeStats = await api.Issues.showTimeStats(123, 5);
console.log(timeStats.human_time_estimate); // "3 days"
console.log(timeStats.human_total_time_spent); // "1 hour 30 minutes"

// Reset spent time
await api.Issues.resetSpentTime(123, 5);

Issue Relationships

Manage relationships between issues and other resources.

/**
 * List participants in an issue
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @returns Array of participating users
 */
allParticipants<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<SimpleUserSchema[], C, E, void>>;

/**
 * List merge requests related to the issue
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @returns Array of related merge requests
 */
allRelatedMergeRequests<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<MergeRequestSchema[], C, E, void>>;

/**
 * List merge requests that will close the issue
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @returns Array of merge requests
 */
allClosedByMergeRequestst<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<MergeRequestSchema[], C, E, void>>;

Issue Operations

Additional issue operations including cloning, moving, and subscriptions.

/**
 * Clone an issue to another project
 * @param projectId - Source project ID
 * @param issueIid - Issue IID to clone
 * @param destinationProjectId - Target project ID
 * @param options - Clone options (withNotes)
 * @returns Cloned issue
 */
clone<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  destinationProjectId: string | number,
  options?: { withNotes?: boolean } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<IssueSchema, C, E, void>>;

/**
 * Move an issue to another project
 * @param projectId - Source project ID
 * @param issueIid - Issue IID to move
 * @param destinationProjectId - Target project ID
 * @returns Moved issue (in new project)
 */
move<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  destinationProjectId: string | number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<IssueSchema, C, E, void>>;

/**
 * Promote issue to epic (Premium/Ultimate)
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @param body - Note body (will include /promote command)
 * @returns Promoted issue
 */
promote<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  body: string,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<IssueSchema, C, E, void>>;

/**
 * Reorder issue in issue list
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @param options - Move position options
 */
reorder<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  options?: { moveAfterId?: number; moveBeforeId?: number } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

/**
 * Subscribe to issue notifications
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @returns Updated issue
 */
subscribe<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<IssueSchema, C, E, void>>;

/**
 * Unsubscribe from issue notifications
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @returns Updated issue
 */
unsubscribe<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<IssueSchema, C, E, void>>;

/**
 * Create a todo for the issue
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @returns Created todo
 */
createTodo<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<TodoSchema, C, E, void>>;

Usage Examples:

// Clone issue to another project
const clonedIssue = await api.Issues.clone(123, 5, 456, {
  withNotes: true
});

// Move issue to another project
const movedIssue = await api.Issues.move(123, 5, 456);

// Subscribe to notifications
await api.Issues.subscribe(123, 5);

// Unsubscribe
await api.Issues.unsubscribe(123, 5);

// Create todo
await api.Issues.createTodo(123, 5);

// Reorder issue (move after issue #3)
await api.Issues.reorder(123, 5, {
  moveAfterId: 3
});

Metric Images

Upload and manage metric images for issues (for incident management).

/**
 * List metric images attached to an issue
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @returns Array of metric images
 */
allMetricImages<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<MetricImageSchema[], C, E, void>>;

/**
 * Upload a metric image to an issue
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @param metricImage - Image file
 * @param options - URL and URL text options
 * @returns Uploaded metric image
 */
uploadMetricImage<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  metricImage: { content: Blob; filename: string },
  options?: { url?: string; urlText?: string } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<MetricImageSchema, C, E, void>>;

/**
 * Update a metric image
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @param imageId - Metric image ID
 * @param options - Fields to update
 * @returns Updated metric image
 */
editMetricImage<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  imageId: number,
  options?: { url?: string; urlText?: string } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<MetricImageSchema, C, E, void>>;

/**
 * Remove a metric image
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @param imageId - Metric image ID
 */
removeMetricImage<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  imageId: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<void, C, E, void>>;

Usage Examples:

// Upload metric image
const metricImage = await api.Issues.uploadMetricImage(123, 5, {
  content: imageBlob,
  filename: 'metrics.png'
}, {
  url: 'https://grafana.example.com/dashboard/123',
  urlText: 'View in Grafana'
});

// List metric images
const images = await api.Issues.allMetricImages(123, 5);

// Update metric image
await api.Issues.editMetricImage(123, 5, 789, {
  urlText: 'Updated Dashboard Link'
});

// Remove metric image
await api.Issues.removeMetricImage(123, 5, 789);

User Agent Details

Get user agent information for issues created via service desk or API.

/**
 * Show user agent details for an issue
 * @param projectId - Project ID
 * @param issueIid - Issue IID
 * @returns User agent details
 */
showUserAgentDetails<E extends boolean = false>(
  projectId: string | number,
  issueIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<UserAgentDetailSchema, C, E, void>>;

Related Issue Resources

For working with issue-related features, see the following resource classes:

Issue Comments and Discussions

  • IssueNotes - Create and manage issue comments
  • IssueNoteAwardEmojis - React to issue comments with emojis
  • IssueDiscussions - Manage threaded discussions on issues

Issue Tracking and Events

  • IssueAwardEmojis - React to issues with emojis
  • IssueLinks - Link related issues together
  • IssueLabelEvents - Track label change history
  • IssueMilestoneEvents - Track milestone changes
  • IssueStateEvents - Track state changes (opened, closed, etc.)
  • IssueIterationEvents - Track iteration changes (Premium/Ultimate)
  • IssueWeightEvents - Track weight changes (Premium/Ultimate)

Issue Statistics

  • IssuesStatistics - Get issue statistics and metrics

Project Issue Boards

  • ProjectIssueBoards - Manage project-level issue boards
  • GroupIssueBoards - Manage group-level issue boards

See Additional Resources for detailed documentation of these resource classes.