Ellipse Gradient for Header

Integrate Bitbucket with Martini

Integrate Bitbucket Cloud with Martini to automate repository, commit, pull request, pipeline, and deployment workflows. Martini can receive Bitbucket webhooks, call the Bitbucket Cloud REST API, access Git content, transform JSON data, synchronize records on a schedule, and support Bitbucket Pipelines deployments of Martini packages.

Integration PointSupported by BitbucketCommon use casesHow Martini supports it
Reporting and analytics extractionYesBuild engineering activity reports, repository inventories, CI/CD dashboards, and deployment history. Correlate commits, pull requests, pipeline runs, and deployments in a data warehouse or release-management system.Martini can call Bitbucket Cloud REST collection endpoints, follow pagination, filter records, and map repository, commit, pull request, pipeline, and deployment data into reporting or analytical systems. Scheduled workflows can persist checkpoints to limit repeated extraction.
Bulk and batch operationsYes, through paginated REST workflowsPerform an initial repository inventory or backfill pull requests, commits, pipeline runs, and deployment records. Batch jobs should limit response size, respect request limits, and avoid repeatedly processing unchanged history.Bitbucket does not appear to provide a single vendor-wide bulk synchronization API for all resources. Martini can implement controlled batch processing with paginated REST calls, bounded concurrency, filtering, checkpoints, and retry handling.
Incremental export APIsYes, for selected resourcesSynchronize commits after a known revision, collect recent pull request or pipeline changes, and update external systems when delivery status changes. Persist the last processed commit, run, or timestamp according to the resource being synchronized.Martini can use Bitbucket filters, commit revision and include/exclude traversal, path filters where supported, pagination, and persisted checkpoints for incremental synchronization. Webhooks can provide the change signal while REST calls retrieve complete details.
WebhooksYesReact to repository pushes, pull request changes, comments, approvals, merges, commit status changes, issue events, and pipeline-related events. Use the event to trigger targeted REST retrieval instead of polling every repository.Martini can expose an HTTP endpoint for Bitbucket Cloud webhook delivery and route events into validation, transformation, orchestration, notification, or deployment workflows. Signature validation, idempotency, retries, and asynchronous processing should be included in the implementation.
REST APIsYesManage or retrieve repositories, commits, pull requests, pipelines, deployments, source files, webhooks, projects, users, and commit statuses. Apply governance rules, synchronize records, post permitted pull request actions, and correlate source changes with enterprise processes.Martini can integrate with Bitbucket Cloud REST API version 2.0 through HTTP services and JSON transformations. OAuth bearer tokens or API-token Basic Authentication can be configured with the permissions required by each operation.

Exposes data and business events

Bitbucket Webhooks

Bitbucket Cloud webhooks notify Martini when repository, pull request, commit status, issue, or pipeline-related events occur. A repository push event can initiate processing without continuously polling every repository.

How This works in Martini

Expose a Martini HTTP endpoint for the webhook, validate the configured HMAC signature against the raw request body, and acknowledge valid events quickly. The workflow can use event identifiers for deduplication, then retrieve complete commit, file, pull request, or status details through the Bitbucket REST API.

Example Martini workflow

Receive webhook
Validate signature
Deduplicate event
Retrieve details
Route workflow

Bitbucket REST APIs

Bitbucket Cloud REST APIs provide JSON resources for workspaces, repositories, commits, pull requests, pipelines, deployments, projects, source files, webhooks, and commit statuses. Martini can use these APIs to synchronize engineering and delivery data with enterprise systems.

How This works in Martini

Create Martini HTTP services for the required Bitbucket endpoints, provide OAuth or API-token credentials, and transform the JSON responses into the target application model. Follow Bitbucket's opaque next link for paginated collections and use filtering or partial responses where supported.

Example Martini workflow

Schedule trigger
Call API
Follow pagination
Map records
Persist checkpoint

Bitbucket Pipelines

