backend

package
v1.71.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 15, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Index

Constants

View Source 
const AssigneeNone = "__none__"

AssigneeNone is a sentinel value for UpdateIssueInput.Assignee that signals "unassign" (set assignee to null on the wire).

Variables

View Source 
var (
	ErrNotFound          = errors.New("not found")
	ErrAuth              = errors.New("authentication required")
	ErrPermission        = errors.New("permission denied")
	ErrUnsupportedOnHost = errors.New("operation unsupported on this host")
	ErrConflict          = errors.New("conflict")
	ErrTransport         = errors.New("transport error")
)

Sentinel errors describing the bounded set of domain-level failure modes. Adapters classify wire errors into one of these so commands and the MCP surface can branch deterministically via errors.Is.

View Source 
var AllCodes = []ErrorCode{
	CodeAuthNoToken,
	CodeAuthInvalidToken,
	CodePermWriteRequired,
	CodeRepoNotFound,
	CodePRNotFound,
	CodePRMergeConflict,
	CodePRMergeBehind,
	CodePRCreateDuplicateBranch,
	CodePRReviewerUnknown,
	CodePRAutoMergeBetaDisabled,
	CodeBranchProtected,
	CodeHostUnsupported,
	CodeNetworkTLSUnknownAuthority,
	CodeTransportTimeout,
}

AllCodes lists every published ErrorCode. The errfmt test suite iterates this slice and asserts each code has a catalogue entry, so adding a new constant above without a matching errfmt entry fails the build.

When adding a new code:

  1. Append it to the const block above.
  2. Append it here.
  3. Add the matching catalogue entry in pkg/errfmt/errfmt.go.

Functions

func DefaultBranch added in v1.8.0 

func DefaultBranch(bl BranchLister, ns, slug string) (string, error)

DefaultBranch resolves a repository's default branch by inspecting the IsDefault flag on its branch list. It returns "" with no error when no branch in the list is marked default (e.g. on Bitbucket Cloud, whose branch endpoint omits IsDefault), so callers can fall back to local git state or another heuristic.

Errors from the underlying ListBranches call are propagated unchanged so no command silently masks them with a literal "main".

func NormaliseEmoji added in v1.40.0 

func NormaliseEmoji(emoji string) string

NormaliseEmoji converts any accepted emoji form (colon-wrapped Server values, shortcodes with colons, or canonical underscore form) to the canonical underscore form. Returns the input unchanged when the emoji is not in the known set.

func StampCode added in v1.19.0 

func StampCode(err error, code ErrorCode, resource, id, feature string) error

StampCode is an adapter convenience: when err is a *DomainError, sets the fields on a copy and returns the copy as an error; otherwise returns err unchanged. This lets call sites annotate post-classification errors with operation-specific codes (e.g. pr.merge.conflict vs the bare ErrConflict kind) without per-call boilerplate.

Empty arguments are skipped so a caller can stamp only Code while leaving Resource/ID/Feature alone, or fill in just Resource+ID for a not-found path.

The returned error preserves Kind, Host, Cause, and Message — only the specified fields are overwritten.

func ToCloudMergeStrategy added in v1.30.0 

func ToCloudMergeStrategy(s string) string

ToCloudMergeStrategy translates CLI strategy names to Bitbucket Cloud API values used on the auto-merge endpoint.

func ToServerMergeStrategy added in v1.30.0 

func ToServerMergeStrategy(s string) string

ToServerMergeStrategy translates CLI strategy names to Bitbucket Server / Data Center API values used on the auto-merge endpoint.

Types

type AddCommitCommentInput added in v1.27.0 

type AddCommitCommentInput struct {
	Body string
}

AddCommitCommentInput carries parameters for creating a commit comment.

type AddPRCommentInput added in v1.6.0 

type AddPRCommentInput struct {
	Text     string
	Inline   *PRCommentInline
	Parent   *int
	Severity string // "BLOCKER" to create a task; "" for normal comment (Server only)
}

AddPRCommentInput carries the parameters for adding a comment to a PR. Inline is non-nil for inline (file:line) review comments and nil for general PR comments. Parent is non-nil to post a reply nested under an existing comment thread.

Severity controls the comment type on Bitbucket Server / Data Center: set to "BLOCKER" to create a task comment. Cloud ignores this field and always creates a regular comment.

type AdminClient added in v1.38.0 

type AdminClient interface {
	RotateSecrets() error
	GetLoggingConfig() (LoggingConfig, error)
	SetLoggingConfig(in LoggingConfigInput) error
}

AdminClient exposes Bitbucket Server / Data Center administration operations. Bitbucket Cloud does not expose these endpoints — calls against Cloud return ErrUnsupportedOnHost via AsAdminClient.

func AsAdminClient added in v1.38.0 

func AsAdminClient(c Client, host string) (AdminClient, error)

AsAdminClient returns the AdminClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) when called against a backend that doesn't implement admin operations (currently Bitbucket Cloud).

type AutoMergeState added in v1.30.0 

type AutoMergeState struct {
	Enabled  bool
	Strategy string // "merge" | "squash" | "rebase"
}

AutoMergeState records the auto-merge configuration for a pull request. Strategy is one of "merge", "squash", or "rebase" (the CLI vocabulary).

type Branch 

type Branch struct {
	Name       string
	IsDefault  bool
	LatestHash string
}

Branch is the domain representation of a repository branch.

type BranchCreator 

type BranchCreator interface {
	CreateBranch(ns, slug string, in CreateBranchInput) (Branch, error)
}

BranchCreator creates a branch.

type BranchDeleter 

type BranchDeleter interface {
	DeleteBranch(ns, slug, branch string) error
}

BranchDeleter deletes a branch.

type BranchLister 

type BranchLister interface {
	ListBranches(ns, slug string, limit int) ([]Branch, error)
}

BranchLister lists branches in a repository.

type BranchProtection added in v1.17.0 

type BranchProtection struct {
	ID          int
	Type        string
	MatcherID   string
	MatcherKind string
	Users       []string
	Groups      []string
}

BranchProtection is a single branch-restriction record on Bitbucket Server / Data Center. Cloud has a similar concept under a different, non-trivial wire shape that we don't model yet — BranchProtection is surfaced only via the BranchProtector optional interface.

Type values match BBS exactly (lowercased, dash-separated): 

read-only           — disallow all writes
no-deletes          — disallow branch deletion
fast-forward-only   — disallow non-fast-forward writes
pull-request-only   — only PR merges may write

MatcherKind is the BBS matcher type id ("BRANCH", "PATTERN", "MODEL_BRANCH", "MODEL_CATEGORY") and MatcherID is the corresponding value (a branch name, glob, or model id). Users / Groups list slugs that are exempted from the restriction.

type BranchProtector added in v1.17.0 

type BranchProtector interface {
	ListBranchProtections(ns, slug string, limit int) ([]BranchProtection, error)
	CreateBranchProtection(ns, slug string, in CreateBranchProtectionInput) (BranchProtection, error)
	DeleteBranchProtection(ns, slug string, id int) error
}

BranchProtector exposes branch-restriction management on Bitbucket Server / Data Center. The Cloud backend has a different "branch restrictions" shape that's not modelled here — calls against a Cloud client surface ErrUnsupportedOnHost via AsBranchProtector.

func AsBranchProtector added in v1.17.0 

func AsBranchProtector(c Client, host string) (BranchProtector, error)

AsBranchProtector returns the BranchProtector view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) when called against a backend that doesn't model branch protections (currently Cloud).

type BranchRule added in v1.53.0 

type BranchRule struct {
	ID      int    `json:"id"`
	Kind    string `json:"kind"`
	Pattern string `json:"pattern"`
	Value   int    `json:"value,omitempty"`
}

BranchRule is the domain representation of a Bitbucket Cloud branch restriction rule.

type BranchRuleClient added in v1.53.0 

type BranchRuleClient interface {
	ListBranchRules(ns, slug string) ([]BranchRule, error)
	AddBranchRule(ns, slug string, input BranchRuleInput) (BranchRule, error)
	DeleteBranchRule(ns, slug string, id int) error
}

BranchRuleClient is implemented only by Bitbucket Cloud clients. Bitbucket Server / Data Center has no equivalent branch restriction API, so the entire surface is gated behind AsBranchRuleClient.

func AsBranchRuleClient added in v1.53.0 

func AsBranchRuleClient(c Client, host string) (BranchRuleClient, error)

AsBranchRuleClient returns the BranchRuleClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) when called against a Server/DC backend.

type BranchRuleInput added in v1.53.0 

type BranchRuleInput struct {
	Kind    string
	Pattern string
	Value   int
}

BranchRuleInput carries the parameters for adding a branch restriction rule.

type Client 

type Client interface {
	RepoLister
	RepoReader
	RepoWriter
	RepoDeleter
	RepoRenamer
	RepoVisibilitySetter
	SourceReader
	PRLister
	PRReader
	PRCreator
	PRMerger
	PRApprover
	PRDiffer
	BranchLister
	BranchCreator
	BranchDeleter
	TagLister
	TagCreator
	TagDeleter
	PREditor
	PRDecliner
	PRUnapprover
	PRReadier
	PRReviewRequester
	PRReviewer
	UserGetter
	CommitLister
	CommitReader
	PRCommentLister
	PRCommentAdder
	PRCommentEditor
	PRCommentDeleter
	PRActivityReader
	CommitCommenter
	CommitStatusLister
	CommitStatusReporter
	WebhookLister
	WebhookReader
	WebhookCreator
	WebhookDeleter
}

Client is the composite capability interface that every backend adapter must satisfy. Capability interfaces that only some backends implement (e.g. PipelineClient, IssueClient, BranchProtector) are NOT embedded here; they are accessed via their respective AsXxx helper which returns a typed ErrUnsupportedOnHost when the backend doesn't implement the capability.

Per-feature interface declarations live in client_<feature>.go files in this package so that new features can add interfaces without touching this file. The composite Client embedding block is the single intended conflict point for parallel development — per-feature optional interfaces never touch it.

type CodeInsightsAnnotation added in v1.23.0 

type CodeInsightsAnnotation struct {
	ExternalID string `json:"external_id,omitempty"`
	Path       string `json:"path"`
	Line       int    `json:"line,omitempty"`
	Message    string `json:"message"`
	Severity   string `json:"severity,omitempty"`
	Type       string `json:"type,omitempty"`
	Link       string `json:"link,omitempty"`
}

CodeInsightsAnnotation is a single file/line annotation posted under a Code Insights report. This type serves as both the API response shape and the input payload (CodeInsightsAnnotationInput is an alias).

