Bitbucket Server Docker image tag and Java version compatibility

Recommended image pin

Pin your CI pipeline to a patch-level tag such as atlassian/bitbucket:8.13.1 rather than atlassian/bitbucket:latest. Bitbucket Server 8.x and later require Java 11, while 5.x through 7.x require Java 8. A patch-level tag freezes the Java baseline and REST API surface, keeping webhook payloads and branch-permission behavior stable until you intentionally change the tag.

Established behavior vs. likely explanation

Established behavior

• Official images follow atlassian/bitbucket:.
• Java 8 ships with 5.x–7.x; Java 11 ships with 8.x and later.
• latest is a rolling tag and can move to a newer patch or major release without notice.
• Branch permissions introduced in Bitbucket Server 8.0 are not backward-compatible with custom ACL plugins built for 7.x.
• Git push webhook payloads differ between Bitbucket Cloud and Bitbucket Server 8.5.

Likely explanation

CI instability usually comes from allowing latest to pull a new image mid-pipeline or across runs. That changes the Java runtime, webhook schema, and permission API without a version change in your configuration.

Steps for this case

1. Select the Bitbucket Server major version your CI integration targets (for example, 8.x for Java 11).
2. Pin the pipeline image to an exact patch tag, for example atlassian/bitbucket:8.13.1. Confirm the tag exists in your registry before deploying.
3. Remove latest from all CI image definitions.
4. Test webhook consumers and branch-permission calls against the pinned container before promoting to production.

Verification

docker pull atlassian/bitbucket:8.13.1
docker run --rm atlassian/bitbucket:8.13.1 java -version

The Java command should report Java 11. After starting the container, capture a test push webhook payload and inspect it with jq, then compare the JSON structure to the documented Bitbucket Server 8.5 schema. You can also query GET /rest/branch-permissions/1.0/... to confirm the 8.x permission response structure.

Assumptions and uncertainty

• The tag 8.13.1 is an example; verify it is still published and not end-of-support.
• The bundled Java runtime is determined by the Bitbucket Server release and is not configurable inside the image.
• Custom plugins built for 7.x will not load on an 8.x image; remediate those plugins before upgrading major versions.
• Behavior of latest may change over time; treat it as unsuitable for production CI pinning.

No missing diagnostic detail changes the pinning recommendation. If you are migrating from 7.x with custom branch-permission plugins, confirm plugin compatibility with the target 8.x image before upgrading.