Bitbucket Pipelines can build Martini packages and invoke the martini-build-pipeline-utility to upload them to a Martini instance. The pipeline can optionally poll deployment status or build a Docker image containing a Martini package.

How This works in Martini

Configure bitbucket-pipelines.yml with the Martini instance URL, access token, package directory, package selection pattern, upload mode, and deployment polling controls. Bitbucket Pipelines executes the build and utility, while Martini receives the selected packages for deployment.

Example Martini workflow

Build packages
Invoke utility
Upload packages
Poll deployment
Report result

Bitbucket Git

Git over HTTPS or SSH provides access to repository source and artifacts when a workflow needs to clone, fetch, inspect, or package files. Git credentials are a separate concern from Bitbucket REST API credentials.

How This works in Martini

Use Martini Git and workflow capabilities to access the required repository content, then apply validation, transformation, packaging, or delivery logic. Use SSH keys for non-interactive Git operations where appropriate and keep REST API authentication separately configured.

Example Martini workflow

Access repository
Fetch revisions
Inspect files
Validate package
Deliver artifact

Common Integration Patterns

Pattern 1

When to use this pattern

Use this pattern when repository changes must trigger processing quickly without polling every repository. It is suitable for source validation, package generation, release notifications, and downstream deployment workflows.

Data Flow
Bitbucket Cloud
Martini
Validation and notification systems
Example Mapping
Bitbucket FieldCanonical FieldTarget Field
workspace.uuidworkspaceIdworkspace_identifier
repository.slugrepositorySlugrepository_code
push.changes[].new.target.hashcommitHashsource_revision
push.changes[].new.namebranchNamesource_branch
Martini Implementation

Configure a Bitbucket repository webhook for repo:push and expose a Martini HTTP endpoint. Validate the X-Hub-Signature using the raw request body, deduplicate with event or request identifiers, and acknowledge valid events quickly. The workflow then extracts the repository, branch, and commit references, calls Bitbucket REST endpoints for complete commit or source details, and routes the result to validation, packaging, notification, or deployment services.

Martini features used:
  • HTTP services
  • Workflow orchestration
  • JSON transformation
  • Conditional routing
  • Asynchronous execution

Pattern 2

When to use this pattern

Use this pattern when pull requests are part of a governed delivery process. It connects code review events with enterprise approvals, compliance checks, ITSM records, and notifications.

Data Flow
Bitbucket Cloud
Martini
Approval and ITSM systems
Example Mapping
Bitbucket FieldCanonical FieldTarget Field
pullrequest.idpullRequestIdchange_request_id
pullrequest.source.branch.namesourceBranchsource_branch
pullrequest.destination.branch.namedestinationBranchtarget_branch
pullrequest.author.display_nameauthorrequestor
Martini Implementation

Subscribe Martini to pull request events and retrieve the pull request, associated commits, comments, and commit statuses through Bitbucket REST APIs. Apply business rules for required metadata, package validation, or approval state, then notify an external system or perform permitted Bitbucket actions such as posting a comment, updating a status, approving, declining, or merging. Use separate least-privilege credentials for read and write duties where appropriate.

Martini features used:
  • HTTP services
  • Workflow orchestration
  • Data mapping
  • Conditional routing
  • Authentication and authorization

Pattern 3

When to use this pattern

Use this pattern when Bitbucket is the source-control and CI/CD system for Martini packages. It provides a repeatable path from repository changes to package upload, deployment monitoring, and optional Docker image creation.

Data Flow
Bitbucket Pipelines
Martini build utility
Martini instance
Example Mapping
Bitbucket FieldCanonical FieldTarget Field
BASE_URLinstanceUrlMartini instance base URL
MARTINI_ACCESS_TOKENaccessTokenMartini deployment credential
PACKAGE_DIRpackageDirectoryPackage source directory
SUCCESS_CHECK_PACKAGE_NAMEdeploymentResultSelected package deployment status
Martini Implementation