Severity values: "LOW", "MEDIUM", "HIGH", "CRITICAL". Type values: "VULNERABILITY", "CODE_SMELL", "BUG".

type CodeInsightsAnnotationInput added in v1.23.0 

type CodeInsightsAnnotationInput = CodeInsightsAnnotation

CodeInsightsAnnotationInput is an alias of CodeInsightsAnnotation used on the write side of the interface to keep the signature intent clear.

type CodeInsightsClient added in v1.23.0 

type CodeInsightsClient interface {
	// Report operations
	ListReports(project, slug, hash string) ([]CodeInsightsReport, error)
	GetReport(project, slug, hash, key string) (CodeInsightsReport, error)
	// SetReport upserts (PUT) a report by key.
	SetReport(project, slug, hash, key string, in CodeInsightsReportInput) (CodeInsightsReport, error)
	DeleteReport(project, slug, hash, key string) error

	// Annotation operations
	ListAnnotations(project, slug, hash, key string) ([]CodeInsightsAnnotation, error)
	// AddAnnotations bulk-POSTs all annotations in a single request.
	AddAnnotations(project, slug, hash, key string, in []CodeInsightsAnnotationInput) error
	DeleteAnnotations(project, slug, hash, key string) error

	// Merge-check operations (experimental — partly undocumented API)
	SetMergeCheck(project, slug, key string, in MergeCheckInput) error
	GetMergeCheck(project, slug, key string) (MergeCheck, error)
	DeleteMergeCheck(project, slug, key string) error
}

CodeInsightsClient exposes Bitbucket Server / Data Center Code Insights management. Cloud has no native equivalent — AsCodeInsightsClient returns ErrUnsupportedOnHost when called against a Cloud backend.

The merge-check sub-API (SetMergeCheck / GetMergeCheck / DeleteMergeCheck) uses a partly undocumented endpoint at /rest/insights/latest/.../merge-check/ and is marked experimental in CLI help text.

func AsCodeInsightsClient added in v1.23.0 

func AsCodeInsightsClient(c Client, host string) (CodeInsightsClient, error)

AsCodeInsightsClient returns the CodeInsightsClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) when called against a backend that doesn't implement Code Insights (currently Bitbucket Cloud).

type CodeInsightsReport added in v1.23.0 

type CodeInsightsReport struct {
	Key        string                    `json:"key"`
	Title      string                    `json:"title"`
	Result     string                    `json:"result"`
	ReportType string                    `json:"report_type,omitempty"`
	Details    string                    `json:"details,omitempty"`
	Reporter   string                    `json:"reporter,omitempty"`
	Link       string                    `json:"link,omitempty"`
	LogoURL    string                    `json:"logo_url,omitempty"`
	Data       []CodeInsightsReportDatum `json:"data,omitempty"`
	CreatedAt  string                    `json:"created_at,omitempty"`
	UpdatedAt  string                    `json:"updated_at,omitempty"`
}

CodeInsightsReport is a Bitbucket Server / Data Center Code Insights report attached to a specific commit. Reports aggregate quality/security/build annotations and roll up to a single PASS/FAIL/PENDING result. This type is used for both API responses and the input shape (CodeInsightsReportInput).

Result values: "PASS", "FAIL", "PENDING" (empty = PENDING). ReportType values: "TESTING", "COVERAGE", "BUG", "SECURITY", "DUPLICATION", "DEPENDENCY" (empty uses TESTING as default on Server).

type CodeInsightsReportDatum added in v1.23.0 

type CodeInsightsReportDatum struct {
	Title string `json:"title"`
	Type  string `json:"type"`
	Value any    `json:"value"`
}

CodeInsightsReportDatum is a single key/value data point attached to a Code Insights report. Type values: "BOOLEAN", "DATE", "DURATION", "LINK", "NUMBER", "PERCENTAGE", "TEXT".

type CodeInsightsReportInput added in v1.23.0 

type CodeInsightsReportInput struct {
	Title      string
	Result     string // "PASS", "FAIL", "PENDING"
	ReportType string
	Details    string
	Reporter   string
	Link       string
	LogoURL    string
	Data       []CodeInsightsReportDatum
}

CodeInsightsReportInput is the upsert payload for SetReport. All fields map 1:1 to CodeInsightsReport; the separation exists only so the input shape stays explicit in the interface signature.

type CodeSearchHit added in v1.21.0 

type CodeSearchHit struct {
	Repository        string
	Path              string
	PathMatches       []SearchSegment
	ContentMatches    []ContentMatch
	ContentMatchCount int
	FileURL           string
}

CodeSearchHit is one result row from Bitbucket Cloud's workspace-scoped code search. The hit may match on the file path (PathMatches non-empty), on file content (ContentMatches non-empty), or both. Renderers use the SearchSegment.Match flag to bold the matched runs.

Repository is "workspace/slug" — the Cloud "full_name" form, kept verbatim so JSON consumers can split it themselves and the table renderer needs no extra column.

type CodeSearcher added in v1.21.0 

type CodeSearcher interface {
	SearchCode(workspace, query string, limit int) ([]CodeSearchHit, error)
}

CodeSearcher performs workspace-scoped code search on Bitbucket Cloud. Bitbucket Server / Data Center does not expose a first-class REST code- search endpoint (search there is provided by the separate Sourcegraph integration or third-party plugins), so the entire surface is gated behind AsCodeSearcher. Server adapters intentionally do NOT implement this interface — the type-assertion in AsCodeSearcher is what surfaces the typed host.unsupported error to callers.

func AsCodeSearcher added in v1.21.0 

func AsCodeSearcher(c Client, host string) (CodeSearcher, error)

AsCodeSearcher returns the CodeSearcher view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) when called against a backend that doesn't model code search (currently Server/DC).

type CommentReaction added in v1.40.0 

type CommentReaction struct {
	Emoji string // canonical shortcode: thumbs_up | thumbs_down | heart | laugh | hooray | confused
	Users []User // all users who reacted with this emoji
}

CommentReaction is the domain representation of an emoji reaction on a pull-request comment. Emoji is the canonical shortcode (underscore form): "thumbs_up", "thumbs_down", "heart", "laugh", "hooray", "confused". Users lists every user who reacted with that emoji.

type CommentReactor added in v1.40.0 

type CommentReactor interface {
	ListCommentReactions(ns, slug string, prID, commentID int) ([]CommentReaction, error)
	AddCommentReaction(ns, slug string, prID, commentID int, emoji string) error
	RemoveCommentReaction(ns, slug string, prID, commentID int, emoji string) error
}

CommentReactor manages emoji reactions on pull-request comments. Implemented only by Bitbucket Server / Data Center. Bitbucket Cloud has no equivalent API. Callers route through AsCommentReactor to surface the constraint as a typed ErrUnsupportedOnHost.

func AsCommentReactor added in v1.40.0 

func AsCommentReactor(c Client, host string) (CommentReactor, error)

AsCommentReactor returns the CommentReactor view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) when the backend at host has no reaction primitive (currently Bitbucket Cloud).

type Commit 

type Commit struct {
	Hash      string
	Message   string // subject line only (first line of commit message)
	Author    User
	Timestamp time.Time
	WebURL    string
}

Commit is the domain representation of a single repository commit.

type CommitComment added in v1.27.0 

type CommitComment struct {
	ID        int
	Author    User
	Body      string
	CreatedAt time.Time
	UpdatedAt time.Time
	Reactions []CommentReaction // only populated when explicitly requested; Server/DC only
}

CommitComment is a comment attached to a specific commit. Reactions is only populated when explicitly requested (e.g. --reactions flag or include_reactions MCP parameter). Server/DC only.

type CommitCommentReactor added in v1.41.0 

type CommitCommentReactor interface {
	ListCommitCommentReactions(ns, slug, hash string, commentID int) ([]CommentReaction, error)
	AddCommitCommentReaction(ns, slug, hash string, commentID int, emoji string) error
	RemoveCommitCommentReaction(ns, slug, hash string, commentID int, emoji string) error
}

CommitCommentReactor manages emoji reactions on commit comments. Implemented only by Bitbucket Server / Data Center. Bitbucket Cloud has no equivalent API. Callers route through AsCommitCommentReactor to surface the constraint as a typed ErrUnsupportedOnHost.

func AsCommitCommentReactor added in v1.41.0 

func AsCommitCommentReactor(c Client, host string) (CommitCommentReactor, error)

AsCommitCommentReactor returns the CommitCommentReactor view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) when the backend at host has no reaction primitive (currently Bitbucket Cloud).

type CommitCommenter added in v1.27.0 

type CommitCommenter interface {
	ListCommitComments(ns, slug, hash string, limit int) ([]CommitComment, error)
	AddCommitComment(ns, slug, hash string, in AddCommitCommentInput) (CommitComment, error)
	EditCommitComment(ns, slug, hash string, commentID int, body string) (CommitComment, error)
	DeleteCommitComment(ns, slug, hash string, commentID int) error
}

CommitCommenter manages comments on individual commits.

type CommitFileClient added in v1.55.0 

type CommitFileClient interface {
	ListCommitFiles(ns, slug, hash string) ([]DiffStatEntry, error)
}

CommitFileClient is implemented by both Cloud and Server backends.

func AsCommitFileClient added in v1.55.0 

func AsCommitFileClient(c Client, host string) (CommitFileClient, error)

AsCommitFileClient returns the CommitFileClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not implement the CommitFiles capability.

type CommitLister 

type CommitLister interface {
	ListCommits(ns, slug, branch string, limit int) ([]Commit, error)
}

CommitLister lists commits in a repository.

type CommitReader 

type CommitReader interface {
	GetCommit(ns, slug, hash string) (Commit, error)
}

CommitReader reads a single commit by hash.

type CommitStatus added in v1.6.0 

type CommitStatus struct {
	Key         string
	State       string // SUCCESSFUL | FAILED | INPROGRESS | STOPPED
	Name        string
	Description string
	URL         string
}

CommitStatus is a build / CI status reported against a commit hash.

type CommitStatusInput added in v1.59.0 

type CommitStatusInput struct {
	Key         string
	State       string // SUCCESSFUL | FAILED | INPROGRESS | STOPPED
	Name        string
	URL         string
	Description string
}

CommitStatusInput carries the parameters for reporting a build status.

type CommitStatusLister added in v1.6.0 

type CommitStatusLister interface {
	ListCommitStatuses(ns, slug, hash string) ([]CommitStatus, error)
}

CommitStatusLister lists build/CI statuses reported against a commit hash.

