How do you create and configure a basic Bitbucket Pipeline?

Imagine a pipeline as an assembly line in a factory. Each station (step) performs a specific task, like welding, painting, or quality inspection. In Bitbucket Pipelines, each step runs inside a fresh Docker container, performs its scripts, and passes artifacts to the next step if needed.

Bitbucket Pipelines is the built-in CI/CD service for Bitbucket Cloud. You activate it by committing a bitbucket-pipelines.yml file to your repository root. The YAML file defines one or more pipelines, each containing steps. The most common pipeline is the 'default' pipeline, which runs on every push to any branch that does not have a specific branch pipeline defined. You specify a Docker image for each step (or a global image for all steps), then list the shell commands to run under the 'script' key.

Internally, when you push a commit, Bitbucket reads the YAML file, provisions a Docker container with the specified image, clones your repository into the container, and executes the script commands sequentially. Each step gets a fresh container, so steps are isolated. You can share data between steps using artifacts, and you can speed up builds with caches (like node_modules or pip packages). The build minutes are metered in Bitbucket Cloud: free plans get 50 minutes per month, while premium plans offer more.

In a production setup, teams typically define branch-specific pipelines. For example, pushes to the 'develop' branch run tests, while pushes to 'main' run tests and then deploy to staging. Pull request pipelines run whenever a PR is created or updated, providing feedback before code is merged. You can also define custom pipelines that are triggered manually from the Bitbucket UI, useful for one-off tasks like database migrations or release tagging.

A common gotcha for beginners is assuming the pipeline has access to the same environment as their local machine. The Docker container starts clean every time, so all dependencies must be installed within the step or restored from cache. Another mistake is putting secrets directly in the YAML file instead of using repository variables, which are encrypted and injected as environment variables at runtime.