Ellipse Gradient for Header

Bitbucket Integration Guide

Connect Bitbucket Cloud repositories, pull requests, pipelines, and webhook events with enterprise systems through REST APIs and Martini workflows.

Bitbucket integration options at a glance

Bitbucket Cloud provides a versioned REST API for workspaces, projects, repositories, commits, pull requests, pipelines, permissions, deployments, and webhooks. Selected repository and workspace events can be delivered through webhooks, while collection endpoints support paginated retrieval for scheduled synchronization. Repository source endpoints support reading and updating files through commit operations, subject to branch and repository permissions. Martini can consume these APIs, receive webhook requests, map Bitbucket JSON into canonical models, orchestrate incremental or scheduled workflows, and expose governed APIs for internal consumers. OAuth 2.0, API tokens, and scoped token access can be stored securely for environment-specific integrations.

Integration pointSupported by Bitbucket?Common use casesHow Martini supports it
REST APIsYesBitbucket Cloud exposes workspaces, projects, repositories, commits, pull requests, pipelines, deployments, permissions, webhooks, source, and related resources through its versioned REST API.Martini can consume REST endpoints from workflows, map Bitbucket JSON, apply business rules, and expose a controlled Martini API abstraction.
Webhooks and outbound callbacksYesRepository and workspace webhooks provide selected push, pull request, pipeline, fork, and deployment-related events. Coverage is event-specific rather than universal.Martini can receive webhook requests through an API or webhook-consuming workflow, validate the request, route the event, and retrieve additional resource data.
Bulk, asynchronous, and batch APIsLimitedCollection endpoints support pagination, and pipeline or deployment operations can execute asynchronously. A general-purpose bulk API for arbitrary updates was not confirmed.Martini can orchestrate paginated and asynchronous workflows with checkpoints, controlled concurrency, polling, and retry logic.
File and source APIsLimitedBitbucket source resources can read files and directories at branches, tags, or commits and can support file updates through repository commit operations.Martini can retrieve or write selected repository files, transform content, and coordinate commit operations while handling branch conflicts and permissions.
AuthenticationYesBitbucket Cloud supports OAuth 2.0, API tokens with Basic Authentication, and scoped repository, project, or workspace access tokens. Effective access depends on scopes and permissions.Martini can store credentials securely, configure authenticated REST consumption, and separate access by environment and integration purpose.
Scheduled synchronizationYesScheduled jobs can reconcile repositories, pull requests, commits, pipelines, users, and permissions where webhook coverage is incomplete or recovery is required.Martini scheduler-triggered workflows can paginate through resources, persist checkpoints, perform idempotent upserts, and handle rate limits.
SDKs and client librariesLimitedCommunity and language-specific clients exist, but Bitbucket REST calls do not require an SDK. Specialized client behavior may require custom logic.Martini can call REST endpoints directly and can use JVM-compatible custom logic when specialized request or payload processing is needed.
GraphQL APIsNot confirmedNo current official Bitbucket Cloud GraphQL API was confirmed in the reviewed documentation.Martini can use the confirmed Bitbucket REST API instead of assuming GraphQL support.
SOAP APIsNot confirmedNo Bitbucket Cloud SOAP API was confirmed.Martini can integrate through Bitbucket REST APIs and webhooks rather than SOAP.

How Bitbucket exposes data and business events

Bitbucket REST APIs

Bitbucket Cloud’s versioned REST API is the primary interface for workspaces, projects, repositories, source, commits, pull requests, pipelines, deployments, permissions, and webhook configuration. Collection responses commonly require pagination.

Martini implementation pattern

Martini implementation pattern: a workflow authenticates to the selected Bitbucket API, retrieves the required resource or collection, follows pagination links, maps the response into a canonical model, applies business rules, and writes to downstream systems or returns a controlled API response.

Implementation sequence

Authenticate with an OAuth token or scoped API token
Call the required Bitbucket REST resource
Follow pagination links and persist synchronization progress
Map Bitbucket JSON into the target model
Apply validation, routing, and business rules
Write the result and record the checkpoint

Bitbucket Webhooks

Bitbucket Cloud supports repository and workspace webhooks for selected push, pull request, pipeline, fork, and deployment-related events. Webhook coverage depends on the configured event type and permissions.

Martini implementation pattern

Martini implementation pattern: expose an authenticated Martini API or webhook workflow, validate the incoming request and event type, use identifiers from the payload to retrieve authoritative Bitbucket data, then route the normalized event to downstream applications.