type CommitStatusReporter added in v1.59.0 

type CommitStatusReporter interface {
	ReportCommitStatus(ns, slug, hash string, input CommitStatusInput) (CommitStatus, error)
}

CommitStatusReporter posts a build status against a commit hash.

type ContentMatch added in v1.21.0 

type ContentMatch struct {
	Line     int
	Segments []SearchSegment
}

ContentMatch is a single matched line within a file: the 1-based line number plus a sequence of segments. Cloud groups consecutive matched lines into "content_matches" objects each with a "lines" array; bitbottle flattens those to a single ContentMatch slice in arrival order.

type Context added in v1.21.0 

type Context struct {
	Host          string      `json:"host"`
	Project       string      `json:"project"`
	Slug          string      `json:"slug"`
	Branch        string      `json:"branch"`
	DefaultBranch string      `json:"default_branch"`
	Ahead         *int        `json:"ahead,omitempty"`
	Behind        *int        `json:"behind,omitempty"`
	User          ContextUser `json:"user"`
	Backend       string      `json:"backend"`
}

Context is the one-call orientation primitive returned by `bitbottle context` and the MCP `get_context` tool. It collapses three previously independent calls (auth status / repo view / git status) into a single structured response so AI agents can orient themselves in one round-trip.

Zero-valued Project / Slug / Branch / DefaultBranch indicate "outside a git repo" — the rest of the shape (Host, User, Backend) still resolves through config + the backend's current-user endpoint.

Ahead and Behind are *int with omitempty so that "unknown" (git failed, no upstream, base ref missing, outside a repo) is encoded as the keys being absent from JSON — never as 0/0, which would lie to agents that would otherwise conclude "in sync". Both pointers are populated as a pair: either both non-nil, or both nil.

Backend is the literal "cloud" or "server" string matching the bbinstance backend-type vocabulary, so consumers can branch on host shape without re-deriving it.

User is a Context-local shape with JSON tags so the public contract emits {"slug": ..., "display_name": ...} without bleeding tags onto backend.User (which is reused across many wire surfaces and would regress existing JSON outputs if tagged here).

type ContextUser added in v1.21.0 

type ContextUser struct {
	Slug        string `json:"slug"`
	DisplayName string `json:"display_name"`
}

ContextUser is the user shape carried inside Context. It mirrors User but stamps explicit JSON tags so the documented contract is stable (`{"slug": ..., "display_name": ...}`) regardless of how backend.User is later reshaped.

type CreateBranchInput 

type CreateBranchInput struct {
	Name    string
	StartAt string // branch name or commit hash
}

CreateBranchInput carries the parameters for creating a branch.

type CreateBranchProtectionInput added in v1.17.0 

type CreateBranchProtectionInput struct {
	Type        string
	MatcherID   string
	MatcherKind string
	Users       []string
	Groups      []string
}

CreateBranchProtectionInput carries the parameters for adding a branch-restriction. All fields except Type and MatcherID are optional. MatcherKind defaults to "BRANCH" when empty (the most common case).

type CreateEnvironmentInput added in v1.29.0 

type CreateEnvironmentInput struct {
	Name string
	Type string
	Rank int
}

CreateEnvironmentInput carries the parameters for creating a deployment environment.

type CreateIssueInput added in v1.17.0 

type CreateIssueInput struct {
	Title    string
	Content  string
	Kind     string
	Priority string
}

CreateIssueInput carries the parameters for opening a new issue. Bitbucket Cloud applies sane defaults (kind=bug, priority=major) when fields are empty, so callers can omit everything but Title.

type CreatePRInput 

type CreatePRInput struct {
	Title       string
	Description string
	Draft       bool
	FromBranch  string
	ToBranch    string
	Reviewers   []string
}

CreatePRInput carries the parameters for creating a pull request.

Reviewers are user slugs (Server) or usernames / account IDs (Cloud). Both adapters serialise the same logical list into their backend's wire shape. A nil or empty slice creates a PR with no reviewers — Bitbucket does NOT auto-apply repo "default reviewers" on the create endpoint, so callers that want that behaviour must fetch them via DefaultReviewersResolver and merge the result here.

type CreateRepoInput 

type CreateRepoInput struct {
	Name        string
	SCM         string
	Public      bool
	Description string
}

CreateRepoInput carries the parameters for creating a repository.

type CreateReviewerGroupInput added in v1.69.0 

type CreateReviewerGroupInput struct {
	Name              string   // used as sourceMatcher displayId / id
	UserSlugs         []string // reviewer user slugs
	RequiredApprovals int      // default 1
}

CreateReviewerGroupInput carries the parameters for creating a reviewer group condition.

type CreateTagInput 

type CreateTagInput struct {
	Name    string
	StartAt string // branch name or commit hash
	Message string // empty = lightweight tag; non-empty = annotated tag
}

CreateTagInput carries the parameters for creating a tag.

type CreateWebhookInput added in v1.15.0 

type CreateWebhookInput struct {
	URL    string
	Events []string
	Active bool
	Secret string
}

CreateWebhookInput carries the parameters for creating a webhook. Secret is write-only — neither backend returns it on read.

type DefaultReviewer added in v1.50.0 

type DefaultReviewer struct {
	UserSlug     string `json:"userSlug"`
	DisplayName  string `json:"displayName"`
	EmailAddress string `json:"emailAddress,omitempty"`
}

DefaultReviewer is the domain representation of a repository default reviewer.

type DefaultReviewerClient added in v1.50.0 

type DefaultReviewerClient interface {
	ListDefaultReviewers(ns, slug string) ([]DefaultReviewer, error)
	AddDefaultReviewer(ns, slug, userSlug string) error
	RemoveDefaultReviewer(ns, slug, userSlug string) error
}

DefaultReviewerClient is implemented by both Cloud and Server backends.

func AsDefaultReviewerClient added in v1.50.0 

func AsDefaultReviewerClient(c Client, host string) (DefaultReviewerClient, error)

AsDefaultReviewerClient returns the DefaultReviewerClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not implement the DefaultReviewerClient capability.

type DefaultReviewersResolver added in v1.17.0 

type DefaultReviewersResolver interface {
	DefaultReviewers(ns, slug, fromBranch, toBranch string) ([]User, error)
}

DefaultReviewersResolver looks up the configured "default reviewers" for a repository given a source/target ref pair. Only Bitbucket Server / Data Center exposes this — Cloud has a similar feature with a different, non-trivial wire shape that we don't model yet.

Implementations may need additional context (e.g. numeric repo ID) which they obtain themselves; callers pass only the values they natively know.

func AsDefaultReviewersResolver added in v1.17.0 

func AsDefaultReviewersResolver(c Client, host string) (DefaultReviewersResolver, error)

AsDefaultReviewersResolver returns the DefaultReviewersResolver view of c, or a typed *DomainError when the backend doesn't implement it (currently Cloud). Callers use the returned error to decide whether to skip the auto-apply step entirely.

type DeployKey added in v1.47.0 

type DeployKey struct {
	ID       int    `json:"id"`
	Label    string `json:"label"`
	Key      string `json:"key"`
	ReadOnly bool   `json:"readOnly,omitempty"`
}

DeployKey is the domain representation of a repository deploy key (SSH public key).

type DeployKeyClient added in v1.47.0 

type DeployKeyClient interface {
	ListDeployKeys(ns, slug string) ([]DeployKey, error)
	AddDeployKey(ns, slug string, input DeployKeyInput) (DeployKey, error)
	DeleteDeployKey(ns, slug string, id int) error
}

DeployKeyClient is implemented by both Cloud and Server backends.

func AsDeployKeyClient added in v1.47.0 

func AsDeployKeyClient(c Client, host string) (DeployKeyClient, error)

AsDeployKeyClient returns the DeployKeyClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not implement the DeployKeys capability.

type DeployKeyInput added in v1.47.0 

type DeployKeyInput struct {
	Label string
	Key   string
}

DeployKeyInput carries the parameters for adding a deploy key.

type Deployment added in v1.29.0 

type Deployment struct {
	UUID        string
	State       string
	Environment Environment
	Release     struct {
		Name       string
		URL        string
		CommitHash string
	}
}

Deployment is the domain representation of a Bitbucket Cloud deployment. State values: PENDING, IN_PROGRESS, COMPLETED, STOPPED, FAILED.

type DeploymentClient added in v1.29.0 

type DeploymentClient interface {
	ListDeployments(ns, slug string, limit int) ([]Deployment, error)
	GetDeployment(ns, slug, uuid string) (Deployment, error)

	ListEnvironments(ns, slug string) ([]Environment, error)
	CreateEnvironment(ns, slug string, in CreateEnvironmentInput) (Environment, error)
	DeleteEnvironment(ns, slug, uuid string) error

	ListEnvVariables(ns, slug, envUUID string) ([]EnvVariable, error)
	SetEnvVariable(ns, slug, envUUID string, in EnvVariableInput) (EnvVariable, error)
	DeleteEnvVariable(ns, slug, envUUID, varUUID string) error
}

DeploymentClient is implemented by Cloud only; Server returns ErrUnsupportedOnHost.

func AsDeploymentClient added in v1.29.0 

func AsDeploymentClient(c Client, host string) (DeploymentClient, error)

AsDeploymentClient returns the DeploymentClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not implement the Deployments capability.

type DiffClient added in v1.49.0 

type DiffClient interface {
	GetDiff(ns, slug, from, to string) (string, error)
	GetDiffStat(ns, slug, from, to string) (DiffStat, error)
}

DiffClient is implemented by both Cloud and Server backends.

func AsDiffClient added in v1.49.0 

func AsDiffClient(c Client, host string) (DiffClient, error)

AsDiffClient returns the DiffClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not implement the Diff capability.

type DiffStat added in v1.49.0 

type DiffStat struct {
	FilesChanged int
	Additions    int
	Deletions    int
	Files        []DiffStatEntry
}

DiffStat is the domain representation of a repository diff summary.

type DiffStatEntry added in v1.49.0 

type DiffStatEntry struct {
	Path      string
	Status    string // "added", "modified", "deleted", "renamed"
	Additions int
	Deletions int
}

DiffStatEntry is the domain representation of a single file's diff summary.

type DomainError added in v1.8.0 

type DomainError struct {
	Kind     error
	Code     ErrorCode
	Host     string
	Feature  string
	Resource string
	ID       string
	Message  string
	Cause    error
}

DomainError wraps an underlying cause with structured context for renderers (CLI plain-text, MCP structured payload). Kind is one of the package-level sentinels; errors.Is(err, backend.ErrXxx) walks Kind, enabling deterministic branching without parsing prose.

