Documentation ¶
Overview ¶
Package bitbucket provides a client for using the Bitbucket Server API v1.
Index ¶
- Constants
- func CheckResponse(resp *http.Response) error
- func ParseWebHook(eventKey string, payload []byte) (interface{}, error)
- func RequestID(r *http.Request) string
- func ValidatePayload(r *http.Request, secretToken []byte) (payload []byte, err error)
- func ValidateSignature(signature string, payload, secretToken []byte) error
- func WebHookType(r *http.Request) string
- type Branch
- type Client
- type Error
- type ErrorResponse
- type Link
- type ListOptions
- type ListRepositoriesOptions
- type ListUsersOptions
- type ListUsersPermission
- type ListUsersPermissions
- type NamelessLink
- type Project
- type PullRequest
- type PullRequestApprovedEvent
- type PullRequestBranchUpdatedEvent
- type PullRequestDeclinedEvent
- type PullRequestDeletedEvent
- type PullRequestEvent
- type PullRequestListOptions
- type PullRequestMergedEvent
- type PullRequestModifiedEvent
- type PullRequestNeedsWorkEvent
- type PullRequestOpenedEvent
- type PullRequestRef
- type PullRequestReviewerEvent
- type PullRequestReviewersUpdatedEvent
- type PullRequestTarget
- type PullRequestUnapprovedEvent
- type PullRequestUser
- type PullRequestsService
- type PushEvent
- type PushEventChange
- type RecentReposOptions
- type Ref
- type RepositoriesService
- func (s *RepositoriesService) CreateWebHooks(ctx context.Context, projectKey, repositorySlug string, hook *WebHook) (*WebHook, *Response, error)
- func (s *RepositoriesService) Get(ctx context.Context, projectKey, repositorySlug string) (*Repository, *Response, error)
- func (s *RepositoriesService) GetDefaultBranch(ctx context.Context, projectKey, repositorySlug string) (*Branch, *Response, error)
- func (s *RepositoriesService) List(ctx context.Context, opts *ListRepositoriesOptions) ([]*Repository, *Response, error)
- func (s *RepositoriesService) ListByProject(ctx context.Context, projectKey string, opts *ListOptions) ([]*Repository, *Response, error)
- func (s *RepositoriesService) ListRecent(ctx context.Context, opts *RecentReposOptions) ([]*Repository, *Response, error)
- func (s *RepositoriesService) ListWebHooks(ctx context.Context, projectKey, repositorySlug string, ...) ([]*WebHook, *Response, error)
- type Repository
- type RepositoryForkedEvent
- type RepositoryLinks
- type RepositoryModifiedEvent
- type Response
- type SelfLinks
- type Time
- type User
- type UsersService
- func (s *UsersService) Get(ctx context.Context, slug string) (*User, *Response, error)
- func (s *UsersService) List(ctx context.Context, opts *ListUsersOptions) ([]*User, *Response, error)
- func (s *UsersService) Myself(ctx context.Context) (*User, *Response, error)
- func (s *UsersService) WhoAmI(ctx context.Context) (string, *Response, error)
- type WebHook
- type WebHookConfiguration
- type WebHookListOptions
Constants ¶
const ( EventKeyRepositoryPush = "repo:refs_changed" EventKeyRepositoryModified = "repo:modified" EventKeyRepositoryForked = "repo:forked" EventKeyPullRequestOpened = "pr:opened" EventKeyPullRequestReviewersUpdated = "pr:reviewer:updated" EventKeyPullRequestModified = "pr:modified" EventKeyPullRequestBranchUpdated = "pr:from_ref_updated" EventKeyPullRequestApproved = "pr:reviewer:approved" EventKeyPullRequestUnapproved = "pr:reviewer:unapproved" EventKeyPullRequestNeedsWork = "pr:reviewer:needs_work" EventKeyPullRequestMerged = "pr:merged" EventKeyPullRequestDeclined = "pr:declined" EventKeyPullRequestDeleted = "pr:deleted" )
const ( PermissionRepoRead = "REPO_READ" PermissionRepoWrite = "REPO_WRITE" PermissionRepoAdmin = "REPO_ADMIN" )
Variables ¶
This section is empty.
Functions ¶
func CheckResponse ¶
CheckResponse checks the API response for errors, and returns them if present. A response is considered an error if it has a status code outside the 200 range.
func ParseWebHook ¶
ParseWebHook parses the event payload. An error will be returned for unrecognized event types.
Example usage:
func (s *BitbucketEventMonitor) ServeHTTP(w http.ResponseWriter, r *http.Request) { payload, err := bitbucket.ValidatePayload(r, s.webhookSecretKey) if err != nil { ... } event, err := bitbucket.ParseWebHook(bitbucket.WebHookType(r), payload) if err != nil { ... } switch event := event.(type) { case *bitbucket.RepositoryForkedEvent: processRepositoryForkedEvent(event) case *bitbucket.PullRequestModifiedEvent: processPullRequestModifiedEvent(event) ... } }
func ValidatePayload ¶
ValidatePayload validates an incoming Bitbucket Server Webhook event request and returns the (JSON) payload. The Content-Type header of the payload can be "application/json" or "application/x-www-form-urlencoded". If the Content-Type is neither then an error is returned. secretToken is the Bitbucket Server Webhook secret token. If your webhook does not contain a secret token, you can pass nil or an empty slice. This is intended for local development purposes only and all webhooks should ideally set up a secret token.
Example usage:
func (s *BitbucketEventMonitor) ServeHTTP(w http.ResponseWriter, r *http.Request) { payload, err := bitbucket.ValidatePayload(r, s.webhookSecretKey) if err != nil { ... } // Process payload... }
func ValidateSignature ¶
ValidateSignature validates the signature for the given payload. signature is the Bitbucket Server hash signature delivered in the X-Hub-Signature header. payload is the JSON payload sent by Bitbucket Server Webhooks. secretToken is the Bitbucket Server Webhook secret token.
func WebHookType ¶
WebHookType returns the event key of webhook request r.
Types ¶
type Branch ¶
type Branch struct { ID string `json:"id"` DisplayID string `json:"displayId"` Type string `json:"type"` LatestCommit string `json:"latestCommit"` LatestChangeset string `json:"latestChangeset"` IsDefault bool `json:"isDefault,omitempty"` }
todo: this could be merged with Ref, PullRequestTarget and PullRequestRef
type Client ¶
type Client struct { // User agent used when communicating with the Bitbucket Server API. UserAgent string // Services used for talking to different parts of the Bitbucket Server API. Users *UsersService Repositories *RepositoriesService PullRequests *PullRequestsService // contains filtered or unexported fields }
A Client manages communication with the Bitbucket Server API.
func NewServerClient ¶
NewServerClient returns a new Bitbucket Server API client with provided base URL. If either URL does not have the suffix "/rest/api/1.0/", it will be added automatically. If a nil httpClient is provided, a new http.Client will be used.
func (*Client) Do ¶
Do sends an API request and returns the API response. The API response is JSON decoded and stored in the value pointed to by v, or returned as an error if an API error has occurred. If v implements the io.Writer interface, the raw response body will be written to v, without attempting to first decode it.
If the context is canceled or times out, ctx.Err() will be returned.
func (*Client) NewRequest ¶
func (c *Client) NewRequest(ctx context.Context, method, urlStr string, body interface{}) (*http.Request, error)
NewRequest creates an API request. A relative URL can be provided in urlStr, in which case it is resolved relative to the baseURL of the Client. Relative URLs should always be specified without a preceding slash, otherwise the URL will be relative root of the base URL (ignoring the API suffix i.e., `/rest/api/1.0/`). If specified, the value pointed to by body is JSON encoded and included as the request body.
type Error ¶
type ErrorResponse ¶
type ErrorResponse struct { // Response is the HTTP response that caused this error Response *http.Response `json:"-"` Errors []Error `json:"errors"` }
func (*ErrorResponse) Error ¶
func (e *ErrorResponse) Error() string
type ListOptions ¶
type ListOptions struct { // Start parameter indicates which item should be used as the first item in the page of results. Start int `url:"start,omitempty"` // Limit parameter indicates how many results to return per page. Limit int `url:"limit,omitempty"` }
ListOptions specifies the optional parameters to various List methods that support pagination.
type ListRepositoriesOptions ¶
type ListRepositoriesOptions struct { // Name (optional) if specified, this will limit the resulting repository // list to ones whose name matches this parameter's value. The match will // be done case-insensitive and any leading and/or trailing whitespace // characters on the name parameter will be stripped.zxl Name string `url:"name,omitempty"` // ProjectName (optional) if specified, this will limit the resulting // repository list to ones whose project's name matches this parameter's value. // The match will be done case-insensitive and any leading and/or trailing // whitespace characters on the `projectname` parameter will be stripped. ProjectName string `url:"projectname,omitempty"` // Permission (optional) if specified, it must be a valid repository permission // level name and will limit the resulting repository list to ones that the // requesting user has the specified permission level to. If not specified, // the default implicit 'read' permission level will be assumed. The currently // supported explicit permission values are REPO_READ, REPO_WRITE and REPO_ADMIN. Permission string `url:"permission,omitempty"` // State (optional) if specified, it must be a valid repository state name // and will limit the resulting repository list to ones that are in the // specified state. The currently supported explicit state values are AVAILABLE, // INITIALISING and INITIALISATION_FAILED. State string `url:"state,omitempty"` // Visibility (optional) if specified, this will limit the resulting repository // list based on the repositories visibility. Valid values are public or private. Visibility string `url:"visibility,omitempty"` ListOptions }
todo: add the option values as consts
type ListUsersOptions ¶
type ListUsersOptions struct { // Filter return only users, whose username, name or email address contain this value. Filter string `url:"filter,omitempty"` // Group return only users who are members of the given group. Group string `url:"group,omitempty"` // Permission return users who have the specified permissions. Permission ListUsersPermissions `url:"permission,omitempty"` ListOptions }
type ListUsersPermission ¶
type ListUsersPermissions ¶
type ListUsersPermissions []ListUsersPermission
func (ListUsersPermissions) EncodeValues ¶
func (l ListUsersPermissions) EncodeValues(key string, v *url.Values) error
type NamelessLink ¶
type NamelessLink struct {
Href string `json:"href,omitempty"`
}
type Project ¶
type Project struct { Key string `json:"key,omitempty"` Id int `json:"id,omitempty"` Name string `json:"name,omitempty"` Description string `json:"description,omitempty"` Public bool `json:"public,omitempty"` Type string `json:"type,omitempty"` Owner *User `json:"owner,omitempty"` // this populated only for personal projects Links *SelfLinks `json:"links,omitempty"` }
type PullRequest ¶
type PullRequest struct { ID int `json:"id,omitempty"` Version int `json:"version,omitempty"` Title string `json:"title,omitempty"` Description string `json:"description,omitempty"` State string `json:"state,omitempty"` Open bool `json:"open,omitempty"` Closed bool `json:"closed,omitempty"` CreatedDate Time `json:"createdDate,omitempty"` UpdatedDate Time `json:"updatedDate,omitempty"` FromRef *PullRequestRef `json:"from_ref,omitempty"` ToRef *PullRequestRef `json:"toRef,omitempty"` Locked bool `json:"locked,omitempty"` Author *PullRequestUser `json:"author,omitempty"` Reviewers []*PullRequestUser `json:"reviewers,omitempty"` Participants []*PullRequestUser `json:"participants,omitempty"` Links *SelfLinks `json:"links,omitempty"` }
PullRequest represents a Bitbucket Server pull request on a repository.
type PullRequestApprovedEvent ¶
type PullRequestApprovedEvent PullRequestReviewerEvent
PullRequestApprovedEvent is triggered when a pull request is marked as approved by a reviewer. This payload has a event key of pr:reviewer:approved
type PullRequestBranchUpdatedEvent ¶
type PullRequestBranchUpdatedEvent struct { EventKey string `json:"eventKey"` Date time.Time `json:"date"` Actor *User `json:"actor"` PullRequest *PullRequest `json:"pullRequest"` PreviousFromHash string `json:"previousFromHash"` }
PullRequestBranchUpdatedEvent is triggered when the source branch (FromRef) updated. This payload has a event key of pr:from_ref_updated
type PullRequestDeclinedEvent ¶
type PullRequestDeclinedEvent PullRequestEvent
PullRequestDeclinedEvent is triggered when a user declines a pull request for a repository. This payload has a event key of pr:declined
type PullRequestDeletedEvent ¶
type PullRequestDeletedEvent PullRequestEvent
PullRequestDeletedEvent is triggered when a user deletes a pull request for a repository. This payload has a event key of pr:deleted
type PullRequestEvent ¶
type PullRequestEvent struct { EventKey string `json:"eventKey"` Date time.Time `json:"date"` Actor *User `json:"actor"` PullRequest *PullRequest `json:"pullRequest"` }
PullRequestEvent present the payload schema some general pull request events suh `PullRequestDeclinedEvent` and `PullRequestOpenedEvent`.
type PullRequestListOptions ¶
type PullRequestListOptions struct { // Direction (optional, defaults to INCOMING) the direction relative to the specified repository. // Either INCOMING or OUTGOING. Direction string `url:"direction,omitempty"` // At (optional) a fully-qualified branch ID to find pull requests to or from, // such as {@code refs/heads/master} At string `url:"at,omitempty"` // State (optional, defaults to OPEN). Supply ALL to return pull request in any state. // If a state is supplied only pull requests in the specified state will be returned. // Either OPEN, DECLINED or MERGED. State string `url:"state,omitempty"` // Order (optional, defaults to NEWEST) the order to return pull requests in, // either OLDEST (as in: "oldest first") or NEWEST. Order string `url:"order,omitempty"` // WithAttributes (optional, defaults to true) whether to return additional pull request attributes WithAttributes bool `url:"withAttributes,omitempty"` // WithProperties (optional, defaults to true) whether to return additional pull request properties WithProperties bool `url:"withProperties,omitempty"` ListOptions }
PullRequestListOptions specifies the optional parameters to the PullRequestsService.List method.
type PullRequestMergedEvent ¶
type PullRequestMergedEvent PullRequestEvent
PullRequestMergedEvent is triggered when a user merges a pull request for a repository. This payload has a event key of pr:merged
Doc: https://confluence.atlassian.com/bitbucketserver070/event-payload-996644369.html#Eventpayload-Merged
type PullRequestModifiedEvent ¶
type PullRequestModifiedEvent struct { EventKey string `json:"eventKey"` Date time.Time `json:"date"` Actor *User `json:"actor"` PullRequest *PullRequest `json:"pullRequest"` PreviousTitle string `json:"previousTitle"` PreviousDescription string `json:"previousDescription"` PreviousTarget *PullRequestTarget `json:"previousTarget"` }
PullRequestModifiedEvent is triggered when a pull request's description, title, or target branch is changed. This payload has a event key of pr:modified
type PullRequestNeedsWorkEvent ¶
type PullRequestNeedsWorkEvent PullRequestReviewerEvent
PullRequestNeedsWorkEvent is triggered when a pull request is marked as needs work by a reviewer. This payload has a event key of pr:reviewer:needs_work
type PullRequestOpenedEvent ¶
type PullRequestOpenedEvent PullRequestEvent
PullRequestOpenedEvent is triggered when a pull request is opened or reopened. This payload has a event key of pr:opened
Doc: https://confluence.atlassian.com/bitbucketserver070/event-payload-996644369.html#Eventpayload-Opened
type PullRequestRef ¶
type PullRequestRef struct { ID string `json:"id,omitempty"` DisplayId string `json:"displayId,omitempty"` LatestCommit string `json:"latestCommit,omitempty"` Repository *Repository `json:"repository,omitempty"` }
type PullRequestReviewerEvent ¶
type PullRequestReviewerEvent struct { EventKey string `json:"eventKey"` Date time.Time `json:"date"` Actor *User `json:"actor"` PullRequest *PullRequest `json:"pullRequest"` Participant *PullRequestUser `json:"participant"` PreviousStatus string `json:"previousStatus"` }
PullRequestReviewerEvent present the payload schema for events related to pull request review suh `PullRequestNeedsWorkEvent` and `PullRequestApprovedEvent`.
type PullRequestReviewersUpdatedEvent ¶
type PullRequestReviewersUpdatedEvent struct { EventKey string `json:"eventKey"` Date string `json:"date"` Actor *User `json:"actor"` PullRequest *PullRequest `json:"pullRequest"` AddedReviewers []*User `json:"addedReviewers"` RemovedReviewers []*User `json:"removedReviewers"` }
PullRequestReviewersUpdatedEvent is triggered when a pull request's reviewers have been added or removed. This payload has a event key of pr:reviewer:updated
type PullRequestTarget ¶
type PullRequestUnapprovedEvent ¶
type PullRequestUnapprovedEvent PullRequestReviewerEvent
PullRequestUnapprovedEvent is triggered when a pull request is unapproved by a reviewer. This payload has a event key of pr:reviewer:unapproved
type PullRequestUser ¶
type PullRequestsService ¶
type PullRequestsService service
PullRequestsService handles communication with the pull request related methods of the Bitbucket Server API.
Bitbucket Server API doc: https://docs.atlassian.com/bitbucket-server/rest/7.0.1/bitbucket-rest.html#idp280
func (*PullRequestsService) Get ¶
func (s *PullRequestsService) Get(ctx context.Context, projectKey, repo string, id int) (*PullRequest, *Response, error)
Get retrieves a single pull request.
Bitbucket Server API doc: https://docs.atlassian.com/bitbucket-server/rest/7.0.1/bitbucket-rest.html#idp284
func (*PullRequestsService) List ¶
func (s *PullRequestsService) List(ctx context.Context, projectKey, repo string, opts *PullRequestListOptions) ([]*PullRequest, *Response, error)
List retrieves a page of pull requests to or from the specified repository.
Bitbucket Server API doc: https://docs.atlassian.com/bitbucket-server/rest/7.0.1/bitbucket-rest.html#idp281
type PushEvent ¶
type PushEvent struct { EventKey string `json:"eventKey"` Date time.Time `json:"date"` Actor *User `json:"actor"` Repository *Repository `json:"repository"` Changes []PushEventChange `json:"changes"` }
PushEvent is triggered when a user pushes one or more commits, branch created or deleted, or tag created or deleted. This payload has a event key of repo:refs_changed
Doc: https://confluence.atlassian.com/bitbucketserver070/event-payload-996644369.html#Eventpayload-Push
type PushEventChange ¶
type RecentReposOptions ¶
type RecentReposOptions struct { // Permission (optional) if specified, it must be a valid repository permission // level name and will limit the resulting repository list to ones that the // requesting user has the specified permission level to. If not specified, // the default REPO_READ permission level will be assumed. Permission string `url:"permission,omitempty"` ListOptions }
type RepositoriesService ¶
type RepositoriesService service
RepositoriesService handles communication with the repository related methods of the Bitbucket Server API.
Bitbucket Server API doc: https://docs.atlassian.com/bitbucket-server/rest/7.0.1/bitbucket-rest.html#idp167
func (*RepositoriesService) CreateWebHooks ¶
func (*RepositoriesService) Get ¶
func (s *RepositoriesService) Get(ctx context.Context, projectKey, repositorySlug string) (*Repository, *Response, error)
Get fetches a repository.
Bitbucket Server API doc: https://docs.atlassian.com/bitbucket-server/rest/7.0.1/bitbucket-rest.html#idp172
func (*RepositoriesService) GetDefaultBranch ¶
func (s *RepositoriesService) GetDefaultBranch(ctx context.Context, projectKey, repositorySlug string) (*Branch, *Response, error)
GetDefaultBranch returns the default branch of the repository.
Bitbucket Server API doc: https://docs.atlassian.com/bitbucket-server/rest/7.0.1/bitbucket-rest.html#idp204
func (*RepositoriesService) List ¶
func (s *RepositoriesService) List(ctx context.Context, opts *ListRepositoriesOptions) ([]*Repository, *Response, error)
List retrieves a page of repositories based on the options that control the search.
Bitbucket Server API doc: https://docs.atlassian.com/bitbucket-server/rest/7.0.1/bitbucket-rest.html#idp393
func (*RepositoriesService) ListByProject ¶
func (s *RepositoriesService) ListByProject(ctx context.Context, projectKey string, opts *ListOptions) ([]*Repository, *Response, error)
ListByProject the repositories for a project. To list personal repositories, projectKey should be ~ then user slug (e.g., ~suhaib).
Bitbucket Server API doc: https://docs.atlassian.com/bitbucket-server/rest/7.0.1/bitbucket-rest.html#idp169
func (*RepositoriesService) ListRecent ¶
func (s *RepositoriesService) ListRecent(ctx context.Context, opts *RecentReposOptions) ([]*Repository, *Response, error)
ListRecent retrieves a page of recently accessed repositories for the currently authenticated user.
Bitbucket Server API doc: https://docs.atlassian.com/bitbucket-server/rest/7.0.1/bitbucket-rest.html#idp140
func (*RepositoriesService) ListWebHooks ¶
func (s *RepositoriesService) ListWebHooks(ctx context.Context, projectKey, repositorySlug string, opts *WebHookListOptions) ([]*WebHook, *Response, error)
ListWebHooks finds web hooks in a repository.
Bitbucket Server API doc: https://docs.atlassian.com/bitbucket-server/rest/7.0.1/bitbucket-rest.html#idp365
type Repository ¶
type Repository struct { Slug string `json:"slug,omitempty"` Id int `json:"id,omitempty"` Name string `json:"name,omitempty"` Description string `json:"description,omitempty"` HierarchyId string `json:"hierarchyId,omitempty"` ScmId string `json:"scmId,omitempty"` State string `json:"state,omitempty"` StatusMessage string `json:"statusMessage,omitempty"` Forkable bool `json:"forkable,omitempty"` Origin *Repository `json:"origin,omitempty"` // this populated only for forked repositories Project *Project `json:"project,omitempty"` Public bool `json:"public,omitempty"` Links *RepositoryLinks `json:"links,omitempty"` }
Repository represents a Bitbucket Server repository.
func (*Repository) String ¶
func (r *Repository) String() string
type RepositoryForkedEvent ¶
type RepositoryForkedEvent struct { EventKey string `json:"eventKey"` Date string `json:"date"` Actor *User `json:"actor"` Repository *Repository `json:"repository"` }
RepositoryModifiedEvent is triggered when a repository is forked. This payload has a event key of repo:forked
Doc: https://confluence.atlassian.com/bitbucketserver070/event-payload-996644369.html#Eventpayload-Fork
type RepositoryLinks ¶
type RepositoryLinks struct { Self []NamelessLink `json:"self,omitempty"` Clone []Link `json:"clone,omitempty"` }
type RepositoryModifiedEvent ¶
type RepositoryModifiedEvent struct { EventKey string `json:"eventKey"` Date string `json:"date"` Actor *User `json:"actor"` Old *Repository `json:"old"` New *Repository `json:"new"` }
RepositoryModifiedEvent is triggered when a repository is renamed or moved. This payload has a event key of repo:modified
type Response ¶
Response represents Bitbucket Server API response. It wraps http.Response returned from API and provides information about paging.
type SelfLinks ¶
type SelfLinks struct {
Self []NamelessLink
}
type User ¶
type User struct { Name string `json:"name,omitempty"` EmailAddress string `json:"emailAddress,omitempty"` Id int `json:"id,omitempty"` DisplayName string `json:"displayName,omitempty"` Active bool `json:"active,omitempty"` Slug string `json:"slug,omitempty"` Type string `json:"type,omitempty"` Links *SelfLinks `json:"links,omitempty"` }
type UsersService ¶
type UsersService service
UsersService handles communication with the user related methods of the Bitbucket Server API.
Bitbucket Server API doc: https://docs.atlassian.com/bitbucket-server/rest/7.0.1/bitbucket-rest.html#idp400
func (*UsersService) Get ¶
Get retrieves the user matching the supplied userSlug.
Bitbucket Server API doc: https://docs.atlassian.com/bitbucket-server/rest/7.0.1/bitbucket-rest.html#idp406
func (*UsersService) List ¶
func (s *UsersService) List(ctx context.Context, opts *ListUsersOptions) ([]*User, *Response, error)
List retrieves a page of users, optionally run through provided filters.
Bitbucket Server API doc: https://docs.atlassian.com/bitbucket-server/rest/7.0.1/bitbucket-rest.html#idp401
type WebHook ¶
type WebHook struct { ID int `json:"id,omitempty"` Name string `json:"name,omitempty"` CreatedDate Time `json:"createdDate,omitempty"` UpdatedDate Time `json:"updatedDate,omitempty"` Events []string `json:"events,omitempty"` Configuration WebHookConfiguration `json:"configuration,omitempty"` Url string `json:"url,omitempty"` Active bool `json:"active,omitempty"` }
type WebHookConfiguration ¶
type WebHookConfiguration struct {
Secret string `json:"secret,omitempty"`
}