Configure bitbucket-pipelines.yml to build Martini packages and invoke the martini-build-pipeline-utility as a Bitbucket Pipe. Store the Martini base URL and access token as secured variables, select the package directory and optional name pattern, and choose synchronous or asynchronous upload behavior. Configure timeout and delay controls when polling deployment status, and define how build, upload, HTTP 504, and deployment timeout outcomes are reported.

Martini features used:
  • Bitbucket Pipelines
  • Martini package deployment
  • CI/CD automation
  • Deployment status polling
  • Secured pipeline variables

Pattern 4

When to use this pattern

Use this pattern when downstream systems need a consolidated view of source activity and delivery status. It is appropriate for reporting, release governance, CMDB enrichment, and periodic reconciliation.

Data Flow
Bitbucket Cloud
Martini
Data warehouse or release-management system
Example Mapping
Bitbucket FieldCanonical FieldTarget Field
repository.slugrepositoryrepository_code
commit.hashrevisionsource_revision
pipeline.state.namepipelineStatusbuild_status
deployment.environment.nameenvironmentdeployment_environment
Martini Implementation

Schedule a Martini workflow to collect repository metadata, recent commits, pull request state, pipeline results, and deployment status. Follow each Bitbucket next link, apply filters, and persist the last processed commit, run, or timestamp so subsequent executions process only the required range. Transform the records into the target reporting or release model and use bounded concurrency with retry backoff for larger repository sets.

Martini features used:
  • Scheduled workflows
  • HTTP services
  • Pagination handling
  • Data mapping
  • Checkpoint persistence

How to build a Bitbucket integration in Martini

Objective

Define the integration boundary and authorization model before building Martini services. This prevents Cloud and Data Center assumptions from being mixed and establishes a least-privilege permission set.

Instructions in Martini

  • Confirm that the target is Bitbucket Cloud rather than Bitbucket Data Center.
  • Identify the repositories, workspaces, resources, and operations Martini must access.
  • Choose OAuth 2.0 for reusable user-authorized integrations or an API token for controlled service and CI/CD use.
  • Map repository, pull request, pipeline, project, and account permissions to the selected credential.

Objective

Establish reliable API access and a consistent internal data model. Include filtering and partial responses where supported to reduce unnecessary data transfer.

Instructions in Martini

  • Create Martini HTTP services for the required Bitbucket REST API endpoints.
  • Configure the selected Bitbucket credential for outbound requests.
  • Implement JSON transformations for repositories, commits, pull requests, pipelines, deployments, or source files.
  • Follow the opaque next link for every paginated collection.

Objective

Add event-driven processing for changes that should not wait for a scheduled poll. The endpoint must account for retries and ensure that duplicate deliveries do not repeat business actions.

Instructions in Martini

  • Configure repository webhooks for the required events, such as repo:push or pull request changes.
  • Expose a Martini HTTP endpoint over HTTPS.
  • Validate X-Hub-Signature against the raw request body.
  • Use X-Request-UUID, X-Hook-UUID, or another event identifier for deduplication.
  • Acknowledge valid events quickly and move extended processing into an asynchronous workflow.

Objective

Implement controlled incremental synchronization and reconciliation. Checkpoints and rate-aware execution reduce duplicate work and help the workflow operate within Bitbucket request limits.

Instructions in Martini

  • Create scheduled Martini workflows for repository, commit, pull request, pipeline, or deployment synchronization.
  • Persist the last processed revision, run, or timestamp.
  • Apply Bitbucket filters and continue pagination until no next link remains.
  • Use bounded concurrency and retry with backoff when processing multiple repositories.

Objective

Automate deployment of Martini packages from Bitbucket Pipelines. The pipeline should make package selection, upload behavior, and deployment verification explicit and keep credentials out of source control.