Implementation sequence

Receive the Bitbucket webhook request
Validate authentication and the event type
Check the event key for duplicate or replayed delivery
Retrieve current repository or pull request details when required
Apply routing and governance rules
Send the normalized event to downstream systems

Bitbucket Source APIs

Bitbucket source resources support reading files and directory contents at branches, tags, or commits and can support file updates through repository commit operations. This is not a universal attachment service.

Martini implementation pattern

Martini implementation pattern: a workflow retrieves only the required source paths, transforms JSON, YAML, XML, or text content, and either delivers it to another system or prepares a controlled commit operation with branch and concurrency checks.

Implementation sequence

Identify the repository, reference, and source path
Retrieve the selected file or directory through the source API
Validate encoding and expected content type
Transform the content into the target representation
Check branch and commit state before an update
Create the commit or deliver the transformed file

Bitbucket Pipeline Events and Status

Pipeline-related events may be delivered through supported webhook configurations, and pipeline execution state can also be retrieved through REST APIs. Pipeline operations may be asynchronous rather than bulk operations.

Martini implementation pattern

Martini implementation pattern: receive a pipeline event or schedule a status check, correlate the execution with its repository and commit, normalize the result, and notify or update operational systems while polling only when necessary.

Implementation sequence

Receive a pipeline event or start a scheduled status check
Retrieve the current pipeline execution state
Correlate the execution with repository and commit identifiers
Apply success, failure, and timeout rules
Update the target deployment or incident record
Retry transient failures and record the final outcome

Common Bitbucket integration patterns

Pattern 1: Govern pull request changes

When to use this pattern

Use this pattern when pull request activity must be connected to approvals, change records, notifications, or development governance. Webhooks provide near-real-time initiation for supported pull request events, while REST retrieval supplies authoritative details.

Integration direction
Bitbucket
Martini
Jira
ServiceNow
Example Mapping
Bitbucket FieldCanonical FieldTarget Field
pullrequest.idchangeRequest.externalIdServiceNow Change Request number
pullrequest.statereview.statusJira development status
repository.full_namerepository.namechangeRequest.configurationItem
commit.hashsource.commitIddeployment.sourceRevision
Martini implementation pattern

Martini receives the pull request webhook, validates the event, retrieves the pull request, repository, commit, and reviewer details, then applies rules for required reviewers or linked change records. It upserts downstream objects using a composite correlation key and routes authorization, validation, rate-limit, and duplicate-event failures for retry or review.

Martini capabilities used
  • workflows
  • API consumption
  • webhook handling
  • data mapping
  • business rules
  • idempotent processing
  • error handling

Pattern 2: Synchronize repositories and projects

When to use this pattern

Use this pattern for scheduled inventory, governance, directory, or reporting synchronization across Bitbucket workspaces, projects, repositories, users, and permissions.

Integration direction
Bitbucket
Martini
Database
Example Mapping
Bitbucket FieldCanonical FieldTarget Field
workspace.uuidorganization.externalIdworkspace_external_id
project.keygroup.codeproject_code
repository.uuidsourceRepository.externalIdrepository_external_id
repository.is_privatesecurity.privateis_private
Martini implementation pattern

A scheduled Martini workflow enumerates resources through paginated REST calls, stores a durable checkpoint, normalizes identifiers and ownership, and performs idempotent database upserts. It handles 429 responses with bounded backoff, avoids unstable page-only checkpoints, and supports reconciliation when resources change during a run.

Martini capabilities used
  • scheduled workflows
  • API consumption
  • pagination orchestration
  • data mapping
  • database integration
  • checkpointing
  • retry handling

Pattern 3: Propagate pipeline status

When to use this pattern

Use this pattern when CI/CD execution results must update deployment records, incidents, notifications, or internal status APIs. Webhooks can reduce latency, while polling supports reconciliation and missed-event recovery.

Integration direction
Bitbucket
Martini
ServiceNow
Slack
Example Mapping
Bitbucket FieldCanonical FieldTarget Field
pipeline.uuiddeployment.executionIdServiceNow deployment external ID
pipeline.state.namedeployment.statusdeployment status
repository.full_namedeployment.repositoryServiceNow source repository
commit.hashdeployment.revisionSlack notification context
Martini implementation pattern

