Bitbucket Pipelines reference

Bitbucket Pipelines is configured via `bitbucket-pipelines.yml` at the repository root. The file declares a global `image:`, optional `definitions:` (services and custom caches), and a `pipelines:` map keyed by trigger type — `default`, `branches`, `tags`, `pull-requests`, and `custom` (manual). Each value is a list of `step:` (or `parallel:`) entries.

There are no expressions like the other platforms — Bitbucket uses simple shell-style `$VAR` interpolation. Built-in caches include `node`, `pip`, `composer`, `gradle`, `maven`, `bundler`, `dotnetcore`, `sbt`, `ivy2`, `ruby`. Pipes (`pipe: org/name:version`) are reusable Docker-based steps with a YAML wrapper.

Top-level keys

Key	Purpose
image	Global default Docker image.
clone	Git clone configuration (depth, lfs).
definitions.services	Sidecar service containers usable from steps.
definitions.caches	Custom cache name → path mapping.
pipelines.default	Steps that run on every push.
pipelines.branches.<glob>	Steps that run on push to matching branches.
pipelines.tags.<glob>	Steps that run on push of a matching tag.
pipelines.pull-requests.<glob>	Steps that run on PRs targeting matching branches.
pipelines.custom.<name>	Manually-triggered named pipeline.
step.image	Override image for this step.
step.script	List of commands to run.
step.caches	List of cache names to restore + save.
step.artifacts	List of glob paths to persist for downstream steps.
step.trigger	"manual" gates the step on user click.
step.deployment	Bitbucket deployment environment (configured in the UI).

Minimal example

image: node:20

definitions:
  caches:
    npm: ~/.npm

pipelines:
  default:
    - step:
        name: test
        caches: [npm]
        script:
          - npm ci
          - npm test

Context variables

The same concept goes by a different name on every platform. Use this table when porting expressions and conditions.

Concept	GitHub Actions	GitLab CI	CircleCI	Bitbucket
Branch name	github.ref_name	$CI_COMMIT_REF_NAME	<< pipeline.git.branch >>	$BITBUCKET_BRANCH
Commit SHA	github.sha	$CI_COMMIT_SHA	<< pipeline.git.revision >>	$BITBUCKET_COMMIT
Tag name	github.ref_name	$CI_COMMIT_TAG	<< pipeline.git.tag >>	$BITBUCKET_TAG
Repository slug	github.repository	$CI_PROJECT_PATH	<< pipeline.project.git_url >>	$BITBUCKET_REPO_FULL_NAME
Run / pipeline id	github.run_id	$CI_PIPELINE_ID	<< pipeline.id >>	$BITBUCKET_BUILD_NUMBER
Triggering event	github.event_name	$CI_PIPELINE_SOURCE	<< pipeline.trigger_source >>	(implicit; check pipelines.* section)
Actor / user	github.actor	$GITLAB_USER_LOGIN	$CIRCLE_USERNAME	$BITBUCKET_STEP_TRIGGERER_UUID
Workspace path	github.workspace	$CI_PROJECT_DIR	$CIRCLE_WORKING_DIRECTORY	$BITBUCKET_CLONE_DIR
PR / MR source branch	github.head_ref	$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME	$CIRCLE_BRANCH (head ref)	$BITBUCKET_PR_DESTINATION_BRANCH (target only)
PR / MR target branch	github.base_ref	$CI_MERGE_REQUEST_TARGET_BRANCH_NAME	(not directly exposed)	$BITBUCKET_PR_DESTINATION_BRANCH

Related Tools

data_object

YAML Formatter

Format and validate YAML. Convert YAML to JSON or JSON to YAML. Supports 2 and 4 space indentation.

timer

Cron Builder

Visual builder for cron-job schedules.

filter_list_off

Gitignore Generator

Generate .gitignore files for any language, framework, or IDE — 100+ templates, 100% client-side.

schema

JSON Schema Generator

Generate a JSON Schema from one or more sample JSONs — drafts 2020-12, 2019-09, 7, 6, 4. Detects formats (date-time, email, uuid, ipv4, uri), extracts $defs, validates with AJV, and exports to YAML, TypeScript, and Zod. 100% in your browser.

auto_awesome

AI Coding Rules

Curated rules-file library and generator for Cursor, Claude Code, GitHub Copilot, Windsurf, Cline, Aider, Continue, and Cody. Browse 20 hand-crafted .cursorrules / CLAUDE.md / copilot-instructions.md files for popular stacks, build a custom one with the wizard, or convert any rules file between AI-tool formats.