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

repository-management.mddocs/

Repository Management

Repository operations including branches, tags, commits, files, protected branches, and repository configuration.

Capabilities

Branches

Manage repository branches including creation, deletion, and protection.

/**
 * Branches resource class for branch management
 */
class Branches<C extends boolean = false> {
  /**
   * List all branches in a repository
   * @param projectId - Project ID or path
   * @param options - Search and pagination options
   * @returns Array of branches
   */
  all<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    projectId: string | number,
    options?: { search?: string; regex?: string } & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<BranchSchema[], C, E, P>>;

  /**
   * Get details of a single branch
   * @param projectId - Project ID
   * @param branchName - Branch name
   * @returns Branch details
   */
  show<E extends boolean = false>(
    projectId: string | number,
    branchName: string,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<BranchSchema, C, E, void>>;

  /**
   * Create a new branch
   * @param projectId - Project ID
   * @param branchName - New branch name
   * @param ref - Source branch, tag, or commit SHA
   * @returns Created branch
   */
  create<E extends boolean = false>(
    projectId: string | number,
    branchName: string,
    ref: string,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<BranchSchema, C, E, void>>;

  /**
   * Delete a branch
   * @param projectId - Project ID
   * @param branchName - Branch name to delete
   */
  remove<E extends boolean = false>(
    projectId: string | number,
    branchName: string,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;

  /**
   * Delete all merged branches
   * @param projectId - Project ID
   */
  removeMerged<E extends boolean = false>(
    projectId: string | 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 branches
const branches = await api.Branches.all(123);

// Search branches
const featureBranches = await api.Branches.all(123, {
  search: 'feature/'
});

// Get branch details
const branch = await api.Branches.show(123, 'main');

// Create new branch
const newBranch = await api.Branches.create(123, 'feature/new-feature', 'main');

// Delete branch
await api.Branches.remove(123, 'feature/old-feature');

// Delete all merged branches
await api.Branches.removeMerged(123);

Protected Branches

Configure branch protection rules.

/**
 * ProtectedBranches resource class
 */
class ProtectedBranches<C extends boolean = false> {
  /**
   * List all protected branches
   */
  all<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    projectId: string | number,
    options?: { search?: string } & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ProtectedBranchSchema[], C, E, P>>;

  /**
   * Protect a branch
   */
  create<E extends boolean = false>(
    projectId: string | number,
    branchName: string,
    options?: ProtectBranchOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ProtectedBranchSchema, C, E, void>>;

  /**
   * Unprotect a branch
   */
  remove<E extends boolean = false>(
    projectId: string | number,
    branchName: string,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Usage Examples:

// Protect main branch
await api.ProtectedBranches.create(123, 'main', {
  pushAccessLevel: 40, // Maintainer
  mergeAccessLevel: 30, // Developer
  allowForcePush: false
});

// List protected branches
const protected = await api.ProtectedBranches.all(123);

// Unprotect branch
await api.ProtectedBranches.remove(123, 'develop');

Tags

Manage repository tags including creation and protection.

/**
 * Tags resource class for tag management
 */
class Tags<C extends boolean = false> {
  /**
   * List all tags
   */
  all<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    projectId: string | number,
    options?: { search?: string; orderBy?: 'name' | 'updated'; sort?: 'asc' | 'desc' }
      & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<TagSchema[], C, E, P>>;

  /**
   * Get a single tag
   */
  show<E extends boolean = false>(
    projectId: string | number,
    tagName: string,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ExpandedTagSchema, C, E, void>>;

  /**
   * Create a new tag
   */
  create<E extends boolean = false>(
    projectId: string | number,
    tagName: string,
    ref: string,
    options?: { message?: string } & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<TagSchema, C, E, void>>;

  /**
   * Delete a tag
   */
  remove<E extends boolean = false>(
    projectId: string | number,
    tagName: string,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Usage Examples:

// List all tags
const tags = await api.Tags.all(123, {
  orderBy: 'updated',
  sort: 'desc'
});

// Get tag details
const tag = await api.Tags.show(123, 'v1.0.0');

// Create annotated tag
await api.Tags.create(123, 'v1.2.0', 'main', {
  message: 'Release version 1.2.0'
});

// Delete tag
await api.Tags.remove(123, 'v0.9.0-beta');

Protected Tags

Configure tag protection rules.

/**
 * ProtectedTags resource class
 */
class ProtectedTags<C extends boolean = false> {
  /**
   * List all protected tags
   */
  all<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    projectId: string | number,
    options?: PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ProtectedTagSchema[], C, E, P>>;

  /**
   * Protect a tag pattern
   */
  create<E extends boolean = false>(
    projectId: string | number,
    tagPattern: string,
    options?: { createAccessLevel?: number } & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ProtectedTagSchema, C, E, void>>;

  /**
   * Unprotect a tag pattern
   */
  remove<E extends boolean = false>(
    projectId: string | number,
    tagPattern: string,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Commits

Access commit history and details.

/**
 * Commits resource class for commit operations
 */
class Commits<C extends boolean = false> {
  /**
   * List commits in a repository
   * @param projectId - Project ID
   * @param options - Filter and pagination options
   * @returns Array of commits
   */
  all<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    projectId: string | number,
    options?: AllCommitsOptions & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<CommitSchema[], C, E, P>>;

  /**
   * Get details of a single commit
   * @param projectId - Project ID
   * @param sha - Commit SHA
   * @param options - Additional options
   * @returns Commit details
   */
  show<E extends boolean = false>(
    projectId: string | number,
    sha: string,
    options?: ShowCommitOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<CommitSchema, C, E, void>>;

  /**
   * Create a new commit with multiple file operations
   * @param projectId - Project ID
   * @param branch - Target branch
   * @param commitMessage - Commit message
   * @param actions - Array of file actions
   * @param options - Additional commit options
   * @returns Created commit
   */
  create<E extends boolean = false>(
    projectId: string | number,
    branch: string,
    commitMessage: string,
    actions: CommitAction[],
    options?: CreateCommitOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<CommitSchema, C, E, void>>;
}

type CommitAction = {
  /** Action to perform */
  action: 'create' | 'delete' | 'move' | 'update' | 'chmod';
  /** File path */
  filePath: string;
  /** Previous path (for move action) */
  previousPath?: string;
  /** File content (for create/update) */
  content?: string;
  /** File encoding */
  encoding?: 'text' | 'base64';
  /** Execute permission (for chmod) */
  executeFilemode?: boolean;
};

Usage Examples:

// List recent commits
const commits = await api.Commits.all(123, {
  refName: 'main',
  since: '2024-01-01',
  perPage: 20
});

// Get commit details
const commit = await api.Commits.show(123, 'abc123def456');

// Create commit with multiple file operations
await api.Commits.create(
  123,
  'main',
  'Update configuration and add new feature',
  [
    {
      action: 'update',
      filePath: 'config/settings.json',
      content: JSON.stringify({ setting: 'value' })
    },
    {
      action: 'create',
      filePath: 'src/new-feature.ts',
      content: 'export function newFeature() { }'
    },
    {
      action: 'delete',
      filePath: 'src/old-file.ts'
    }
  ]
);

Repository Files

Manage individual files in the repository.

/**
 * RepositoryFiles resource class for file operations
 */
class RepositoryFiles<C extends boolean = false> {
  /**
   * Get file metadata
   * @param projectId - Project ID
   * @param filePath - Path to file
   * @param ref - Branch, tag, or commit SHA
   * @returns File information with base64 content
   */
  show<E extends boolean = false>(
    projectId: string | number,
    filePath: string,
    ref: string,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<RepositoryFileSchema, C, E, void>>;

  /**
   * Get raw file content
   * @param projectId - Project ID
   * @param filePath - Path to file
   * @param ref - Branch, tag, or commit SHA
   * @returns Raw file content as string
   */
  showRaw<E extends boolean = false>(
    projectId: string | number,
    filePath: string,
    ref: string,
    options?: Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<string, C, E, void>>;

  /**
   * Create a new file
   * @param projectId - Project ID
   * @param filePath - Path for new file
   * @param branch - Target branch
   * @param content - File content
   * @param commitMessage - Commit message
   * @param options - Additional options
   * @returns Created file info
   */
  create<E extends boolean = false>(
    projectId: string | number,
    filePath: string,
    branch: string,
    content: string,
    commitMessage: string,
    options?: CreateRepositoryFileOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<RepositoryFileSchema, C, E, void>>;

  /**
   * Update an existing file
   * @param projectId - Project ID
   * @param filePath - Path to file
   * @param branch - Target branch
   * @param content - Updated content
   * @param commitMessage - Commit message
   * @param options - Additional options
   * @returns Updated file info
   */
  edit<E extends boolean = false>(
    projectId: string | number,
    filePath: string,
    branch: string,
    content: string,
    commitMessage: string,
    options?: EditRepositoryFileOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<RepositoryFileSchema, C, E, void>>;

  /**
   * Delete a file
   * @param projectId - Project ID
   * @param filePath - Path to file
   * @param branch - Target branch
   * @param commitMessage - Commit message
   * @param options - Additional options
   */
  remove<E extends boolean = false>(
    projectId: string | number,
    filePath: string,
    branch: string,
    commitMessage: string,
    options?: RemoveRepositoryFileOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<void, C, E, void>>;
}

Usage Examples:

// Get file metadata
const fileInfo = await api.RepositoryFiles.show(
  123,
  'src/config.json',
  'main'
);

// Get raw file content
const content = await api.RepositoryFiles.showRaw(
  123,
  'README.md',
  'main'
);

// Create new file
await api.RepositoryFiles.create(
  123,
  'docs/new-guide.md',
  'main',
  '# New Guide\n\nContent here',
  'Add new guide documentation'
);

// Update file
await api.RepositoryFiles.edit(
  123,
  'src/config.json',
  'main',
  JSON.stringify({ updated: true }, null, 2),
  'Update configuration'
);

// Delete file
await api.RepositoryFiles.remove(
  123,
  'src/deprecated.ts',
  'main',
  'Remove deprecated file'
);

Repositories

Repository-level operations and settings.

/**
 * Repositories resource class
 */
class Repositories<C extends boolean = false> {
  /**
   * List repository tree (files and directories)
   */
  allTree<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    projectId: string | number,
    options?: {
      path?: string;
      ref?: string;
      recursive?: boolean;
    } & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<RepositoryTreeSchema[], C, E, P>>;

  /**
   * Compare branches, tags, or commits
   */
  compare<E extends boolean = false>(
    projectId: string | number,
    from: string,
    to: string,
    options?: { straight?: boolean } & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<RepositoryCompareSchema, C, E, void>>;

  /**
   * Get list of contributors
   */
  allContributors<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    projectId: string | number,
    options?: { orderBy?: 'name' | 'email' | 'commits'; sort?: 'asc' | 'desc' }
      & PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<ContributorSchema[], C, E, P>>;
}

Usage Examples:

// List repository tree
const tree = await api.Repositories.allTree(123, {
  path: 'src',
  ref: 'main',
  recursive: true
});

// Compare branches
const comparison = await api.Repositories.compare(123, 'main', 'develop');
console.log(`${comparison.commits.length} commits ahead`);

// Get contributors
const contributors = await api.Repositories.allContributors(123, {
  orderBy: 'commits',
  sort: 'desc'
});

Repository Submodules

Manage git submodules.

/**
 * RepositorySubmodules resource class
 */
class RepositorySubmodules<C extends boolean = false> {
  /**
   * Update a submodule URL
   */
  edit<E extends boolean = false>(
    projectId: string | number,
    submodule: string,
    branch: string,
    commitSha: string,
    options?: { commitMessage?: string } & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<CommitSchema, C, E, void>>;
}

Commit Discussions

Manage discussions on commits.

/**
 * CommitDiscussions resource class
 */
class CommitDiscussions<C extends boolean = false> {
  /**
   * List all discussions on a commit
   */
  all<E extends boolean = false, P extends PaginationTypes = 'offset'>(
    projectId: string | number,
    commitSha: string,
    options?: PaginationRequestOptions<P> & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<DiscussionSchema[], C, E, P>>;

  /**
   * Create a new discussion on a commit
   */
  create<E extends boolean = false>(
    projectId: string | number,
    commitSha: string,
    body: string,
    options?: CreateDiscussionOptions & Sudo & ShowExpanded<E>
  ): Promise<GitlabAPIResponse<DiscussionSchema, C, E, void>>;
}

Related Repository Resources

Additional resources for repository management:

  • ProjectRemoteMirrors - Configure repository mirroring
  • ProjectRepositoryStorageMoves - Manage repository storage migration

See Additional Resources for detailed documentation of these resource classes.