Martini receives a pipeline event or invokes a scheduled status workflow, retrieves the current execution, correlates it with the repository and commit, and applies success, failure, timeout, and notification rules. Downstream updates use idempotent keys, while temporary failures are retried and permanent validation errors are recorded for investigation.

Martini capabilities used
  • event-driven workflows
  • scheduled workflows
  • API consumption
  • data transformation
  • conditional routing
  • notifications
  • error handling

Pattern 4: Synchronize repository configuration files

When to use this pattern

Use this pattern when selected repository files must be consumed by enterprise applications or generated and committed back to Bitbucket under controlled branch governance.

Integration direction
Bitbucket
Martini
Database
Example Mapping
Bitbucket FieldCanonical FieldTarget Field
pathconfiguration.filePathfile_path
commit.hashconfiguration.sourceRevisionsource_revision
file.contentconfiguration.documentconfiguration_payload
branch.nameconfiguration.branchbranch_name
Martini implementation pattern

Martini retrieves targeted source files at a known reference, validates and transforms their content, and writes the result to a database or other API. For reverse synchronization, the workflow checks the expected branch state before creating a commit, applies repository permission and branch-protection rules, and routes conflicts for retry or manual resolution.

Martini capabilities used
  • workflows
  • API consumption
  • file processing
  • JSON handling
  • XML handling
  • data mapping
  • validation
  • business rules

Applications commonly integrated with Bitbucket

Bitbucket Cloud can participate in broader development, change-management, communication, and DevSecOps workflows. Martini can coordinate Bitbucket APIs and webhook events with the following named applications, subject to each target product’s API and authentication model.

Application Scenario Direction Martini Pattern
Jira Associate pull requests, commits, branches, and pipeline activity with Jira issues and development workflows. Bitbucket → Martini → Jira Receive Bitbucket pull request or push events, retrieve related repository and commit details, map development activity to Jira issue fields, and upsert links or status updates while handling duplicate events and API failures.
Confluence Publish release notes, build status, repository documentation, or deployment information to team knowledge spaces. Bitbucket → Martini → Confluence Use a scheduled or event-driven workflow to collect repository and pipeline information, transform it into the target page model, and call Confluence APIs with controlled updates and retry handling.
ServiceNow Connect pull request and pipeline activity to change requests, incidents, approvals, or deployment records. Bitbucket → Martini → ServiceNow Receive Bitbucket events or poll pipeline state, apply change-management rules, map deployment details into ServiceNow objects, and maintain idempotent updates with error routing.
Slack Notify development and operations channels about pull requests, failed pipelines, approvals, and deployments. Bitbucket → Martini → Slack Receive selected Bitbucket webhook events, normalize the event content, apply channel-routing rules, and call Slack APIs with deduplication and bounded retries.
Jenkins Coordinate builds and exchange build status with Bitbucket repositories and pull requests. Bitbucket → Martini → Jenkins Orchestrate calls between Bitbucket and Jenkins APIs, pass repository and commit references to build workflows, and publish resulting status back to downstream systems or Bitbucket-related processes.
Snyk Initiate or coordinate repository security scans and route findings into engineering workflows. Bitbucket → Martini → Snyk Trigger or schedule repository scan requests, map findings and commit references into a normalized security model, and route actionable results to engineering or governance systems.
SonarQube Run code-quality analysis and associate quality results with commits or pull requests. Bitbucket → Martini → SonarQube Pass repository and commit context to SonarQube, retrieve analysis results, apply quality-gate rules, and synchronize outcomes with development workflows using retries and correlation identifiers.

How to build a Bitbucket integration in Martini

Objective

Establish environment-specific access to Bitbucket Cloud using a supported authentication method and the least practical scopes and permissions.

Instructions in Martini

  • Configure OAuth 2.0, an API token, or a scoped repository, project, or workspace token.
  • Store client secrets, tokens, and webhook credentials in Martini secure configuration.
  • Separate credentials and resource permissions by environment and integration purpose.

Objective

Select an event-driven or scheduled initiation model based on Bitbucket’s event coverage and the synchronization requirement.

Instructions in Martini

  • Use a Martini API or webhook workflow for supported push, pull request, pipeline, or deployment events.
  • Use a scheduler-triggered workflow for reconciliation, pagination-heavy synchronization, and missed-event recovery.
  • Avoid polling when an appropriate Bitbucket webhook event is available.

Objective

Obtain the authoritative Bitbucket resource data needed by the integration rather than relying only on a compact event payload.