Optional fields populated when known:

  • Host: the hostname the request was directed at
  • Feature: capability name, populated for ErrUnsupportedOnHost
  • Resource: domain kind ("pull-request", "branch", "repository", ...)
  • ID: resource identifier ("42", "feat/x", "ws/repo", ...)
  • Code: dotted ErrorCode token used by errfmt to look up the user-facing title + hint. Auto-attached for HTTP 401 by ClassifyHTTPError; otherwise stamped by adapters at the call site (where they have op-specific context). May be empty — Render then falls back to a Kind-based humanisation.

func ClassifyHTTPError added in v1.8.0 

func ClassifyHTTPError(host string, err *HTTPError) *DomainError

ClassifyHTTPError translates an HTTPError into a DomainError, picking a Kind sentinel from the response status code. Statuses outside the bounded domain set leave Kind unset; the original HTTPError is preserved as Cause in every case so adapters can attach further context (resource, ID, etc.).

Only HTTP 401 receives an automatic Code (CodeAuthInvalidToken) — re-login is an unambiguous remedy that does not need adapter context. 403/404/409 each map to multiple user-facing situations (which resource? which write op?) and so the adapter that issued the request stamps the appropriate Code at the call site, where the necessary context lives.

func ClassifyTransportError added in v1.19.0 

func ClassifyTransportError(host string, err error) *DomainError

ClassifyTransportError translates a transport-level error (one that failed before an HTTP response existed — TLS handshake failure, DNS resolution timeout, dial timeout, read timeout, etc.) into a DomainError carrying a network-cluster ErrorCode. host is attached so the renderer can name which Bitbucket instance produced the failure.

Returns nil if err is nil, or if err is not a recognised transport failure shape — callers should treat the original error as untranslated and either return it as-is or fall through to a generic renderer. The intent is "do no harm": never mis-label an error.

Recognised shapes:

  • x509.UnknownAuthorityError (anywhere in the unwrap chain) → CodeNetworkTLSUnknownAuthority. Triggered by self-signed CAs; the catalogue hints at -k / skip_tls_verify.
  • context.DeadlineExceeded (anywhere in the unwrap chain) → CodeTransportTimeout. Triggered by per-request deadlines.
  • any net.Error whose Timeout() returns true → CodeTransportTimeout. Covers dial timeouts and read timeouts surfaced as *net.OpError.

Kind is set to ErrTransport in every classified case so callers can branch on errors.Is(err, backend.ErrTransport).

func (*DomainError) Error added in v1.8.0 

func (e *DomainError) Error() string

Error renders a single-line human-readable form. Structured emission (e.g. MCP) should read the fields directly rather than parsing this string.

func (*DomainError) HTTPStatus added in v1.19.0 

func (e *DomainError) HTTPStatus() int

HTTPStatus returns the HTTP status code that produced this DomainError, or 0 if the underlying cause is not an *HTTPError. Useful for adapters that need to refine call-site Code stamping based on status (e.g. 404 → not found, 409 → conflict). Walks the unwrap chain via errors.As.

func (*DomainError) Is added in v1.8.0 

func (e *DomainError) Is(target error) bool

Is matches against the Kind sentinel. The wrapped Cause is reached via Unwrap by errors.Is's default walk — intentionally not duplicated here.

func (*DomainError) Unwrap added in v1.8.0 

func (e *DomainError) Unwrap() error

Unwrap exposes the underlying cause for errors.Is / errors.As walks.

type EnvVariable added in v1.29.0 

type EnvVariable struct {
	UUID    string
	Key     string
	Value   string // empty if Secured
	Secured bool
}

EnvVariable is a deployment-environment variable on Bitbucket Cloud. Value is empty when Secured is true (the API never returns secured values).

type EnvVariableInput added in v1.29.0 

type EnvVariableInput struct {
	Key     string
	Value   string
	Secured bool
}

EnvVariableInput carries the parameters for creating or updating an environment variable.

type Environment added in v1.29.0 

type Environment struct {
	UUID string
	Name string
	Type string // Test | Staging | Production
	Rank int
}

Environment is a Bitbucket Cloud deployment environment (e.g. Test, Staging, Production). Rank is the numeric ordering position.

type ErrorCode added in v1.18.0 

type ErrorCode string

ErrorCode is a stable, dotted token identifying a specific user-visible failure mode (e.g. "auth.invalid_token"). Codes are the join key between the API layer (which classifies wire errors) and the errfmt renderer (which looks up titles + hints). Treat them as part of the public API: add new codes freely, never repurpose existing ones. 

const (
	// auth cluster — credentials missing, expired, or insufficient
	CodeAuthNoToken       ErrorCode = "auth.no_token"
	CodeAuthInvalidToken  ErrorCode = "auth.invalid_token"
	CodePermWriteRequired ErrorCode = "perm.write_required"

	// repo cluster — repository-shaped failures
	CodeRepoNotFound ErrorCode = "repo.not_found"

	// pr cluster — pull-request lifecycle failures
	CodePRNotFound              ErrorCode = "pr.not_found"
	CodePRMergeConflict         ErrorCode = "pr.merge.conflict"
	CodePRMergeBehind           ErrorCode = "pr.merge.behind"
	CodePRCreateDuplicateBranch ErrorCode = "pr.create.duplicate_branch"
	CodePRReviewerUnknown       ErrorCode = "pr.reviewer.unknown"
	// CodePRAutoMergeBetaDisabled is returned by Bitbucket Cloud when the
	// auto-merge beta endpoint is unavailable because the workspace has not
	// opted into the feature.
	CodePRAutoMergeBetaDisabled ErrorCode = "pr.automerge.beta_disabled"

	// branch cluster — branch-protection / write-side failures
	CodeBranchProtected ErrorCode = "branch.protected"

	// host cluster — feature unavailable on the targeted Bitbucket flavour
	CodeHostUnsupported ErrorCode = "host.unsupported"

	// network cluster — pre-classify codes attached at the transport
	// layer before an HTTPError exists. ClassifyTransportError stamps
	// these.
	CodeNetworkTLSUnknownAuthority ErrorCode = "network.tls_unknown_authority"
	CodeTransportTimeout           ErrorCode = "transport.timeout"
)

Catalogue of error codes. Group by cluster prefix; keep alphabetical inside each cluster. errfmt has a matching catalogue of titles + hints.

type Feature added in v1.8.0 

type Feature string

Feature names a capability that some backends may not implement. The As<X> helpers map each Feature to the optional interface a Client must satisfy to expose that capability. 

const FeatureAdmin Feature = "admin"

FeatureAdmin names the admin capability. 

const FeatureBranchProtect Feature = "branch-protect"

FeatureBranchProtect names the branch-protection capability for typed- error reporting. 

const FeatureBranchRules Feature = "branch_rules"

FeatureBranchRules names the branch-rules capability for typed-error reporting. 

const FeatureCodeInsights Feature = "code-insights"

FeatureCodeInsights names the Code Insights capability for typed-error reporting. 

const FeatureCodeSearch Feature = "code-search"

FeatureCodeSearch names the code-search capability for typed-error reporting. 

const FeatureCommentReactions Feature = "pr-comment-reactions"

FeatureCommentReactions names the PR comment reaction capability. 

const FeatureCommitCommentReactions Feature = "commit-comment-reactions"

FeatureCommitCommentReactions names the commit comment reaction capability. 

const FeatureCommitFiles Feature = "commit_files"

FeatureCommitFiles names the commit-files capability for typed-error reporting. 

const FeatureDefaultReviewerClient Feature = "default_reviewer_client"

FeatureDefaultReviewerClient names the default-reviewer-client capability for typed-error reporting. 

const FeatureDefaultReviewers Feature = "default-reviewers"

FeatureDefaultReviewers names the default-reviewers capability for typed-error reporting. 

const FeatureDeployKeys Feature = "deploy_keys"

FeatureDeployKeys names the deploy-keys capability for typed-error reporting. 

const FeatureDeployments Feature = "deployments"

FeatureDeployments names the deployments capability for typed-error reporting. 

const FeatureDiff Feature = "diff"

FeatureDiff names the diff capability for typed-error reporting. 

const FeatureIssues Feature = "issues"

FeatureIssues names the issues capability for typed-error reporting. 

const FeaturePRCommentResolve Feature = "pr-comment-resolve"

FeaturePRCommentResolve names the inline-comment resolution capability for typed-error reporting via AsPRCommentResolver. 

const FeaturePRCommentStateSet Feature = "pr-task"

PRCommentStateSetterFeature names the PR task (comment-state) capability. 

const FeaturePRCommits Feature = "pr_commits"

FeaturePRCommits names the PR-commits capability for typed-error reporting. 

const FeaturePRFiles Feature = "pr_files"

FeaturePRFiles names the PR-files capability for typed-error reporting. 

const FeaturePRParticipants Feature = "pr_participants"

FeaturePRParticipants names the PR-participants capability for typed-error reporting. 

const FeaturePRReopen Feature = "pr-reopen"

FeaturePRReopen names the PR-reopen capability for typed-error reporting. Bitbucket Cloud has no reopen primitive (BCLOUD-23807), so callers gate the feature behind AsPRReopener. 

const FeaturePRSuggestion Feature = "pr-suggestion"

FeaturePRSuggestion names the PR suggestion capability. 

const FeaturePermissions Feature = "permissions"

FeaturePermissions names the permissions management capability. 

const FeaturePipelineCache Feature = "pipeline-cache"

FeaturePipelineCache names the pipeline-cache capability for typed-error reporting. 

const FeaturePipelineSchedules Feature = "pipeline_schedules"

FeaturePipelineSchedules names the pipeline-schedules capability for typed-error reporting. 

const FeaturePipelineTrigger Feature = "pipeline_trigger"

FeaturePipelineTrigger names the pipeline-trigger capability for typed-error reporting. 

const FeaturePipelines Feature = "pipelines"

FeaturePipelines names the pipelines capability for typed-error reporting. 

const FeatureRepoFork Feature = "repo-fork"

FeatureRepoFork names the repo-fork capability for typed-error reporting. 

const FeatureRepoForks Feature = "repo-forks"

FeatureRepoForks names the repo-forks-list capability for typed-error reporting. 

const FeatureRepoTransfer Feature = "repo_transfer"

FeatureRepoTransfer names the repo-transfer capability for typed-error reporting. 

const FeatureRepoWatchers Feature = "repo_watchers"

