@gohcltech/bitbucket-mcp
Version:
Bitbucket integration for Claude via Model Context Protocol
589 lines • 19.7 kB
TypeScript
/**
* @fileoverview TypeScript types for Bitbucket branch operations.
*
* This module contains TypeScript interfaces that correspond to branch-related
* entities returned by the Bitbucket API v2.0. Branches are fundamental to git
* version control and represent different lines of development within repositories.
*
* These types cover:
* - Basic branch information and commit metadata
* - Git Flow and branching model configurations
* - Branch protection rules and permissions
* - Automatic reviewer assignment configurations
*
* These types are used throughout the MCP server for:
* - Parsing Bitbucket branch API responses
* - Ensuring type safety in branch management operations
* - Supporting Git Flow workflows and branch protection
* - Managing code review automation
*/
/**
* Bitbucket branch entity representing a git branch within a repository.
*
* A branch represents a line of development in git, containing a sequence of
* commits that diverge from other branches. Each branch points to a specific
* commit and contains metadata about that commit including author, date, and
* message information.
*
* @example
* ```typescript
* const branch: Branch = {
* name: "feature/authentication",
* target: {
* hash: "a1b2c3d4e5f6789012345678901234567890abcd",
* date: "2025-09-23T14:22:33.456Z",
* author: {
* user: {
* display_name: "Kurt Wolf",
* uuid: "{user-uuid}"
* }
* },
* message: "Add OAuth 2.0 authentication support"
* },
* links: {
* commits: {
* href: "https://api.bitbucket.org/2.0/repositories/gohcl/bitbucket-mcp/commits/feature/authentication"
* },
* html: {
* href: "https://bitbucket.org/gohcl/bitbucket-mcp/branch/feature/authentication"
* }
* }
* };
* ```
*/
export interface Branch {
/**
* Branch name following git branch naming conventions.
*
* Contains the full branch name including any prefixes (e.g., "feature/auth",
* "bugfix/login-error", "main", "develop"). Must follow git's branch naming
* rules and cannot contain certain special characters.
*/
name: string;
/**
* Target commit information that this branch points to.
*
* Contains comprehensive metadata about the latest commit on this branch,
* including the commit hash, author information, timestamp, and message.
* This represents the HEAD of the branch.
*/
target: {
/**
* SHA-1 hash of the commit this branch points to.
*
* This is the full 40-character hexadecimal string that uniquely
* identifies the commit. Used for git operations and API calls.
*/
hash: string;
/**
* ISO 8601 timestamp when the commit was created.
*
* Represents the commit date (not the author date) and includes
* timezone information for precise temporal ordering.
*/
date: string;
/**
* Information about the commit author.
*
* May be undefined if the author is not a registered Bitbucket user
* or if the commit was made by an external system.
*/
author: {
/**
* Optional Bitbucket user information for the commit author.
*
* Only present if the commit author email matches a registered
* Bitbucket user account. Otherwise undefined.
*/
user?: {
/** Display name of the committer */
display_name: string;
/** Unique UUID for the user account */
uuid: string;
};
};
/**
* Commit message describing the changes.
*
* Contains the full commit message including title and optional
* body text. May include multiple lines and formatting.
*/
message: string;
};
/**
* Collection of related URLs for the branch.
*
* Provides direct access to branch-related pages and API endpoints
* for commits and web interface navigation.
*/
links: {
/**
* API endpoint for commits on this branch.
*
* Provides direct access to the commits API filtered for this
* specific branch, useful for retrieving commit history.
*/
commits: {
/** Full URL to the branch's commits API endpoint */
href: string;
};
/**
* Direct link to the branch's page in the Bitbucket web interface.
*
* Opens the branch view showing recent commits, files, and
* branch-specific actions like creating pull requests.
*/
html: {
/** Full URL to the branch page in Bitbucket */
href: string;
};
};
}
/**
* Bitbucket branching model configuration defining the repository's workflow strategy.
*
* The branching model determines how branches are organized and used within a
* repository. Bitbucket supports Git Flow, GitHub Flow, and custom branching
* strategies, each with different branch types and naming conventions.
*
* @example
* ```typescript
* const gitFlowModel: BranchingModel = {
* type: "git_flow",
* development: {
* name: "develop",
* use_mainbranch: false
* },
* production: {
* name: "master",
* use_mainbranch: true
* },
* branch_types: [
* {
* kind: "feature",
* prefix: "feature/",
* enabled: true
* },
* {
* kind: "bugfix",
* prefix: "bugfix/",
* enabled: true
* },
* {
* kind: "release",
* prefix: "release/",
* enabled: true
* },
* {
* kind: "hotfix",
* prefix: "hotfix/",
* enabled: true
* }
* ]
* };
* ```
*/
export interface BranchingModel {
/**
* Type of branching workflow strategy used by the repository.
*
* - 'git_flow': Traditional Git Flow with separate develop and master branches
* - 'github_flow': Simplified flow with feature branches merging to main
* - 'custom': User-defined branching strategy with custom configuration
*/
type?: 'git_flow' | 'github_flow' | 'custom';
/**
* Configuration for the primary development branch.
*
* In Git Flow, this is typically the "develop" branch where feature branches
* are merged. In GitHub Flow, this might be the same as the production branch.
*/
development?: {
/**
* Name of the development branch.
*
* Common names include "develop", "dev", or "main" depending on the
* workflow strategy being used.
*/
name: string;
/**
* Whether this branch is the same as the repository's main branch.
*
* When true, the development branch is the repository's default branch.
* When false, it's a separate branch for ongoing development work.
*/
use_mainbranch: boolean;
};
/**
* Configuration for the production/release branch.
*
* This is the stable branch containing production-ready code. Typically
* named "master", "main", or "production" depending on conventions.
*/
production?: {
/**
* Name of the production branch.
*
* Common names include "master", "main", or "production". This branch
* should always contain stable, deployable code.
*/
name: string;
/**
* Whether this branch is the same as the repository's main branch.
*
* Usually true for the production branch, making it the default
* branch that users see when visiting the repository.
*/
use_mainbranch: boolean;
};
/**
* Array of branch type configurations defining naming and behavior.
*
* Each entry defines a category of branches with specific naming prefixes
* and usage patterns. Common types include feature, bugfix, release, and hotfix.
*/
branch_types?: Array<{
/**
* Category of branch defining its purpose and workflow role.
*
* - 'feature': New feature development branches
* - 'bugfix': Bug fix branches for non-critical issues
* - 'release': Release preparation branches
* - 'hotfix': Critical fix branches for production issues
* - 'custom': User-defined branch types with custom workflows
*/
kind: 'feature' | 'bugfix' | 'release' | 'hotfix' | 'custom';
/**
* Naming prefix used for branches of this type.
*
* Examples: "feature/", "bugfix/", "release/", "hotfix/"
* Branches of this type should start with this prefix.
*/
prefix: string;
/**
* Whether branches of this type are currently enabled.
*
* When false, this branch type is disabled and should not be used
* for new branch creation, though existing branches remain functional.
*/
enabled: boolean;
}>;
/**
* Collection of related URLs for the branching model configuration.
*
* Provides API endpoints for managing and retrieving branching model settings.
*/
links?: {
/**
* Self-referential link to this branching model configuration.
*/
self: {
/** API endpoint URL for this branching model */
href: string;
};
};
}
/**
* Bitbucket branch permissions and restrictions configuration.
*
* This interface defines branch protection rules that control who can perform
* specific actions on branches matching certain patterns. These restrictions
* help enforce code review policies, prevent force pushes, and maintain
* code quality standards.
*
* @example
* ```typescript
* const permissions: BranchPermissions = {
* values: [
* {
* id: 12345,
* kind: "push",
* pattern: "master",
* users: [
* {
* display_name: "Kurt Wolf",
* uuid: "{user-uuid}"
* }
* ],
* groups: [],
* value: true
* },
* {
* id: 12346,
* kind: "enforce_merge_checks",
* pattern: "master",
* value: 2
* }
* ],
* page: 1,
* pagelen: 10,
* size: 2
* };
* ```
*/
export interface BranchPermissions {
/**
* Array of branch restriction rules.
*
* Each restriction defines a specific protection rule that applies to
* branches matching the specified pattern. Multiple restrictions can
* be applied to the same branch pattern.
*/
values: Array<{
/**
* Unique identifier for this restriction rule.
*
* Used for updating or deleting specific restrictions through the API.
*/
id: number;
/**
* Type of restriction being enforced.
*
* - 'push': Restricts who can push commits to matching branches
* - 'force': Prevents force pushes that rewrite history
* - 'delete': Prevents deletion of matching branches
* - 'restrict_merges': Controls merge permissions and requirements
* - 'enforce_merge_checks': Requires passing checks before merging
*/
kind: 'push' | 'force' | 'delete' | 'restrict_merges' | 'enforce_merge_checks';
/**
* Branch name pattern this restriction applies to.
*
* Can be an exact branch name (e.g., "master") or a pattern using
* wildcards (e.g., "release/*"). The pattern determines which
* branches are affected by this restriction.
*/
pattern: string;
/**
* Optional list of users who are exempt from this restriction.
*
* Users listed here can perform the restricted action even when
* the restriction is active. Useful for designating maintainers
* or administrators who need elevated permissions.
*/
users?: Array<{
/** Display name of the exempt user */
display_name: string;
/** Unique UUID identifier for the user */
uuid: string;
}>;
/**
* Optional list of groups whose members are exempt from this restriction.
*
* Similar to individual users, but applies to all members of the
* specified workspace groups. Provides role-based access control.
*/
groups?: Array<{
/** Human-readable group name */
name: string;
/** URL-safe group identifier */
slug: string;
}>;
/**
* Optional restriction configuration value.
*
* The meaning depends on the restriction kind:
* - For 'enforce_merge_checks': Number of required approvals
* - For boolean restrictions: true/false to enable/disable
* - For other types: Additional configuration parameters
*/
value?: string | number | boolean;
/**
* Optional links related to this restriction.
*
* Provides API endpoints for managing this specific restriction rule.
*/
links?: {
/**
* Self-referential link to this restriction rule.
*/
self: {
/** API endpoint URL for this restriction */
href: string;
};
};
}>;
/**
* Current page number in paginated results.
*
* Used when the response contains multiple pages of restrictions.
* Page numbering typically starts at 1.
*/
page?: number;
/**
* Number of items per page in paginated results.
*
* Indicates how many restriction rules are included in each page
* of the response. Default is usually 10 or 25.
*/
pagelen?: number;
/**
* Total number of restriction rules across all pages.
*
* Provides the complete count of restrictions, useful for
* calculating total pages and implementing pagination controls.
*/
size?: number;
/**
* URL for the next page of results.
*
* Only present when there are additional pages of restrictions
* available. Used for pagination through large result sets.
*/
next?: string;
}
/**
* Bitbucket default reviewers configuration for automatic review assignment.
*
* This interface defines rules for automatically assigning reviewers to pull
* requests based on branch patterns. It helps ensure that the right people
* review changes to specific branches or types of branches, improving code
* quality and knowledge sharing.
*
* @example
* ```typescript
* const reviewers: DefaultReviewers = {
* values: [
* {
* user: {
* display_name: "Kurt Wolf",
* uuid: "{user-uuid}",
* account_id: "557058:12345678-1234-1234-1234-123456789abc",
* links: {
* avatar: {
* href: "https://secure.gravatar.com/avatar/..."
* },
* html: {
* href: "https://bitbucket.org/kurtwolf"
* }
* }
* },
* pattern: "master",
* repository: {
* name: "bitbucket-mcp",
* full_name: "gohcl/bitbucket-mcp",
* uuid: "{repo-uuid}"
* }
* }
* ],
* page: 1,
* pagelen: 10,
* size: 1
* };
* ```
*/
export interface DefaultReviewers {
/**
* Array of automatic reviewer assignment rules.
*
* Each entry defines a user who should be automatically added as a
* reviewer for pull requests targeting branches matching the pattern.
*/
values: Array<{
/**
* User information for the automatic reviewer.
*
* Contains comprehensive details about the user including display name,
* identifiers, and links to their profile and avatar.
*/
user: {
/**
* Human-readable display name of the reviewer.
*
* This is the name shown in the Bitbucket interface and notifications.
*/
display_name: string;
/**
* Unique UUID identifier for the user.
*
* This is Bitbucket's internal identifier for the user account.
*/
uuid: string;
/**
* Atlassian account ID for the user.
*
* This is the cross-product identifier used across Atlassian services
* like Jira and Confluence. Format: "557058:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
*/
account_id: string;
/**
* Collection of links related to the user.
*
* Provides direct access to the user's profile and avatar image.
*/
links: {
/**
* Link to the user's avatar image.
*
* Typically points to a Gravatar or uploaded profile picture.
*/
avatar: {
/** URL to the avatar image file */
href: string;
};
/**
* Link to the user's profile page in Bitbucket.
*
* Opens the user's public profile showing their repositories,
* activity, and other public information.
*/
html: {
/** URL to the user's Bitbucket profile page */
href: string;
};
};
};
/**
* Optional branch name pattern this reviewer rule applies to.
*
* Can be an exact branch name (e.g., "master") or a pattern with
* wildcards (e.g., "feature/*"). If undefined, applies to all branches.
* When a pull request targets a branch matching this pattern, the user
* will be automatically added as a reviewer.
*/
pattern?: string;
/**
* Optional repository information if this rule is repository-specific.
*
* When present, this reviewer rule only applies to the specified
* repository. When undefined, the rule may apply more broadly.
*/
repository?: {
/** Repository name within the workspace */
name: string;
/** Full repository name including workspace prefix */
full_name: string;
/** Unique UUID identifier for the repository */
uuid: string;
};
}>;
/**
* Current page number in paginated results.
*
* Used when the response contains multiple pages of reviewer rules.
* Page numbering typically starts at 1.
*/
page?: number;
/**
* Number of items per page in paginated results.
*
* Indicates how many reviewer rules are included in each page
* of the response. Default is usually 10 or 25.
*/
pagelen?: number;
/**
* Total number of reviewer rules across all pages.
*
* Provides the complete count of automatic reviewer configurations,
* useful for calculating total pages and implementing pagination controls.
*/
size?: number;
/**
* URL for the next page of results.
*
* Only present when there are additional pages of reviewer rules
* available. Used for pagination through large result sets.
*/
next?: string;
}
//# sourceMappingURL=types.d.ts.map