or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

additional-resources.md cicd.md client-configuration.md groups.md index.md issues.md merge-requests.md package-registries.md projects.md repository-management.md users.md

tile.json

Merge Requests

Comprehensive merge request management including creation, approval, merging, discussions, pipeline integration, and code review workflows.

Capabilities

Merge Request Operations

Create, read, update, delete, and merge merge requests with extensive filtering and configuration.

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

  /**
   * Get details of a single merge request
   * @param projectId - Project ID or path
   * @param mergerequestIid - Merge request IID
   * @param options - Additional options
   * @returns Merge request details
   */
  show<E extends boolean = false>(
    projectId: string | number,
    mergerequestIid: number,
    options?: ShowMergeRequestOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ExpandedMergeRequestSchema, C, E, void>>;

  /**
   * Create a new merge request
   * @param projectId - Project ID or path
   * @param sourceBranch - Source branch name
   * @param targetBranch - Target branch name
   * @param title - Merge request title
   * @param options - MR configuration
   * @returns Created merge request
   */
  create<E extends boolean = false>(
    projectId: string | number,
    sourceBranch: string,
    targetBranch: string,
    title: string,
    options?: CreateMergeRequestOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ExpandedMergeRequestSchema, C, E, void>>;

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

  /**
   * Delete a merge request
   * @param projectId - Project ID or path
   * @param mergerequestIid - Merge request IID
   */
  remove<E extends boolean = false>(
    projectId: string | number,
    mergerequestIid: 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 open merge requests in a project
const mrs = await api.MergeRequests.all({
  projectId: 123,
  state: 'opened',
  orderBy: 'updated_at',
  sort: 'desc'
});

// Get specific merge request
const mr = await api.MergeRequests.show(123, 5);

// Create new merge request
const newMr = await api.MergeRequests.create(
  123,
  'feature-branch',
  'main',
  'Add user authentication',
  {
    description: 'Implements JWT-based authentication',
    assigneeIds: [456],
    reviewerIds: [789],
    labels: 'feature,backend',
    removeSourceBranch: true
  }
);

// Update merge request
await api.MergeRequests.edit(123, 5, {
  title: 'Updated title',
  targetBranch: 'develop',
  labels: 'feature,backend,ready-for-review'
});

// Delete merge request
await api.MergeRequests.remove(123, 5);

Merge Request Query Options

/**
 * Options for filtering and querying merge requests
 */
type AllMergeRequestsOptions = {
  /** Filter by approved status */
  approved?: string;
  /** Filter by approver user IDs */
  approverIds?: number[];
  /** Filter by users who approved */
  approvedByIds?: number[];
  /** Filter by assignee ID */
  assigneeId?: number | 'Any' | 'None';
  /** Filter by author ID */
  authorId?: number;
  /** Filter by author username */
  authorUsername?: string;
  /** Created after date (ISO 8601) */
  createdAfter?: string;
  /** Created before date (ISO 8601) */
  createdBefore?: string;
  /** Deployed after date */
  deployedAfter?: string;
  /** Deployed before date */
  deployedBefore?: string;
  /** Filter by environment */
  environment?: string;
  /** Filter by MR IIDs */
  iids?: number[];
  /** Filter by labels (comma-separated) */
  labels?: string;
  /** Filter by milestone */
  milestone?: string;
  /** Filter by reaction emoji */
  myReactionEmoji?: string;
  /** Negation filters */
  not?: {
    labels?: string | string[];
    milestone?: string;
    authorId?: number;
    authorUsername?: string;
    assigneeId?: number;
    assigneeUsername?: string;
    reviewerId?: number;
    reviewerUsername?: string;
    myReactionEmoji?: string;
  };
  /** Order results by */
  orderBy?: 'created_at' | 'updated_at';
  /** Filter by reviewer ID */
  reviewerId?: number | 'Any' | 'None';
  /** Filter by reviewer username */
  reviewerUsername?: string;
  /** Filter scope */
  scope?: 'created_by_me' | 'assigned_to_me' | 'all';
  /** Search term */
  search?: string;
  /** Sort direction */
  sort?: 'asc' | 'desc';
  /** Filter by source branch */
  sourceBranch?: string;
  /** Filter by state */
  state?: 'opened' | 'closed' | 'locked' | 'merged';
  /** Filter by target branch */
  targetBranch?: string;
  /** Updated after date */
  updatedAfter?: string;
  /** Updated before date */
  updatedBefore?: string;
  /** View mode */
  view?: string;
  /** Return expanded label details */
  withLabelsDetails?: boolean;
  /** Trigger merge status recheck */
  withMergeStatusRecheck?: boolean;
  /** Filter by WIP/Draft status */
  wip?: string;
};

Merging

Accept and merge merge requests with various options.

/**
 * Merge/accept a merge request
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @param options - Merge options
 * @returns Merged merge request
 */
merge<E extends boolean = false>(
  projectId: string | number,
  mergerequestIid: number,
  options?: AcceptMergeRequestOptions & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ExpandedMergeRequestSchema, C, E, void>>;

/**
 * Alias for merge()
 */
accept<E extends boolean = false>(
  projectId: string | number,
  mergerequestIid: number,
  options?: AcceptMergeRequestOptions & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ExpandedMergeRequestSchema, C, E, void>>;

/**
 * Cancel auto-merge when pipeline succeeds
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @returns Updated merge request
 */
cancelOnPipelineSuccess<E extends boolean = false>(
  projectId: string | number,
  mergerequestIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ExpandedMergeRequestSchema, C, E, void>>;

/**
 * Merge to default branch for testing
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @returns Commit ID of merge result
 */
mergeToDefault<E extends boolean = false>(
  projectId: string | number,
  mergerequestIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<{ commit_id: string }, C, E, void>>;

type AcceptMergeRequestOptions = {
  /** Custom merge commit message */
  mergeCommitMessage?: string;
  /** Custom squash commit message */
  squashCommitMessage?: string;
  /** Squash commits before merge */
  squash?: boolean;
  /** Remove source branch after merge */
  shouldRemoveSourceBranch?: boolean;
  /** SHA that must match for merge */
  sha?: string;
  /** Enable auto-merge when pipeline succeeds */
  autoMerge?: boolean;
  /** @deprecated Use autoMerge instead */
  mergeWhenPipelineSucceeds?: boolean;
};

Usage Examples:

// Merge immediately
const merged = await api.MergeRequests.merge(123, 5, {
  squash: true,
  shouldRemoveSourceBranch: true,
  mergeCommitMessage: 'Merge feature: User authentication'
});

// Auto-merge when pipeline succeeds
await api.MergeRequests.merge(123, 5, {
  autoMerge: true,
  squash: true
});

// Cancel auto-merge
await api.MergeRequests.cancelOnPipelineSuccess(123, 5);

// Test merge to default branch
const testMerge = await api.MergeRequests.mergeToDefault(123, 5);
console.log(testMerge.commit_id);

Code Changes and Diffs

View code changes, diffs, and commits in merge requests.

/**
 * Get all diffs for a merge request
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @param options - Pagination options
 * @returns Array of diff objects
 */
allDiffs<E extends boolean = false, P extends PaginationTypes = 'offset'>(
  projectId: string | number,
  mergerequestIid: number,
  options?: Sudo & ShowExpanded<E> & PaginationRequestOptions<P>
): Promise<GitlabAPIResponse<MergeRequestDiffSchema[], C, E, P>>;

/**
 * Get all commits in a merge request
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @param options - Pagination options
 * @returns Array of commits
 */
allCommits<E extends boolean = false, P extends PaginationTypes = 'offset'>(
  projectId: string | number,
  mergerequestIid: number,
  options?: Sudo & ShowExpanded<E> & PaginationRequestOptions<P>
): Promise<GitlabAPIResponse<CommitSchema[], C, E, P>>;

/**
 * Get changes (diffs) for a merge request
 * @deprecated Use allDiffs() instead - deprecated in GitLab 15.7
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @returns Changes with diffs
 */
showChanges<E extends boolean = false>(
  projectId: string | number,
  mergerequestIid: number,
  options?: { accessRawDiffs?: boolean } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<MergeRequestChangesSchema, C, E, void>>;

/**
 * List all diff versions
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @returns Array of diff versions
 */
allDiffVersions<E extends boolean = false>(
  projectId: string | number,
  mergerequestIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<MergeRequestDiffVersionsSchema[], C, E, void>>;

/**
 * Show a specific diff version
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @param versionId - Version ID
 * @returns Diff version with commits and diffs
 */
showDiffVersion<E extends boolean = false>(
  projectId: string | number,
  mergerequestIid: number,
  versionId: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ExpandedMergeRequestDiffVersionsSchema, C, E, void>>;

Usage Examples:

// Get all diffs
const diffs = await api.MergeRequests.allDiffs(123, 5);
diffs.forEach(diff => {
  console.log(`${diff.old_path} -> ${diff.new_path}`);
  console.log(diff.diff);
});

// Get all commits
const commits = await api.MergeRequests.allCommits(123, 5);

// List diff versions
const versions = await api.MergeRequests.allDiffVersions(123, 5);

// Show specific version
const version = await api.MergeRequests.showDiffVersion(123, 5, 2);

Rebase

Rebase merge request source branch.

/**
 * Rebase a merge request
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @param options - Rebase options
 * @returns Rebase status
 */
rebase<E extends boolean = false>(
  projectId: string | number,
  mergerequestIid: number,
  options?: { skipCI?: boolean } & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<MergeRequestRebaseSchema, C, E, void>>;

Usage Example:

// Rebase merge request
const rebaseResult = await api.MergeRequests.rebase(123, 5, {
  skipCI: false
});

if (rebaseResult.rebase_in_progress) {
  console.log('Rebase in progress...');
}

Pipelines

Manage CI/CD pipelines for merge requests.

/**
 * List all pipelines for a merge request
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @param options - Pagination options
 * @returns Array of pipelines
 */
allPipelines<E extends boolean = false, P extends PaginationTypes = 'offset'>(
  projectId: string | number,
  mergerequestIid: number,
  options?: PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<PipelineSchema[], C, E, P>>;

/**
 * Create a new pipeline for the merge request
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @returns Created pipeline
 */
createPipeline<E extends boolean = false>(
  projectId: string | number,
  mergerequestIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<ExpandedPipelineSchema, C, E, void>>;

Usage Examples:

// List pipelines for MR
const pipelines = await api.MergeRequests.allPipelines(123, 5);

// Create new pipeline
const pipeline = await api.MergeRequests.createPipeline(123, 5);

Participants and Reviewers

Manage participants, assignees, and reviewers.

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

/**
 * Show reviewers with their review status
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @returns Array of reviewers with status
 */
showReviewers<E extends boolean = false>(
  projectId: string | number,
  mergerequestIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<MergeRequestReviewerSchema[], C, E, void>>;

Usage Examples:

// List participants
const participants = await api.MergeRequests.allParticipants(123, 5);

// Get reviewers with status
const reviewers = await api.MergeRequests.showReviewers(123, 5);
reviewers.forEach(r => {
  console.log(`${r.user.name}: ${r.state}`);
  // Possible states: unreviewed, requested_changes, reviewed, approved, review_started
});

Related Issues

View issues related to or closed by a merge request.

/**
 * List issues that will be closed when MR is merged
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @returns Array of issues
 */
allIssuesClosed<E extends boolean = false>(
  projectId: string | number,
  mergerequestIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<IssueSchema[], C, E, void>>;

/**
 * List issues related to the merge request
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @returns Array of related issues
 */
allIssuesRelated<E extends boolean = false>(
  projectId: string | number,
  mergerequestIid: number,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<IssueSchema[], C, E, void>>;

Time Tracking

Track time estimates and spent time on merge requests.

/**
 * Add time spent on a merge request
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @param duration - Duration string (e.g., "1h 30m")
 * @returns Updated time stats
 */
addSpentTime<E extends boolean = false>(
  projectId: string | number,
  mergerequestIid: number,
  duration: string,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<TimeStatsSchema, C, E, void>>;

/**
 * Set time estimate for a merge request
 * @param projectId - Project ID
 * @param mergerequestIid - Merge request IID
 * @param duration - Duration string (e.g., "3h")
 * @returns Updated time stats
 */
setTimeEstimate<E extends boolean = false>(
  projectId: string | number,
  mergerequestIid: number,
  duration: string,
  options?: Sudo & ShowExpanded<E>
): Promise<GitlabAPIResponse<TimeStatsSchema, C, E, void>>;

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

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

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

Subscriptions and Todos

Subscribe to notifications and create todos.

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

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

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

Related Merge Request Resources

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

Approvals

MergeRequestApprovals - Manage approval rules and approval status

Comments and Discussions

MergeRequestNotes - Create and manage merge request comments
MergeRequestNoteAwardEmojis - React to MR comments with emojis
MergeRequestDiscussions - Manage threaded discussions
MergeRequestDraftNotes - Manage draft comments for batch publishing

Context and History

MergeRequestContextCommits - Add context commits for review
MergeRequestAwardEmojis - React to merge requests with emojis
MergeRequestLabelEvents - Track label change history
MergeRequestMilestoneEvents - Track milestone changes
MergeRequestStateEvents - Track state changes (legacy)

Advanced Features

MergeTrains - Manage merge trains (Premium/Ultimate)

See Additional Resources for detailed documentation of these resource classes.

Version

Tile

Files

merge-requests.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Merge Requests

Capabilities

Merge Request Operations

Merge Request Query Options

Merging

Code Changes and Diffs

Rebase

Pipelines

Participants and Reviewers

Related Issues

Time Tracking

Subscriptions and Todos

Related Merge Request Resources

Approvals

Comments and Discussions

Context and History

Advanced Features

merge-requests.mddocs/