FeatureRepoWatchers names the repo-watchers capability for typed-error reporting. 

const FeatureReviewerGroup Feature = "reviewer-group"

FeatureReviewerGroup names the reviewer-group capability for typed-error reporting. 

const FeatureSSHKeys Feature = "ssh_keys"

FeatureSSHKeys names the ssh-keys capability for typed-error reporting. 

const FeatureServerVersion Feature = "server-version"

FeatureServerVersion names the server-version capability for typed-error reporting. 

const FeatureWorkspaceMembers Feature = "workspace_members"
const FeatureWorkspaceVariables Feature = "workspace-variables"
const FeatureWorkspaceWebhooks Feature = "workspace-webhooks"

FeatureWorkspaceWebhooks names the workspace-webhook capability. 

const FeatureWorkspaces Feature = "workspaces"

FeatureWorkspaces names the workspace/project listing capability for typed-error reporting.

type ForkRepoInput added in v1.16.0 

type ForkRepoInput struct {
	Workspace string
	Name      string
}

ForkRepoInput carries the parameters for forking a Bitbucket Cloud repository. Workspace is required (the fork's destination workspace). Name is optional — when empty, Bitbucket Cloud reuses the source name.

type HTTPError 

type HTTPError struct {
	StatusCode int
	Message    string
	RequestURL string
}

HTTPError represents an error HTTP response from the Bitbucket API.

func (*HTTPError) Error 

func (e *HTTPError) Error() string

Error implements the error interface.

type Issue added in v1.17.0 

type Issue struct {
	ID        int
	Title     string
	State     string // new, open, on hold, resolved, duplicate, invalid, wontfix, closed
	Kind      string // bug, enhancement, proposal, task
	Priority  string // trivial, minor, major, critical, blocker
	Reporter  User
	Assignee  *User // nil when unassigned
	CreatedOn time.Time
	UpdatedOn time.Time
	WebURL    string
	Content   string // raw markdown body
}

Issue is a Bitbucket Cloud issue. Issues are a Cloud-only feature gated by per-repository "issue tracker" enablement; the API returns 404 on repositories where the tracker is disabled. We surface that as the adapter's standard ErrNotFound.

Assignee is a pointer so the zero value cleanly distinguishes "unassigned" from "assigned to user with empty username". Reporter is always present on Cloud and uses the value type.

type IssueClient added in v1.17.0 

type IssueClient interface {
	ListIssues(ns, slug, state string, limit int) ([]Issue, error)
	GetIssue(ns, slug string, id int) (Issue, error)
	CreateIssue(ns, slug string, in CreateIssueInput) (Issue, error)
	UpdateIssue(ns, slug string, id int, in UpdateIssueInput) (Issue, error)
	ReopenIssue(ns, slug string, id int) error
	AssignIssue(ns, slug string, id int, assignee string) error
	ListIssueComments(ns, slug string, id int) ([]IssueComment, error)
	AddIssueComment(ns, slug string, id int, body string) (IssueComment, error)
	EditIssueComment(ns, slug string, id, commentID int, body string) (IssueComment, error)
	DeleteIssueComment(ns, slug string, id, commentID int) error
}

IssueClient is implemented only by Bitbucket Cloud clients. Bitbucket Server / Data Center has no built-in issue tracker, so the entire issue surface is gated behind AsIssueClient.

func AsIssueClient added in v1.17.0 

func AsIssueClient(c Client, host string) (IssueClient, error)

AsIssueClient returns the IssueClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) when called against a Server/DC backend.

type IssueComment added in v1.23.0 

type IssueComment struct {
	ID        int
	Author    User
	Content   string
	CreatedOn time.Time
	UpdatedOn time.Time
}

IssueComment is a comment on a Bitbucket Cloud issue.

type LoggingConfig added in v1.38.0 

type LoggingConfig struct {
	Level      string // DEBUG | INFO | WARN | ERROR
	Async      bool
	Persistent bool // write-only flag; ignored in GetLoggingConfig response
}

LoggingConfig is the domain representation of the Bitbucket Server / Data Center logging configuration. Level is one of DEBUG, INFO, WARN, ERROR. Async controls whether log events are written asynchronously. Persistent, when true, directs SetLoggingConfig to write to log4j.properties so the change survives restarts; false = runtime-only.

type LoggingConfigInput added in v1.38.0 

type LoggingConfigInput = LoggingConfig

LoggingConfigInput is the upsert payload for SetLoggingConfig. It mirrors LoggingConfig; the alias exists so the interface signature stays explicit.

type MergeCheck added in v1.23.0 

type MergeCheck struct {
	Key         string `json:"key"`
	ReportKey   string `json:"report_key"`
	MustPass    bool   `json:"must_pass"`
	MinSeverity string `json:"min_severity,omitempty"`
}

MergeCheck represents a Code Insights merge-check configuration. Merge checks block PR merges when report criteria are not met. This feature is partly undocumented in the Bitbucket Server REST API — treat output as best-effort.

MinSeverity values: "LOW", "MEDIUM", "HIGH", "CRITICAL" (empty = no threshold).

type MergeCheckInput added in v1.23.0 

type MergeCheckInput = MergeCheck

MergeCheckInput is an alias of MergeCheck used on the write side.

type MergePRInput 

type MergePRInput struct {
	Message  string
	Strategy string
}

MergePRInput carries the parameters for merging a pull request.

type MyPREntry added in v1.28.0 

type MyPREntry struct {
	PullRequest        // embed — carries ID, Title, State, Author, WebURL, HeadCommitHash
	Repo        string // "PROJECT/REPO" (Server) or "workspace/slug" (Cloud)
	Role        string // "AUTHOR" | "REVIEWER"
}

MyPREntry is a cross-repo PR summary for the status dashboard.

type Options added in v1.1.1 

type Options struct {
	Token         string
	SkipTLSVerify bool
	// Email is the Atlassian account email address used as the HTTP Basic auth
	// identity for Bitbucket Cloud when authenticating with an Atlassian API
	// token. Leave empty when using a Bearer / OAuth2 token.
	Email string
	// Username is the Bitbucket Server/DC username used as the HTTP Basic auth
	// identity. Not used for Bitbucket Cloud.
	Username string
}

Options overrides the stored config when constructing a backend client. Used by auth login to validate a new token before it is persisted.

type PRActivityEvent added in v1.26.0 

type PRActivityEvent struct {
	Type      string
	Actor     User
	CreatedAt time.Time
	Detail    map[string]any
}

PRActivityEvent is one event in the pull-request activity stream. Type is a normalised event kind: "approval", "unapproval", "comment", "update", "merge", "declined", "rescoped". Detail carries the raw sub-object so callers can surface backend-specific fields via --json.

type PRActivityReader added in v1.26.0 

type PRActivityReader interface {
	GetPRActivity(ns, slug string, id int, limit int) ([]PRActivityEvent, error)
}

PRActivityReader reads the activity event stream for a pull request.

type PRApprover 

type PRApprover interface {
	ApprovePR(ns, slug string, id int) error
}

PRApprover approves a pull request.

type PRBranchUpdater added in v1.28.0 

type PRBranchUpdater interface {
	UpdatePRBranch(ns, slug string, prID int) error
}

PRBranchUpdater syncs a PR's source branch with its base branch.

type PRChangesRequester 

type PRChangesRequester interface {
	RequestChangesPR(ns, slug string, id int) error
}

PRChangesRequester can request changes on a pull request (Cloud only). Access via type assertion — not embedded in Client.

type PRComment added in v1.6.0 

type PRComment struct {
	ID        int
	Author    User
	Text      string
	CreatedAt time.Time
	UpdatedAt time.Time
	Inline    *PRCommentInline
	ParentID  int
	Resolved  bool
	Severity  string            // "" | "BLOCKER" (Server task comments)
	State     string            // "" | "OPEN" | "RESOLVED" (Server task comments)
	Version   int               // optimistic-lock token (Server only)
	Reactions []CommentReaction // only populated when explicitly requested; Server/DC only
}

PRComment is the domain representation of a comment on a pull request. Inline is non-nil for inline (file:line) review comments and nil for general PR comments. ParentID is 0 for top-level comments and the parent comment's ID for replies. Resolved reflects backend-native resolution state (Cloud `resolution`); on Server it is always false because the equivalent concept lives on tasks (RV3 scope).

Severity, State, and Version are populated on Bitbucket Server / Data Center for task-like comments (comments with severity="BLOCKER"). Severity is "BLOCKER" for tasks and "" for regular comments. State is "OPEN" or "RESOLVED" for tasks and "" for regular comments. Version is the optimistic-lock token required by SetPRCommentState on Server.

Reactions is only populated when explicitly requested (e.g. --reactions flag or include_reactions MCP parameter). Server/DC only.

type PRCommentAdder added in v1.6.0 

type PRCommentAdder interface {
	AddPRComment(ns, slug string, id int, in AddPRCommentInput) (PRComment, error)
}

PRCommentAdder adds a general comment to a pull request.

type PRCommentDeleter added in v1.24.0 

type PRCommentDeleter interface {
	DeletePRComment(ns, slug string, id, commentID int) error
}

PRCommentDeleter removes a comment from a pull request.

type PRCommentEditor added in v1.24.0 

type PRCommentEditor interface {
	EditPRComment(ns, slug string, id, commentID int, body string) (PRComment, error)
}

PRCommentEditor updates the body of an existing comment on a pull request.

type PRCommentInline added in v1.22.0 

type PRCommentInline struct {
	Path      string
	Side      string // "old" | "new"
	Line      int
	StartLine int // 0 = single-line
}

PRCommentInline anchors a PR comment to a file and line range in the diff. Side is "old" (LHS / from-side) or "new" (RHS / to-side). StartLine is 0 for single-line comments and set to the first line of the range for multi-line comments; Line is the last (or only) line.

type PRCommentLister added in v1.6.0 

type PRCommentLister interface {
	ListPRComments(ns, slug string, id int) ([]PRComment, error)
}

PRCommentLister lists top-level comments on a pull request.

type PRCommentResolver added in v1.24.0 

type PRCommentResolver interface {
	ResolvePRComment(ns, slug string, id, commentID int) error
}

PRCommentResolver marks a PR comment as resolved. Implemented only by Bitbucket Cloud (whose comments carry a native `resolution` field). Bitbucket Server has no equivalent concept on regular comments — the closest analogue lives on tasks, which is a separate feature scope — so callers route through AsPRCommentResolver and surface the constraint as a typed ErrUnsupportedOnHost.

func AsPRCommentResolver added in v1.24.0 