Instructions in Martini

  • Call the relevant REST endpoint for the workspace, project, repository, commit, pull request, pipeline, or source file.
  • Follow pagination links for collection responses.
  • Persist a checkpoint or correlation identifier for long-running or incremental jobs.

Objective

Coordinate Bitbucket calls, target-system calls, validation, branching, and asynchronous processing in a maintainable Martini workflow.

Instructions in Martini

  • Separate event receipt from resource enrichment where useful.
  • Apply conditional routing for event types, repository scope, pipeline outcomes, or governance requirements.
  • Use reusable workflow logic for common authentication, mapping, and error paths.

Objective

Convert Bitbucket JSON and source content into canonical and target-specific models without coupling downstream systems to every payload variation.

Instructions in Martini

  • Map stable Bitbucket identifiers, repository names, commit hashes, states, and timestamps.
  • Handle optional and event-specific nested fields defensively.
  • Transform JSON, YAML, XML, or text content only where the target contract requires it.

Objective

Enforce enterprise governance such as required reviewers, permitted branches, quality gates, notification routing, or change-management conditions.

Instructions in Martini

  • Validate required repository, project, commit, and pull request values.
  • Apply rules for approval state, pipeline outcome, branch protection, and target ownership.
  • Reject unsupported event types or incomplete payloads with traceable errors.

Common Bitbucket data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
WorkspacesRepresent organizational containers for repositories, projects, users, and permissions.Jira, ServiceNow, enterprise directories, reporting databasesMartini retrieves workspace data through paginated REST calls, normalizes identifiers and permissions, and performs checkpointed upserts.
ProjectsGroup repositories within a workspace and provide a project-level permission boundary.Jira, ServiceNow, asset inventories, governance platformsMartini maps project ownership and access metadata, correlates projects with downstream records, and handles missing or changed permissions.
RepositoriesIdentify Git source locations and their branches, tags, commits, pull requests, pipelines, and configuration files.Jira, Confluence, Jenkins, Snyk, SonarQube, asset inventoriesMartini synchronizes repositories incrementally or on a schedule, using stable identifiers, pagination, and idempotent writes.
CommitsRepresent version-control changes that can be queried, compared, and associated with branches or pull requests.Jira, Jenkins, SonarQube, Snyk, deployment systemsMartini uses commit hashes and repository context as correlation keys, retrieves required details, and avoids reprocessing completed events.
Pull requestsManage proposed repository changes, reviewers, approvals, comments, statuses, and merge state.Jira, ServiceNow, Slack, change-management applicationsMartini receives selected pull request events, retrieves authoritative resource data, applies governance rules, and routes status changes.
PipelinesRepresent CI/CD definitions and executions associated with repositories.ServiceNow, Slack, Jenkins, deployment and incident platformsMartini receives or polls pipeline status, maps execution results, applies notification or incident rules, and retries transient API failures.

Authentication and security considerations

Authentication options

Bitbucket Cloud supports OAuth 2.0, API tokens with Basic Authentication, and scoped repository, project, or workspace access tokens. Effective access depends on both the granted scopes and the user or resource permissions.

Credential protection

Martini should store OAuth client secrets, API tokens, and webhook-related credentials in secure configuration or secrets management rather than embedding them in workflows, mappings, or payloads.

Least privilege

  • Use read-only access for repository and project synchronization where possible.
  • Grant write or administration permissions only to workflows that create commits, manage pull requests, or configure webhooks.
  • Separate credentials by environment and integration purpose.
  • Protect exposed Martini APIs with appropriate authentication and authorization controls.

Operational considerations for Bitbucket integrations

Rate limits and pagination

Bitbucket Cloud applies request limits and commonly paginates collection responses. Handle HTTP 429 responses with bounded exponential backoff, follow pagination links, and persist progress rather than relying on a single page number.

Events and idempotency

Webhook delivery may be repeated, delayed, incomplete, or out of order. Use event, repository, object, commit, and timestamp data to derive durable correlation keys, and prefer idempotent upserts over blind inserts.

Repository concurrency

File updates create commits and can encounter branch protection, concurrent changes, required pull requests, or merge conflicts. Check branch and commit state before writes and route conflicts for controlled retry or review.

Schema and testing

Webhook payloads and REST responses vary by event type and may contain optional nested fields. Test representative event payloads, tolerate missing fields, monitor API version changes, and avoid logging tokens or sensitive repository content.

