Bitbucket Pipelines

Atlassian container-per-step CI: bitbucket-pipelines.yml structure, caches versus artifacts, the shared per-step memory ceiling people hit, self-hosted runners, deployments, OIDC, and an honest comparison to GitHub Actions and GitLab CI.

Overview

Atlassian's CI, and the world it signals

Bitbucket Pipelines is configured by one bitbucket-pipelines.yml at the repository root and runs as a series of Docker containers. Many enterprises standardized on Atlassian (Jira, Confluence, Bitbucket), so their build systems live here rather than on GitHub or GitLab. A job description naming Bitbucket tells you which world you are entering.

Fact one: container per step

Every step gets a fresh container from a declared image, runs its script and is destroyed. Nothing persists unless declared: an artifact for handoff within a run, or a cache for reuse across runs.

The file you built vanished — Not declared as an artifact
Installing a tool in step one does not help step two — Fresh container
A cache miss is slow but never wrong — Caches are for speed only

Fact two: a shared memory budget

A step has one total allocation, 4 GB by default and doubled at 2x, shared by the script and any attached services. Services default to 1024 MB each, at most five per step.

> [!WARNING] Attach a database, a cache and the Docker service at defaults and you lose a day debugging a build container killed for lack of memory. That arithmetic is the most commonly hit real limit in the product.

The feature set

Triggers — default, branches, tags, bookmarks, pull-requests, custom
Structure — Parallel steps, stages, a cap of 100 steps per pipeline
Deployments — Attach an environment, unlock environment-scoped variables, populate a deployment tracking view
Variables — Workspace, repository and deployment scopes; override order pipeline over deployment over repository over workspace over default; secured variables masked in logs
OIDC — Keyless authentication to cloud providers
Self-hosted runners — Your own Linux, Windows or macOS hardware; their minutes are not charged

Where interviewers push: honesty about capability

Thin reuse — Pipes are the reusable-step mechanism and the catalog is small; nothing like reusable workflows or composite actions
No native matrix — Write the steps out, or generate the YAML
Build minutes — A visible cost that genuinely shapes design, especially since larger sizes consume minutes proportionally faster

> [!TIP] Treat build minutes as a legitimate engineering input, not a complaint.

Key concepts

Container per step: Every step starts a separate Docker container built from the declared image and is destroyed afterwards. Nothing carries forward implicitly. This single rule explains artifacts, caches, and why installing a tool in one step does not make it available in the next.
Pipeline types: Under pipelines you declare default, branches, tags, bookmarks, pull-requests, and custom. Only the most specific match runs. A pull-requests pipeline builds a merge of source into destination, which is why it can fail on a branch whose own build passed. Custom pipelines run only when triggered manually or on a schedule.
Artifacts: Files declared with an artifacts glob in one step and made available to subsequent steps of the same pipeline run. The mechanism for passing build output forward, and correctness-critical in a way caches are not.
Caches: Directories preserved across pipeline runs to avoid re-downloading dependencies. Nine predefined names exist including node, pip, maven, gradle, and docker; custom caches are declared under definitions with a path and an optional key based on files. Only caches under 1 GB compressed are saved, and caches older than one week are cleared automatically.
Step size and shared memory: A default step has 4 GB of memory, 4 CPUs, and 64 GB of volume disk; size 2x doubles the memory, and the allocation is shared by the script and every service on the step. Allowed sizes are 1x, 2x, 4x, 8x, 16x, 24x, and 32x, with 4x and above requiring a paid plan and consuming build minutes at the same multiple.
Runners and runs-on: Self-hosted execution agents registered to a repository or workspace and targeted with runs-on labels. A step runs on the next available runner carrying all listed labels, and fails if no online runner matches. Self-hosted runner time is not charged against build minutes.
Deployment variables: Variables scoped to a named environment and exposed only to steps carrying that deployment. Combined with the documented override order — pipeline over deployment over repository over workspace over default — this is how one pipeline definition targets staging and production with different values and no conditional logic.
Pipes: The reusable-step mechanism: a versioned Docker container invoked with a pipe property and a variables block. Functionally analogous to a GitHub Action, with a far smaller catalogue. Writing a private pipe is how you share a step across repositories in one workspace.

When to use it

The organisation is standardised on Atlassian and the code already lives in Bitbucket Cloud, where the Jira and deployment integration is the main draw
Straightforward container-based build, test, and deploy flows where the opinionated model is a feature rather than a limit
Toolchains that cannot run in a cloud image — licensed compilers, macOS signing, Windows SDKs — combined with self-hosted runners for those steps
Deployments that need an environment model with manual approval gates and a tracked history of what is where
Cloud deploys where you want OIDC federation instead of long-lived static credentials stored as repository variables

Interview questions

Explain caches versus artifacts in Bitbucket Pipelines, including the limits, and describe a bug caused by confusing them.
A step is being killed with no useful error. Walk through diagnosing it, and explain the memory model.
Design a Bitbucket pipeline for a native application that must build on Linux and Windows, sign on macOS, deploy to staging automatically, and require approval for production.
How do variables, secured variables, and OIDC work in Bitbucket Pipelines, and how do you get cloud credentials out of the repository?
Compare Bitbucket Pipelines honestly with GitHub Actions and GitLab CI. Where is it genuinely weaker?