Instructions in Martini

  • Create or update bitbucket-pipelines.yml for the Martini package build.
  • Invoke the martini-build-pipeline-utility Bitbucket Pipe.
  • Set BASE_URL and MARTINI_ACCESS_TOKEN as secured pipeline variables.
  • Configure PACKAGE_DIR, PACKAGE_NAME_PATTERN, ASYNC_UPLOAD, and deployment polling controls as needed.
  • Define handling for build failures, upload failures, HTTP 504 responses, and deployment timeouts.

Common Data Objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
WorkspaceSynchronize organizational ownership, repository inventory, and reporting dimensions.ITSM, data warehouse, identity directoryMartini retrieves workspace metadata through paginated REST API calls and maps organizational identifiers into an internal workspace or ownership model.
RepositoryMaintain a repository catalog and connect source repositories to services, teams, or delivery records.CMDB, data warehouse, release-management systemMartini reads repository metadata, branches, source links, and related resources through REST APIs or accesses source content through Git.
CommitTrack source changes, build release notes, and trigger validation or packaging workflows.Data warehouse, release-management system, notification platformMartini retrieves commit details and changed content after a webhook or during scheduled synchronization, using revision, path, or include/exclude filters where supported.
Pull requestEnforce governance rules, coordinate approvals, and notify external stakeholders.ITSM, approval system, notification platformMartini receives pull request events, retrieves full pull request data and statuses, and can perform permitted comment, approval, decline, or merge operations.
PipelineMonitor build outcomes, correlate commits with delivery activity, and report CI/CD performance.Release-management system, reporting platform, data warehouseMartini queries pipeline runs and related statuses through the Bitbucket REST API, applying pagination and bounded concurrency for larger repository sets.
DeploymentTrack which commit or pipeline result reached an environment and report deployment health.CMDB, ITSM, release-management systemMartini retrieves deployment status and maps delivery outcomes to environments, releases, or operational records.

Authentication and security considerations

Authentication

Martini can integrate with Bitbucket Cloud through HTTP-based services using OAuth 2.0 bearer tokens or Bitbucket API tokens. OAuth is suitable for reusable, user-authorized applications, while API tokens are appropriate for controlled service and CI/CD integrations with fixed permissions.

Least-Privilege Access

Configure permissions for the specific operations Martini performs. Repository, pull request, pipeline, project, and account access are separate permission areas, and write access may need to be granted independently from read access.

  • Use repository read access for source and metadata synchronization.
  • Use pull request permissions for monitoring, comments, approvals, or merge operations.
  • Use pipeline permissions for pipeline-related automation.
  • Use repository administration permissions only when managing hooks or repository settings.

Credential Handling

Store Bitbucket credentials and Martini access tokens in protected configuration rather than embedding them in workflow logic or source files. Bitbucket app passwords should not be used for new integrations because they have been permanently removed.

Operation considerations

Cloud Scope

This integration guidance applies to Bitbucket Cloud. Bitbucket Data Center uses a separate API, authentication model, webhook configuration, and deployment model and should be implemented as a distinct integration target.

Webhook Reliability

Use HTTPS with a publicly trusted certificate and validate the HMAC signature before processing. Bitbucket can retry failed deliveries, and the X-Attempt-Number header identifies the delivery attempt. Design Martini handlers to be idempotent, use event or request identifiers for deduplication, and move longer processing into an asynchronous workflow after prompt acknowledgement.

Pagination and Limits

Most Bitbucket collections are paginated. Follow the returned opaque next link until it is absent, and use bounded concurrency, retries with backoff, and selective responses when synchronizing multiple repositories or large collections.

Pipeline Secrets

Store Martini access tokens, webhook secrets, and other credentials as secured Bitbucket Pipeline variables rather than committing them to bitbucket-pipelines.yml. Configure the Martini pipeline utility with the base URL, package directory, package selection pattern, upload mode, and deployment status polling controls.

Credential Separation