Monitoring and recovery

Distinguish authorization failures, invalid identifiers, rate limiting, temporary service errors, validation failures, unsupported event types, and branch conflicts. Use workflow logs, correlation identifiers, retry policies, and scheduled reconciliation for recovery.

Why use Martini instead of scripts or point-to-point integrations?

Orchestrate more than API calls

Scripts can call Bitbucket endpoints, but enterprise integrations also need webhook intake, pagination, checkpoints, target-system coordination, business rules, retries, and operational visibility. Martini provides workflows and APIs for that end-to-end behavior.

Keep mappings maintainable

Martini separates Bitbucket payloads from downstream contracts through reusable mappings and transformations. This helps accommodate event-specific payloads, optional fields, canonical models, and multiple target systems without duplicating point-to-point logic.

Secure and govern access

Environment configuration, secrets management, API security, validation, and controlled API façades keep Bitbucket credentials and repository operations governed. Custom JVM-compatible logic remains available when specialized processing is required.

Support reliable operations

Martini workflows can combine event-driven processing with scheduled reconciliation, bounded retries, idempotent writes, checkpointing, and monitoring. This is better suited to rate limits, missed events, asynchronous pipeline state, and repository concurrency than isolated scripts.

Frequently asked questions

How can Bitbucket be integrated with enterprise systems?

Bitbucket Cloud can be integrated through its versioned REST API, selected repository and workspace webhooks, source and file endpoints, and scheduled paginated synchronization. OAuth 2.0, API tokens, and scoped token access control the available resources. Enterprise workflows commonly synchronize repositories, commits, pull requests, pipelines, permissions, and source files with development, change-management, communication, and DevSecOps systems.

Can Martini integrate with Bitbucket?

Yes. Martini can consume Bitbucket Cloud REST APIs, receive selected Bitbucket webhook events, retrieve authoritative resource details, transform Bitbucket data, and route it to downstream systems. No native Martini Bitbucket connector is documented in the supplied materials, so the integration is implemented through Bitbucket’s confirmed APIs, webhooks, authentication methods, and source endpoints.

Do I need a connector to integrate Bitbucket with Martini?

No. A dedicated Bitbucket connector is not required. Martini can integrate with Bitbucket Cloud using its REST APIs, selected webhook events, repository source operations, OAuth 2.0, API tokens, or scoped token mechanisms, with workflows providing orchestration, mapping, validation, retries, and error handling.

Is there any extra Lonti cost to integrate Bitbucket with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate Bitbucket with Martini. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Atlassian, cloud infrastructure providers, or other third-party systems based on subscriptions, API usage, and deployment model.

Which Bitbucket integration methods should be used?

Use the Bitbucket Cloud REST API as the primary mechanism for workspaces, projects, repositories, commits, pull requests, pipelines, permissions, source, and webhook resources. Use webhooks for supported near-real-time events, scheduled REST synchronization for reconciliation or unsupported event coverage, and source endpoints for selected repository files. A current official Bitbucket Cloud GraphQL or SOAP API was not confirmed.

Does Bitbucket provide webhooks or event notifications?

Yes, Bitbucket Cloud supports repository and workspace webhooks for selected push, pull request, pipeline, fork, and deployment-related events. Coverage is event-specific rather than universal. Martini can receive and validate these events, deduplicate or correlate them, retrieve additional Bitbucket data, and route normalized results to downstream applications.

How should Bitbucket synchronization handle pagination and duplicates?

Collection endpoints should be processed through their documented pagination links or parameters, with durable checkpoints for long-running jobs. Webhook retries or repeated scheduled runs should be handled with stable event, commit, repository, or object identifiers and idempotent upserts. Martini can combine incremental event processing with scheduled reconciliation to recover from missed or out-of-order events.

Can Martini expose an API façade for Bitbucket?

Yes. Martini can expose a controlled REST API that abstracts selected Bitbucket operations for internal consumers. Workflows behind the API can enforce authorization, validate inputs, apply repository or project rules, call Bitbucket REST resources, transform responses, and standardize errors without exposing Bitbucket credentials or resource details directly.

Related Martini documentation

APIs

Workflows

Data

Security

Operations

Connect Bitbucket with your enterprise systems

Use Martini to orchestrate Bitbucket Cloud APIs, selected webhook events, repository source operations, and downstream business workflows in a secure, maintainable integration architecture.

EXPLORE MARTINI
BOOK A DEMO