bitbucketapp

Documentation

Overview

Package bitbucketapp implements OAuth2 and the small slice of Bitbucket Cloud's REST API this control plane needs once connected.

Bitbucket Cloud only: no instance URL parameter anywhere in this package, unlike internal/gitlabapp. Bitbucket Server/Data Center has no OAuth-consumer equivalent and is out of scope (docs/design/git-provider-integrations.md section 3); a Data Center repo can still be connected today through the existing generic deploy-token path (PUT /api/v1/apps/{name}/git-source).

Index

• func AuthorizeURL(clientID, redirectURI, state string) string
• type Branch
• type BuildStatusState
• type Client
  • func NewClient() *Client
  • func (c *Client) CreateCommitBuildStatus(ctx context.Context, accessToken, fullName, commit string, ...) error
  • func (c *Client) CreatePullRequestComment(ctx context.Context, accessToken, fullName string, prID int, body string) error
  • func (c *Client) CreateRepoWebhook(ctx context.Context, accessToken, fullName, hookURL, secret string) error
  • func (c *Client) ExchangeCode(ctx context.Context, key, secret, code string) (Tokens, error)
  • func (c *Client) GetRepo(ctx context.Context, accessToken, fullName string) (Repo, error)
  • func (c *Client) ListBranches(ctx context.Context, accessToken, fullName string) ([]Branch, error)
  • func (c *Client) ListRepos(ctx context.Context, accessToken string) ([]Repo, error)
  • func (c *Client) RefreshToken(ctx context.Context, key, secret, refreshToken string) (Tokens, error)
• type Repo
• type Tokens

Functions

func AuthorizeURL

func AuthorizeURL(clientID, redirectURI, state string) string

AuthorizeURL builds Bitbucket's OAuth2 authorization-code flow entry point: a real browser redirect (GET), the same "the operator's browser must navigate here itself" shape every other provider's own authorize/manifest entry point requires. No scope parameter: unlike GitLab's own AuthorizeURL, Bitbucket OAuth consumers have their permissions configured once on the consumer itself (Repositories: Read, Webhooks: Read and Write), not requested per authorization (docs/design/git-provider-integrations.md section 3).

Types

type Branch

type Branch struct {
	Name      string
	CommitSHA string
}

Branch is one branch of one repository.

type BuildStatusState

type BuildStatusState string

BuildStatusState is Bitbucket's own documented "state" enum for POST .../commit/{commit}/statuses/build.

const (
	// BuildStatusInProgress marks a build status as still in progress.
	BuildStatusInProgress BuildStatusState = "INPROGRESS"
	// BuildStatusSuccessful marks a build status as succeeded.
	BuildStatusSuccessful BuildStatusState = "SUCCESSFUL"
	// BuildStatusFailed marks a build status as failed.
	BuildStatusFailed BuildStatusState = "FAILED"
)

type Client

type Client struct {
	HTTP       *http.Client
	TokenURL   string
	APIBaseURL string
}

Client is a small, purpose-built Bitbucket Cloud REST/OAuth client, not a general-purpose Bitbucket SDK. TokenURL/APIBaseURL are overridable, the same "tests point this at an httptest.Server" pattern internal/githubapp.Client's own BaseURL field establishes: production code always leaves them empty and gets the real Bitbucket Cloud hosts.

func NewClient

func NewClient() *Client

NewClient returns a Client with a bounded per-request timeout, the same reasoning internal/githubapp.NewClient's own doc comment gives.

func (*Client) CreateCommitBuildStatus

func (c *Client) CreateCommitBuildStatus(ctx context.Context, accessToken, fullName, commit string, state BuildStatusState, targetURL, description, key string) error

CreateCommitBuildStatus sets a build status on commit of fullName ("workspace/repo_slug"), authenticated the same way CreatePullRequestComment is. key identifies this status distinctly from any other build system posting to the same commit (support.atlassian.com/bitbucket-cloud/docs/build-status-for-commits), the same role GitHub's own "context" plays; repeat calls with the same key update the existing status rather than adding a new one.

func (*Client) CreatePullRequestComment

func (c *Client) CreatePullRequestComment(ctx context.Context, accessToken, fullName string, prID int, body string) error

CreatePullRequestComment posts a new comment on pull request prID of fullName ("workspace/repo_slug"), authenticated with an OAuth access token the same way CreateRepoWebhook is.

func (*Client) CreateRepoWebhook

func (c *Client) CreateRepoWebhook(ctx context.Context, accessToken, fullName, hookURL, secret string) error

CreateRepoWebhook registers a repo:push and pullrequest:* webhook on fullName ("workspace/repo_slug") pointed at hookURL, with secret set as the value Bitbucket signs each delivery's X-Hub-Signature header with (HMAC-SHA256, the same header name GitHub uses for its own SHA-1 predecessor, see internal/api/git_webhook.go's own verification branch for the distinction). Each pull request event key must be requested explicitly: without them Bitbucket never delivers the events internal/webhook's Bitbucket pull-request parsing expects, so preview environments would silently never trigger for a connected repo.

func (*Client) ExchangeCode

func (c *Client) ExchangeCode(ctx context.Context, key, secret, code string) (Tokens, error)

ExchangeCode exchanges an OAuth authorization code for an access token.

func (*Client) GetRepo

func (c *Client) GetRepo(ctx context.Context, accessToken, fullName string) (Repo, error)

GetRepo looks up a single repository by its "workspace/repo_slug" full name.

func (*Client) ListBranches

func (c *Client) ListBranches(ctx context.Context, accessToken, fullName string) ([]Branch, error)

ListBranches lists every branch of fullName ("workspace/repo_slug"), the same cursor-pagination shape ListRepos follows.

func (*Client) ListRepos

func (c *Client) ListRepos(ctx context.Context, accessToken string) ([]Repo, error)

ListRepos lists every repository the token's account is at least a member of. Bitbucket paginates by an opaque "next" URL in the response body, not a page number the caller increments (GitHub's and GitLab's own shape): each iteration below follows that URL directly rather than constructing one, until the response omits it or listPageCap is hit.

func (*Client) RefreshToken

func (c *Client) RefreshToken(ctx context.Context, key, secret, refreshToken string) (Tokens, error)

RefreshToken exchanges a still-valid refresh token for a new access token.

type Repo

type Repo struct {
	FullName      string
	Name          string
	Private       bool
	DefaultBranch string
	CloneURL      string
	WebURL        string
}

Repo is one Bitbucket repository accessible to the connected account, the subset of Bitbucket's Repository object this control plane's repo picker and "use as source" action need. FullName ("workspace/repo_slug") is the identifier callers pass back to GetRepo/ListBranches/ CreateWebhook: Bitbucket has no separate numeric ID in the sense GitLab's Project.ID is used here.

type Tokens

type Tokens struct {
	AccessToken  string
	RefreshToken string
	ExpiresAt    time.Time
}

Tokens is ExchangeCode's and RefreshToken's shared result.