What's the difference between the default pipeline and branch pipelines?

The `default` pipeline runs for any push that doesn't match a more specific pipeline. A `branches` entry (e.g. for `main`) only runs when that specific branch is pushed to, and takes priority over `default` for matching pushes, letting you run a different (often stricter, or deployment) set of steps on your main branch.

How do cache names work in Bitbucket Pipelines?

Bitbucket ships several predefined cache names out of the box (like `node`, `pip`, `docker`, `composer`) that map to known dependency directories for common ecosystems. Adding a cache name to a step tells Bitbucket to persist and restore that cache between pipeline runs, speeding up dependency installation.

What does the pull-requests pipeline do?

It defines steps that run specifically when a pull request is opened or updated, using the `'**'` pattern to match pull requests targeting any branch. This is commonly used for running tests or linting on every PR without needing that same pipeline to run on ordinary branch pushes.

Can steps in different pipelines use different Docker images?

Yes. Each step you define, whether in the default pipeline, a branch pipeline, or the pull-requests pipeline, has its own image field; leaving it blank falls back to the pipeline-level default image you set at the top of the file.

Bitbucket Pipelines Generator - Build bitbucket-pipelines.yml

Overview

Introduction

Bitbucket Pipelines' YAML nests a `default` pipeline, optional per-branch pipelines, and an optional pull-requests pipeline all under one `pipelines:` key, and it's easy to misplace a step or forget the `'**'` branch-matcher syntax for pull requests.

This tool generates a complete, valid bitbucket-pipelines.yml from a form covering exactly this structure: a default pipeline, branch-specific overrides, shared caches, and a pull-requests pipeline.

What Is Bitbucket Pipelines Generator?

A form-driven generator for Bitbucket Pipelines configuration. You set a default Docker image, add one or more steps to the default pipeline, optionally add branch-specific pipelines with their own step, choose named caches to apply everywhere, and optionally enable a pull-requests pipeline.

The output matches Bitbucket's `image → pipelines.default → pipelines.branches → pipelines.pull-requests` layout exactly.

How Bitbucket Pipelines Generator Works

Every step (in default, a branch pipeline, or pull-requests) is wrapped in Bitbucket's required `- step:` structure with `name`, `image`, `caches`, and `script` keys nested underneath, and multi-line script text is split into one YAML list item per line.

The named caches you select are added to the `caches:` list of every step in the file, since Bitbucket caches are configured per-step rather than globally.

When To Use Bitbucket Pipelines Generator

Use it when setting up Bitbucket Pipelines for a new repository and you want a working YAML file with a sensible default-plus-branch-plus-PR structure from the start.

It's also useful for adding a dedicated main-branch deploy pipeline or a PR-checks pipeline to a repo that currently only has a default pipeline.

Often used alongside GitLab CI Generator, GitHub Actions Workflow Generator and Azure DevOps Pipeline Generator.

Features

Advantages

Correctly nests Bitbucket's somewhat unusual `- step:` wrapper structure, a common source of YAML errors when written by hand.
Applies shared caches consistently across every step in the file instead of requiring you to repeat the caches block per step.
Generates the pull-requests pipeline with the correct `'**'` branch-matcher syntax automatically.

Limitations

Only predefined cache names are supported (e.g. node, pip, docker); custom cache definitions with explicit paths aren't generated.
Doesn't cover parallel steps, deployment environments, or Bitbucket's `pipes:` marketplace integrations.

Examples

A default pipeline with a Node cache

Input

default image: node:20; step 'Build and test' → script: npm install / npm test; cache: node

Output

image: node:20

pipelines:
  default:
    - step:
        name: Build and test
        image: node:20
        caches:
          - node
        script:
          - npm install
          - npm test

The step's name, image, cache, and script lines are nested under Bitbucket's required `- step:` wrapper.

Best Practices & Notes

Best Practices

Reserve branch-specific pipelines (especially on main) for deploy or release steps you don't want running on every ordinary feature-branch push.
Add the pull-requests pipeline for fast checks (lint, unit tests) so contributors get feedback before merging, separate from a potentially slower default pipeline.
Use the predefined cache names that match your stack (node, pip, docker) rather than skipping caching, first-run dependency installs are usually the slowest part of a pipeline.

Developer Notes

Bitbucket Pipelines YAML requires each step to be wrapped as a single-key list item (`- step: {...}`), which this generator renders explicitly rather than relying on a generic object-to-YAML serializer, since that wrapper is easy to get wrong (e.g. omitting the list dash) when hand-written. The pull-requests pipeline always uses the `'**'` glob, matching Bitbucket's own documented pattern for "any branch" pull request pipelines.

Bitbucket Pipelines Generator Use Cases

Scaffolding Bitbucket Pipelines for a new repository
Adding a dedicated main-branch deploy step to an existing pipeline
Setting up fast PR checks separate from a slower default pipeline

Common Mistakes

Forgetting the `'**'` branch pattern under `pull-requests:`, which causes the pull-requests pipeline to not match any pull request at all.
Defining caches per-step inconsistently, so some steps reinstall dependencies from scratch every run while others benefit from caching.

Tips

Enable Bitbucket's built-in pipeline validator (the editor in the repository's Pipelines settings) after pasting in generated YAML to catch anything this generator's simplified model doesn't cover.

Bitbucket Pipelines Generator