Skip to main content

Integration guideSeal API and Scripts

Bitbucket

Connect code reviews and testing evidence to software change records.

Illustration of a seal beside a laptop showing a data table and an evidence binder linked by a red thread.

Bitbucket to SealSeal API and Scripts

Seal reads
Pull requests, commits and pipeline results
Writes back
If agreed
Source of truth
Agreed when scoped
Set up
Scoped with your team
Neil › Software change review
draft

Connect the code change to its review and test evidence.

Neil

  • Once the connection is configured, I’ll use the records it provides and cite each one. Anything it doesn’t supply stays listed as missing.
Reads
Pull requests, commits and pipeline results
Returns
  • Change references and verification evidence
  • Missing or unmatched information
  • Next steps for your team to review
Illustrative work with Bitbucket: a request to Neil, the source it reads and the draft it returns for your review.

1What’s connected.

Link Bitbucket pull requests, commits and pipeline results to Seal change records through a connection set up with Seal’s API or Scripts. Agree which repositories, branches and review evidence each change record needs.

Connection setup and permissions

Use Seal’s APIs or scripting engine for a connection tailored to your process. Agree the data mapping, access and direction of transfer before implementation.

Related blueprints

2Link Bitbucket pull requests and builds to Seal change records.

Route

Webhooks send pullrequest:created, pullrequest:updated and pullrequest:approved, pullrequest:fulfilled for a merge and pullrequest:rejected for a decline, with the event in the X-Event-Key header.⁠¹ A commit status records a result such as a build as INPROGRESS, SUCCESSFUL or FAILED. Its key tells one system’s status from others on the commit, and its url points back to that system.⁠²¹ The REST API approves or declines a pull request and lists its commit statuses.⁠³

Merge rules

Build-based merge checks work with Bitbucket Pipelines, a Marketplace build integration or the commit status REST API.⁠⁴ Without Premium, merge checks only warn. Enforcing them, and resetting approvals when the source branch changes, needs Premium.⁠⁴

Revisions

A status created with an existing key overwrites that status, so one key per change record keeps one current answer on each commit.⁠²

When it fails

The status is on the commit but not the pull request
A commit status shows on a pull request only when its refname is the pull request’s source branch.⁠² Post the status with the source branch as its refname.
A failed check did not stop the merge
Without Premium, a merge check only warns.⁠⁴ On a plan without Premium, check the change record’s status before merging; the warning will not block it.

Check one record

Open a pull request on a test repository. The Seal change record should name the pull request and its source commit. Push a commit and confirm the pullrequest:updated event reaches the record. When the pipeline finishes, confirm the record shows its SUCCESSFUL or FAILED status for that commit.

3Start with the job.

Tell us what Neil needs to do and which records it needs. We’ll confirm the interface, permissions and implementation scope with your team.

Discuss this connection →

4Before it goes live.

Access and any write-back

Define which records are in scope and whose permissions apply. Whether the connection writes back at all is a separate decision, with its own mapping and approval.

Verification and release

Review the configured connection for its intended use. Keep the requirements, checks and evidence with the change, and approve the release through your team’s controls.

Read the assurance detail →

References

  1. 1Bitbucket Cloud: event payloads.
  2. 2Bitbucket Cloud REST API: commit statuses.
  3. 3Bitbucket Cloud REST API: pull requests.
  4. 4Bitbucket Cloud: suggest or require checks before a merge.