func AsPRCommentResolver(c Client, host string) (PRCommentResolver, error)

AsPRCommentResolver returns the PRCommentResolver view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) when the backend at host has no resolution primitive (currently Bitbucket Server / Data Center).

type PRCommentStateSetter added in v1.39.0 

type PRCommentStateSetter interface {
	SetPRCommentState(ns, slug string, id, commentID int, state string) error
}

PRCommentStateSetter sets the state of a PR comment (task). Implemented only by Bitbucket Server / Data Center (where tasks are BLOCKER comments with an OPEN/RESOLVED state). Bitbucket Cloud has no equivalent concept, so callers route through AsPRCommentStateSetter to surface the constraint as a typed ErrUnsupportedOnHost.

func AsPRCommentStateSetter added in v1.39.0 

func AsPRCommentStateSetter(c Client, host string) (PRCommentStateSetter, error)

AsPRCommentStateSetter returns the PRCommentStateSetter view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) when the backend has no task-state primitive (currently Bitbucket Cloud).

type PRCommitClient added in v1.56.0 

type PRCommitClient interface {
	ListPRCommits(ns, slug string, prID int) ([]Commit, error)
}

PRCommitClient is implemented by both Cloud and Server backends.

func AsPRCommitClient added in v1.56.0 

func AsPRCommitClient(c Client, host string) (PRCommitClient, error)

AsPRCommitClient returns the PRCommitClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not implement the PRCommits capability.

type PRCreator 

type PRCreator interface {
	CreatePR(ns, slug string, in CreatePRInput) (PullRequest, error)
}

PRCreator creates a pull request.

type PRDecliner 

type PRDecliner interface {
	DeclinePR(ns, slug string, id int) error
}

PRDecliner declines a pull request.

type PRDiffer 

type PRDiffer interface {
	GetPRDiff(ns, slug string, id int) (string, error)
}

PRDiffer returns the unified diff for a pull request.

type PREditor 

type PREditor interface {
	UpdatePR(ns, slug string, id int, in UpdatePRInput) (PullRequest, error)
}

PREditor updates a pull request's title or description.

type PRFileClient added in v1.57.0 

type PRFileClient interface {
	ListPRFiles(ns, slug string, prID int) ([]DiffStatEntry, error)
}

PRFileClient is implemented by both Cloud and Server backends.

func AsPRFileClient added in v1.57.0 

func AsPRFileClient(c Client, host string) (PRFileClient, error)

AsPRFileClient returns the PRFileClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not implement the PRFiles capability.

type PRLister 

type PRLister interface {
	ListPRs(ns, slug, state string, limit int) ([]PullRequest, error)
}

PRLister lists pull requests.

type PRMerger 

type PRMerger interface {
	MergePR(ns, slug string, id int, in MergePRInput) (PullRequest, error)
	// EnableAutoMerge queues a PR for automatic merge once all checks pass.
	// strategy is the CLI vocabulary value: "merge" | "squash" | "rebase".
	EnableAutoMerge(ns, slug string, id int, strategy string) error
	// DisableAutoMerge cancels a queued auto-merge for the given PR.
	DisableAutoMerge(ns, slug string, id int) error
}

PRMerger merges a pull request and manages auto-merge queuing.

type PRParticipant added in v1.60.0 

type PRParticipant struct {
	User     User
	Role     string // AUTHOR | REVIEWER | PARTICIPANT
	Approved bool
	State    string // APPROVED | CHANGES_REQUESTED | "" (empty = unapproved)
}

PRParticipant is a user involved in a pull request.

type PRParticipantClient added in v1.60.0 

type PRParticipantClient interface {
	ListPRParticipants(ns, slug string, prID int) ([]PRParticipant, error)
}

PRParticipantClient is implemented by both Cloud and Server backends.

func AsPRParticipantClient added in v1.60.0 

func AsPRParticipantClient(c Client, host string) (PRParticipantClient, error)

AsPRParticipantClient returns the PRParticipantClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not implement the PRParticipants capability.

type PRReader 

type PRReader interface {
	GetPR(ns, slug string, id int) (PullRequest, error)
}

PRReader reads a single pull request.

type PRReadier 

type PRReadier interface {
	ReadyPR(ns, slug string, id int) error
}

PRReadier marks a draft pull request as ready for review.

type PRReopener added in v1.21.0 

type PRReopener interface {
	ReopenPR(ns, slug string, id int) error
}

PRReopener reverses a decline. Implemented only by Bitbucket Server / Data Center (POST /pull-requests/{id}/reopen). Bitbucket Cloud has no reopen primitive — declined PRs are terminal there (BCLOUD-23807) — so callers route through AsPRReopener so the Cloud-only constraint surfaces as a typed ErrUnsupportedOnHost rather than a panic.

func AsPRReopener added in v1.21.0 

func AsPRReopener(c Client, host string) (PRReopener, error)

AsPRReopener returns the PRReopener view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) when the backend at host has no reopen primitive (currently Bitbucket Cloud).

type PRReviewRequester 

type PRReviewRequester interface {
	RequestReview(ns, slug string, id int, users []string) error
}

PRReviewRequester requests reviewers on a pull request.

type PRReviewer added in v1.25.0 

type PRReviewer interface {
	SubmitReview(ns, slug string, id int, in SubmitReviewInput) error
}

PRReviewer submits a compound review on a pull request — an optional top-level body comment, zero or more inline comments, and a review action (approve / request_changes / comment). The adapter sequences the writes internally so callers express "what the review looks like" rather than "how to assemble it".

type PRStatusLister added in v1.28.0 

type PRStatusLister interface {
	ListMyPRs(ns, slug string) ([]MyPREntry, error)
}

PRStatusLister returns the authenticated user's open PRs across all repos.

type PRUnapprover 

type PRUnapprover interface {
	UnapprovePR(ns, slug string, id int) error
}

PRUnapprover removes approval from a pull request.

type PermissionGrant added in v1.37.0 

type PermissionGrant struct {
	Subject    PermissionSubject
	Permission string
}

PermissionGrant pairs a subject (user or group) with a permission level. Permission values: 

PROJECT_READ, PROJECT_WRITE, PROJECT_ADMIN
REPO_READ, REPO_WRITE, REPO_ADMIN

type PermissionSubject added in v1.37.0 

type PermissionSubject struct {
	Kind        string // "user" | "group"
	Slug        string // user slug (Kind=user)
	Name        string // group name (Kind=group)
	DisplayName string // populated on read; ignored on write
}

PermissionSubject identifies a user or group in a permission grant. Kind is "user" or "group". For users, Slug is the login slug. For groups, Name is the group name (may contain spaces). DisplayName is populated on read from the API and ignored on write.

type PermissionsClient added in v1.37.0 

type PermissionsClient interface {
	ListProjectPermissions(ctx context.Context, project string) ([]PermissionGrant, error)
	GrantProjectPermission(ctx context.Context, project string, subject PermissionSubject, perm string) error
	RevokeProjectPermission(ctx context.Context, project string, subject PermissionSubject) error

	ListRepoPermissions(ctx context.Context, project, slug string) ([]PermissionGrant, error)
	GrantRepoPermission(ctx context.Context, project, slug string, subject PermissionSubject, perm string) error
	RevokeRepoPermission(ctx context.Context, project, slug string, subject PermissionSubject) error
}

PermissionsClient exposes Bitbucket Server / Data Center permission management for projects and repositories. Bitbucket Cloud has a different permissions model — AsPermissionsClient returns ErrUnsupportedOnHost when called against a Cloud backend.

func AsPermissionsClient added in v1.37.0 

func AsPermissionsClient(c Client, host string) (PermissionsClient, error)

AsPermissionsClient returns the PermissionsClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) when called against a backend that doesn't implement permissions management (currently Bitbucket Cloud).

type Pipeline 

type Pipeline struct {
	UUID        string
	BuildNumber int
	State       string // PENDING, IN_PROGRESS, SUCCESSFUL, FAILED, ERROR, STOPPED
	RefType     string // "branch", "tag", "commit"
	RefName     string
	CreatedOn   string
	Duration    int // seconds
	WebURL      string
}

Pipeline is the domain representation of a Bitbucket Cloud pipeline run.

type PipelineCache added in v1.67.0 

type PipelineCache struct {
	UUID          string `json:"uuid"`
	Name          string `json:"name"`
	Path          string `json:"path"`
	FileSizeBytes int64  `json:"fileSizeBytes"`
	CreatedOn     string `json:"createdOn"`
}

PipelineCache is a named cache entry for a Bitbucket Cloud pipeline.

type PipelineCacheClient added in v1.67.0 

type PipelineCacheClient interface {
	ListPipelineCaches(ns, slug string) ([]PipelineCache, error)
	DeletePipelineCache(ns, slug, uuid string) error
}

PipelineCacheClient is implemented only by Bitbucket Cloud clients.

func AsPipelineCacheClient added in v1.67.0 

func AsPipelineCacheClient(c Client, host string) (PipelineCacheClient, error)

AsPipelineCacheClient returns the PipelineCacheClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host has no pipeline-cache primitive (Bitbucket Server / Data Center).

type PipelineClient 

type PipelineClient interface {
	ListPipelines(ns, slug string, limit int) ([]Pipeline, error)
	GetPipeline(ns, slug, uuid string) (Pipeline, error)
	RunPipeline(ns, slug string, in RunPipelineInput) (Pipeline, error)
	ListPipelineSteps(ns, slug, uuid string) ([]PipelineStep, error)
	GetPipelineStepLog(ns, slug, pipelineUUID, stepUUID string) (io.ReadCloser, error)
	ListPipelineVariables(ns, slug string) ([]PipelineVariable, error)
	SetPipelineVariable(ns, slug string, in PipelineVariableInput) (PipelineVariable, error)
	DeletePipelineVariable(ns, slug, key string) error
}

PipelineClient is implemented only by Bitbucket Cloud clients.

func AsPipelineClient 

func AsPipelineClient(c Client, host string) (PipelineClient, error)

AsPipelineClient returns the PipelineClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not implement the Pipelines capability.

type PipelineSchedule added in v1.54.0 

type PipelineSchedule struct {
	UUID           string `json:"uuid"`
	Enabled        bool   `json:"enabled"`
	CronExpression string `json:"cronExpression"`
	Branch         string `json:"branch"`
}

PipelineSchedule is the domain representation of a Bitbucket Cloud pipeline schedule.

type PipelineScheduleClient added in v1.54.0 