REST API credentials and Git credentials serve different purposes. Use OAuth or API tokens for Bitbucket REST requests and SSH keys or the applicable HTTPS Git credentials for non-interactive repository operations.

Why use Martini

Connect Development and Delivery Data

Martini connects Bitbucket Cloud repositories, commits, pull requests, pipelines, and deployments with enterprise applications and operational workflows. REST services, webhooks, Git access, scheduled execution, and data transformation support both event-driven and batch integration patterns.

Automate Governed Workflows

Use Martini to validate repository changes, apply pull request governance, notify approval systems, synchronize delivery records, and route pipeline or deployment outcomes. Workflows can combine Bitbucket events with API lookups, business rules, asynchronous processing, and downstream actions.

Support Maintainable CI/CD

The documented Bitbucket Pipelines pattern uses the martini-build-pipeline-utility to build and upload Martini packages, monitor deployment status, and optionally build a Docker image. Configuration keeps package selection, upload behavior, and deployment checks explicit for repeatable delivery.

Control Reliability and Security

Martini implementations can incorporate least-privilege credentials, webhook signature validation, idempotent processing, pagination, checkpointing, bounded concurrency, and retry handling. These controls help integrations remain dependable as repository and delivery volumes grow.

Frequently asked questions

Should a Martini integration use OAuth or an API token?

Use OAuth 2.0 for a reusable, user-authorized application integration. Use an API token for a controlled service or CI/CD integration with a dedicated account and fixed permissions. Do not use app passwords for new implementations because they have been permanently removed.

Can an API token read pull requests if it can read repositories?

Not necessarily. Pull request access has its own permission category. Configure the required pull request read or write permission in addition to repository access when the workflow needs to read, comment on, approve, decline, or merge pull requests.

How can Martini detect repository changes without polling?

Configure a Bitbucket repository webhook, commonly for repo:push, and expose a Martini HTTP endpoint to receive it. Martini can validate the signature, deduplicate the event, and retrieve complete commit or source details through the REST API.

How should webhook authenticity be verified?

Configure a webhook secret in Bitbucket and validate the X-Hub-Signature HMAC using the raw request body. Compare the signature using a constant-time method before processing the event.

How does Martini retrieve all commits or pull requests?

Use the relevant paginated REST endpoint and continue following the opaque next link until it is absent. Do not construct page URLs manually, particularly for iterator-based resources such as commits.

Can Martini start a Bitbucket Pipeline?

Bitbucket Pipelines is configured through repository YAML, and the exact pipeline operation and permissions should be verified for the customer's use case. In the documented Martini deployment pattern, the configured pipeline invokes the martini-build-pipeline-utility.

Can Bitbucket Pipelines deploy Martini packages?

Yes. The documented pattern uses Bitbucket Pipelines and the martini-build-pipeline-utility to build and upload Martini packages, optionally poll deployment status, and build a Docker image containing a Martini package.

Can Martini synchronize only changed files?

A push webhook identifies the repository and updated references, after which Martini can query the relevant commit or source endpoints. For larger jobs, persist the last processed commit and use supported revision, path, or include/exclude parameters rather than treating the webhook as a complete source snapshot.

Is there a Bitbucket bulk API or GraphQL API for synchronization?

The reviewed Bitbucket Cloud integration model centers on REST, Git, webhooks, and Pipelines. Use webhooks, filtered REST queries, commit traversal, and pagination for incremental synchronization rather than assuming a general bulk or GraphQL API.

Related Martini documentation

CI/CD

Git

Deployment

Automation

Version Control

Build Reliable Bitbucket Cloud Integrations

Use Martini to connect Bitbucket Cloud events, source data, pull requests, pipelines, and deployments with enterprise workflows and systems. Start with the required authentication model, webhook controls, pagination strategy, and CI/CD variables, then implement the integration as maintainable services and workflows.

EXPLORE MARTINI
BOOK A DEMO