type PipelineScheduleClient interface {
	ListPipelineSchedules(ns, slug string) ([]PipelineSchedule, error)
	CreatePipelineSchedule(ns, slug string, input PipelineScheduleInput) (PipelineSchedule, error)
	DeletePipelineSchedule(ns, slug, uuid string) error
}

PipelineScheduleClient is implemented only by Bitbucket Cloud clients.

func AsPipelineScheduleClient added in v1.54.0 

func AsPipelineScheduleClient(c Client, host string) (PipelineScheduleClient, error)

AsPipelineScheduleClient returns the PipelineScheduleClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not implement the PipelineSchedules capability.

type PipelineScheduleInput added in v1.54.0 

type PipelineScheduleInput struct {
	CronExpression string
	Branch         string
	Enabled        bool
}

PipelineScheduleInput carries the parameters for creating a pipeline schedule.

type PipelineStep added in v1.15.0 

type PipelineStep struct {
	UUID     string
	Name     string
	State    string // PENDING, IN_PROGRESS, SUCCESSFUL, FAILED, ERROR, STOPPED
	Result   string // populated when State has flattened from COMPLETED
	Duration int    // seconds
}

PipelineStep is the domain representation of a single step within a Bitbucket Cloud pipeline run.

type PipelineTriggerClient added in v1.48.0 

type PipelineTriggerClient interface {
	TriggerPipeline(ns, slug string, input PipelineTriggerInput) (PipelineTriggerResult, error)
}

PipelineTriggerClient is implemented only by Bitbucket Cloud clients.

func AsPipelineTriggerClient added in v1.48.0 

func AsPipelineTriggerClient(c Client, host string) (PipelineTriggerClient, error)

AsPipelineTriggerClient returns the PipelineTriggerClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not implement the PipelineTrigger capability.

type PipelineTriggerInput added in v1.48.0 

type PipelineTriggerInput struct {
	Branch    string
	Variables []PipelineVariable
}

PipelineTriggerInput carries the parameters for triggering a pipeline via the PipelineTriggerClient interface. Variables supplements the per-run environment; each entry maps to a Bitbucket pipeline variable object.

type PipelineTriggerResult added in v1.48.0 

type PipelineTriggerResult struct {
	UUID  string `json:"uuid"`
	State string `json:"state"`
	Link  string `json:"link"`
}

PipelineTriggerResult is returned by TriggerPipeline on success.

type PipelineVariable added in v1.15.0 

type PipelineVariable struct {
	UUID    string
	Key     string
	Value   string
	Secured bool
}

PipelineVariable is a repository-level pipeline variable on Bitbucket Cloud. Value is empty when Secured is true (the API never returns secured values).

type PipelineVariableInput added in v1.15.0 

type PipelineVariableInput struct {
	Key     string
	Value   string
	Secured bool
}

PipelineVariableInput carries the parameters for upserting a pipeline variable by Key.

type Project added in v1.17.0 

type Project struct {
	Key    string
	Name   string
	UUID   string
	WebURL string
}

Project is a Bitbucket Cloud project (a logical group of repositories inside a workspace). The naming clashes with Server/DC's "project" — which is the namespace itself — but Cloud's project sits one level deeper. Listed via WorkspaceClient.ListProjects(workspace).

type PullRequest 

type PullRequest struct {
	ID             int
	Title          string
	Description    string
	State          string
	Draft          bool
	Author         User
	FromBranch     string
	ToBranch       string
	WebURL         string
	HeadCommitHash string
	AutoMerge      *AutoMergeState // nil when auto-merge is not enabled
}

PullRequest is the domain representation of a Bitbucket pull request.

type RepoDeleter 

type RepoDeleter interface {
	DeleteRepo(ns, slug string) error
}

RepoDeleter deletes a repository.

type RepoForker added in v1.16.0 

type RepoForker interface {
	ForkRepo(ns, slug string, in ForkRepoInput) (Repository, error)
}

RepoForker is implemented only by Bitbucket Cloud clients — Bitbucket Server / Data Center has no fork primitive in its REST API. Access via AsRepoForker so the Cloud-only constraint surfaces as a typed ErrUnsupportedOnHost error rather than a panic.

func AsRepoForker added in v1.16.0 

func AsRepoForker(c Client, host string) (RepoForker, error)

AsRepoForker returns the RepoForker view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host has no fork primitive (Bitbucket Server / Data Center).

type RepoForksLister added in v1.64.0 

type RepoForksLister interface {
	ListRepoForks(ns, slug string, limit int) ([]Repository, error)
}

RepoForksLister lists forks of a repository. Both Cloud and Server support this.

func AsRepoForksLister added in v1.64.0 

func AsRepoForksLister(c Client, host string) (RepoForksLister, error)

AsRepoForksLister returns the RepoForksLister view of c, or a typed *DomainError.

type RepoLister 

type RepoLister interface {
	ListRepos(ns string, limit int) ([]Repository, error)
}

RepoLister lists repositories. ns is the workspace (Bitbucket Cloud) or project key (Bitbucket Server); pass "" for Server to list all repos.

type RepoReader 

type RepoReader interface {
	GetRepo(ns, slug string) (Repository, error)
}

RepoReader reads a single repository.

type RepoRenamer added in v1.16.0 

type RepoRenamer interface {
	RenameRepo(ns, slug, newName string) (Repository, error)
}

RepoRenamer renames a repository.

type RepoTransferClient added in v1.52.0 

type RepoTransferClient interface {
	TransferRepo(ns, slug, target string) (Repository, error)
}

RepoTransferClient transfers a repository to another project (Server) or workspace (Cloud).

func AsRepoTransferClient added in v1.52.0 

func AsRepoTransferClient(c Client, host string) (RepoTransferClient, error)

AsRepoTransferClient returns the RepoTransferClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not implement the RepoTransfer capability.

type RepoVisibilitySetter added in v1.65.0 

type RepoVisibilitySetter interface {
	SetRepoVisibility(ns, slug string, isPrivate bool) error
}

RepoVisibilitySetter sets a repository's public/private visibility.

type RepoWatcherClient added in v1.58.0 

type RepoWatcherClient interface {
	ListRepoWatchers(ns, slug string) ([]User, error)
}

RepoWatcherClient is implemented by both Cloud and Server backends.

func AsRepoWatcherClient added in v1.58.0 

func AsRepoWatcherClient(c Client, host string) (RepoWatcherClient, error)

AsRepoWatcherClient returns the RepoWatcherClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not implement the RepoWatchers capability.

type RepoWriter 

type RepoWriter interface {
	CreateRepo(ns string, in CreateRepoInput) (Repository, error)
}

RepoWriter creates a repository.

type Repository 

type Repository struct {
	Slug        string
	Name        string
	Namespace   string
	SCM         string
	WebURL      string
	Description string
	IsPrivate   bool
	ID          int
}

Repository is the domain representation of a Bitbucket repository.

ID is the backend's numeric identifier (Server / Data Center). Cloud uses opaque UUIDs surfaced through other channels; for Cloud repos this field stays zero. ID is exposed so the BBS default-reviewers endpoint (which requires source/target repo IDs as query params) has what it needs without an adapter-internal cache.

type ReviewerGroup added in v1.69.0 

type ReviewerGroup struct {
	ID                int    `json:"id"`
	Name              string `json:"name"`
	RequiredApprovals int    `json:"requiredApprovals"`
	Reviewers         []User `json:"reviewers"`
}

ReviewerGroup is the domain representation of a Bitbucket Server / Data Center default-reviewers condition. Each condition defines a set of reviewers that are automatically required for PRs matching a source/target ref pattern.

type ReviewerGroupClient added in v1.69.0 

type ReviewerGroupClient interface {
	ListReviewerGroups(ns, slug string) ([]ReviewerGroup, error)
	CreateReviewerGroup(ns, slug string, in CreateReviewerGroupInput) (ReviewerGroup, error)
	DeleteReviewerGroup(ns, slug string, id int) error
}

ReviewerGroupClient manages named reviewer-group conditions on a Bitbucket Server / Data Center repository. Cloud does not expose a compatible API, so AsReviewerGroupClient returns ErrUnsupportedOnHost for Cloud backends.

func AsReviewerGroupClient added in v1.69.0 

func AsReviewerGroupClient(c Client, host string) (ReviewerGroupClient, error)

AsReviewerGroupClient returns the ReviewerGroupClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend does not implement the capability (currently Cloud).

type RunPipelineInput 

type RunPipelineInput struct {
	Branch string
}

RunPipelineInput carries the parameters for triggering a pipeline run.

type SSHKey added in v1.51.0 

type SSHKey struct {
	ID    int    `json:"id"`
	Label string `json:"label"`
	Key   string `json:"key"`
}

SSHKey is the domain representation of a user SSH key on Bitbucket Cloud.

type SSHKeyClient added in v1.51.0 

type SSHKeyClient interface {
	ListSSHKeys() ([]SSHKey, error)
	AddSSHKey(input SSHKeyInput) (SSHKey, error)
	DeleteSSHKey(id int) error
}

SSHKeyClient is implemented by Cloud backends only. User SSH keys are a Cloud-only concept; Server/DC uses deploy keys instead.

func AsSSHKeyClient added in v1.51.0 

func AsSSHKeyClient(c Client, host string) (SSHKeyClient, error)

AsSSHKeyClient returns the SSHKeyClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not implement the SSHKeys capability.

type SSHKeyInput added in v1.51.0 

type SSHKeyInput struct {
	Label string
	Key   string
}

SSHKeyInput carries the parameters for adding a user SSH key.

type SearchSegment added in v1.21.0 

type SearchSegment struct {
	Text  string
	Match bool
}

SearchSegment is one run of text in a path or content match. Match=true marks the substring that triggered the hit so renderers can highlight it.

type ServerVersion added in v1.46.0 

type ServerVersion struct {
	Major int
	Minor int
	Patch int
	Raw   string // original string, e.g. "8.5.0"
}

ServerVersion holds a parsed Bitbucket Server version number.

func (ServerVersion) AtLeast added in v1.46.0 

func (v ServerVersion) AtLeast(major, minor int) bool

AtLeast reports whether the version is ≥ major.minor.0.

type SourceReader added in v1.22.0 

type SourceReader interface {
	GetFileContent(ns, slug, ref, path string) ([]byte, error)
	ListTree(ns, slug, ref, path string) ([]TreeEntry, error)
}

SourceReader reads file content and directory listings at a ref. Both backends implement it (Cloud via /src/{ref}/{path}, Server via /raw/{path}?at={ref} and /browse/{path}?at={ref}).

GetFileContent returns the raw bytes of a file at ref. When path resolves to a directory the backend returns a 404 (Server) or directory listing (Cloud) — adapters normalise both to ErrNotFound so the cmd layer can suggest ListTree.

ListTree returns immediate children of path at ref. path "" lists the repository root. Each entry has Type "file" or "dir" — backends with richer type vocabularies (Server's "FILE"/"DIRECTORY"/"SUBMODULE", Cloud's "commit_file"/"commit_directory") are normalised at the adapter boundary. Submodules are surfaced as Type "dir" so the renderer treats them as recursable; the Hash field carries the submodule pointer.

type SubmitReviewInline added in v1.25.0 

type SubmitReviewInline struct {
	Path      string
	Line      int
	StartLine int    // 0 = single-line
	Side      string // "new" or "old"; defaults to "new" when empty
	Body      string
}

SubmitReviewInline is one inline comment in a compound review. The shape mirrors PRCommentInline + the comment body, so the adapter can splat each entry into AddPRComment without an intermediate translation.

type SubmitReviewInput added in v1.25.0 

type SubmitReviewInput struct {
	Action string
	Body   string
	Inline []SubmitReviewInline
}

SubmitReviewInput bundles the review action, optional top-level body, and optional inline comments for a compound `pr review` call. The adapter posts the body comment first (if any), then each inline comment in order, then applies the action — so partial failures surface at the first failing step rather than corrupting the review state silently.

Action is one of:

  • "approve" — calls ApprovePR after comments
  • "request_changes" — calls RequestChangesPR (Cloud only; Server returns a typed *DomainError with Kind=ErrUnsupportedOnHost)
  • "comment" — comment-only review; no action call after the comments are posted

type SuggestionApplier added in v1.68.0 

type SuggestionApplier interface {
	// ApplySuggestion commits a suggested change to the PR source branch.
	// The adapter is responsible for fetching the current PR version for
	// optimistic locking before issuing the POST.
	ApplySuggestion(ns, slug string, prID, commentID, suggestionID int) (SuggestionApplyResult, error)

	// GetSuggestionPreview returns the suggestion body text from the comment
	// without applying the change.
	GetSuggestionPreview(ns, slug string, prID, commentID int) (string, error)
}

SuggestionApplier applies Bitbucket Data Center inline code suggestions. Bitbucket Cloud has no equivalent primitive, so callers route through AsSuggestionApplier to surface the constraint as a typed ErrUnsupportedOnHost.

func AsSuggestionApplier added in v1.68.0 

func AsSuggestionApplier(c Client, host string) (SuggestionApplier, error)

AsSuggestionApplier returns the SuggestionApplier view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) when the backend has no suggestion apply primitive (currently Bitbucket Cloud).

type SuggestionApplyResult added in v1.68.0 

type SuggestionApplyResult struct {
	CommitHash    string
	CommitMessage string
}

SuggestionApplyResult is returned when a suggested change is successfully applied.

type Tag 

type Tag struct {
	Name    string
	Hash    string
	Message string // empty for lightweight tags; first line for annotated
	WebURL  string
}

Tag is the domain representation of a repository tag.

type TagCreator 

type TagCreator interface {
	CreateTag(ns, slug string, in CreateTagInput) (Tag, error)
}

TagCreator creates a tag.

type TagDeleter 

type TagDeleter interface {
	DeleteTag(ns, slug, name string) error
}

TagDeleter deletes a tag.

type TagLister 

type TagLister interface {
	ListTags(ns, slug string, limit int) ([]Tag, error)
}

TagLister lists tags in a repository.

type TreeEntry added in v1.22.0 

type TreeEntry struct {
	Path string
	Type string
	Size int64
	Hash string
}

TreeEntry is a single child of a directory listing under a ref. Type is the normalised "file" or "dir" — adapters fold their backend-specific vocabularies (Cloud "commit_file"/"commit_directory", Server "FILE"/"DIRECTORY"/"SUBMODULE") to one of these two values. Submodules surface as "dir" with the submodule pointer in Hash so renderers treat them as recursable.

Path is the full repo-relative path (including the parent prefix), so a renderer doesn't need to know what path was requested to display the listing. Size is 0 for directories.

type UpdateIssueInput added in v1.17.0 

type UpdateIssueInput struct {
	Title    string
	Content  string
	State    string
	Kind     string
	Priority string
	Assignee string // "" = no change; AssigneeNone = clear
}

UpdateIssueInput carries the parameters for changing an issue. Empty strings mean "no change". `issue close` sets State="closed" and leaves the rest untouched. Assignee is the Bitbucket Cloud username to assign to; set to the special sentinel AssigneeNone to explicitly clear the assignee.

type UpdatePRInput 

type UpdatePRInput struct {
	Title       string // empty = no change
	Description string // empty = no change
}

UpdatePRInput carries the parameters for editing a pull request.

type User 

type User struct {
	Slug        string
	DisplayName string
}

User is the domain representation of a Bitbucket user.

type UserGetter 

type UserGetter interface {
	GetCurrentUser() (User, error)
}

UserGetter returns the currently authenticated user.

type VersionedServer added in v1.46.0 

type VersionedServer interface {
	GetServerVersion() ServerVersion
}

VersionedServer is implemented by backends that report their server version. Currently Server/DC only — Cloud has no equivalent endpoint.

func AsVersionedServer added in v1.46.0 

func AsVersionedServer(c Client, host string) (VersionedServer, error)

AsVersionedServer returns the VersionedServer accessor for c if the backend supports it, or ErrUnsupportedOnHost if not.

type Webhook added in v1.15.0 

type Webhook struct {
	ID     string
	URL    string
	Events []string
	Active bool
}

Webhook is the domain representation of a repository webhook. Both Bitbucket Cloud and Server/DC expose a similar shape — a remote URL, a list of subscribed events, and an active flag. ID is the backend's stable identifier (UUID on Cloud, integer-as-string on Server/DC).

type WebhookCreator added in v1.15.0 

type WebhookCreator interface {
	CreateWebhook(ns, slug string, in CreateWebhookInput) (Webhook, error)
}

WebhookCreator creates a webhook.

type WebhookDeleter added in v1.15.0 

type WebhookDeleter interface {
	DeleteWebhook(ns, slug, id string) error
}

WebhookDeleter deletes a webhook.

type WebhookLister added in v1.15.0 

type WebhookLister interface {
	ListWebhooks(ns, slug string) ([]Webhook, error)
}

WebhookLister lists webhooks for a repository.

type WebhookReader added in v1.15.0 

type WebhookReader interface {
	GetWebhook(ns, slug, id string) (Webhook, error)
}

WebhookReader reads a single webhook by ID.

type Workspace added in v1.17.0 

type Workspace struct {
	Slug   string
	Name   string
	UUID   string
	WebURL string
}

Workspace is a Bitbucket Cloud workspace (the top-level ownership unit containing repositories and projects). Bitbucket Server / Data Center has no analogous concept — projects sit directly under the instance — so Workspace is Cloud-only and surfaced via the WorkspaceClient optional interface.

type WorkspaceClient added in v1.17.0 

type WorkspaceClient interface {
	ListWorkspaces(limit int) ([]Workspace, error)
	ListProjects(workspace string, limit int) ([]Project, error)
}

WorkspaceClient is implemented only by Bitbucket Cloud clients. Bitbucket Server / Data Center has no workspace concept — its projects live directly under the instance — so the workspace and project list operations are Cloud-only and accessed via the AsWorkspaceClient type assertion.

func AsWorkspaceClient added in v1.17.0 

func AsWorkspaceClient(c Client, host string) (WorkspaceClient, error)

AsWorkspaceClient returns the WorkspaceClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not support workspaces.

type WorkspaceMember added in v1.62.0 

type WorkspaceMember struct {
	User      User
	Workspace string // workspace slug
}

WorkspaceMember is a member of a Bitbucket Cloud workspace.

type WorkspaceMemberClient added in v1.62.0 

type WorkspaceMemberClient interface {
	ListWorkspaceMembers(workspace string, limit int) ([]WorkspaceMember, error)
}

WorkspaceMemberClient lists members of a Bitbucket Cloud workspace. Cloud-only — Server returns ErrUnsupportedOnHost.

func AsWorkspaceMemberClient added in v1.62.0 

func AsWorkspaceMemberClient(c Client, host string) (WorkspaceMemberClient, error)

AsWorkspaceMemberClient returns the WorkspaceMemberClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if the backend at host does not support workspace members.

type WorkspaceVariableClient added in v1.31.0 

type WorkspaceVariableClient interface {
	ListWorkspaceVariables(ns string) ([]PipelineVariable, error)
	SetWorkspaceVariable(ns string, in PipelineVariableInput) (PipelineVariable, error)
	DeleteWorkspaceVariable(ns, key string) error
}

WorkspaceVariableClient is implemented by Bitbucket Cloud only.

func AsWorkspaceVariableClient added in v1.31.0 

func AsWorkspaceVariableClient(c Client, host string) (WorkspaceVariableClient, error)

AsWorkspaceVariableClient returns the WorkspaceVariableClient view of c, or a typed *DomainError (Kind=ErrUnsupportedOnHost) if not available.

type WorkspaceWebhookClient added in v1.66.0 

type WorkspaceWebhookClient interface {
	WorkspaceWebhookLister
	WorkspaceWebhookCreator
	WorkspaceWebhookDeleter
}

WorkspaceWebhookClient bundles the three workspace-webhook operations.

func AsWorkspaceWebhookClient added in v1.66.0 

func AsWorkspaceWebhookClient(c Client, host string) (WorkspaceWebhookClient, error)

AsWorkspaceWebhookClient returns the WorkspaceWebhookClient view of c, or a typed *DomainError (ErrUnsupportedOnHost) if the backend is not Cloud.

type WorkspaceWebhookCreator added in v1.66.0 

type WorkspaceWebhookCreator interface {
	CreateWorkspaceWebhook(workspace string, in CreateWebhookInput) (Webhook, error)
}

WorkspaceWebhookCreator creates a workspace-level webhook.

type WorkspaceWebhookDeleter added in v1.66.0 

type WorkspaceWebhookDeleter interface {
	DeleteWorkspaceWebhook(workspace, uuid string) error
}

WorkspaceWebhookDeleter deletes a workspace-level webhook by UUID.

type WorkspaceWebhookLister added in v1.66.0 

type WorkspaceWebhookLister interface {
	ListWorkspaceWebhooks(workspace string) ([]Webhook, error)
}

WorkspaceWebhookLister lists webhooks scoped to a workspace.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.