Understanding Bitbucket Pipeline YAML File

In this post, we'll break down the structure of the Bitbucket Pipeline YAML file, explain its components, and walk through examples to help you write and customize your own.

Understanding Bitbucket Pipeline YAML File

Getting Started

Bitbucket Pipelines is a powerful CI/CD (Continuous Integration/Continuous Deployment) feature built into Bitbucket. It enables teams to automatically build, test, and deploy code based on a configuration defined in a single YAML file. This file (.bitbucket-pipelines.yml) resides in the root of your repository and tells Bitbucket exactly how to run your pipeline.

What is a Bitbucket Pipeline?

A Bitbucket Pipeline is a set of automated steps that are executed every time a particular event occurs in your repository. For example, a code push or a pull request.

These steps might include:

• Installing dependencies
• Running tests
• Building the application
• Deploying code to production

All of these instructions are declared in a YAML file (.bitbucket-pipelines.yml) stored in your repo.

Basic Structure of .bitbucket-pipelines.yml File

Here’s a basic example of a Bitbucket Pipeline YAML file:

 image: node:14  
 pipelines:  
  default:  
   - step:  
     name: Install and Test  
     caches:  
      - node  
     script:  
      - npm install  
      - npm test  

Let’s break this down:

image

This defines the Docker image used for the pipeline. In the example above, it uses node:14, meaning all steps will run in a Node.js 14 environment.

pipelines

This is the main section where you define your CI/CD workflows. There are different types of pipelines:

• default: Runs on every push to any branch.
• branches: Runs on specific branches.
• tags: Runs when specific tags are pushed.
• pull-requests: Runs when a PR is created or updated.

step

A step represents a sequence of commands run in a Docker container. You can define multiple steps in a pipeline.

script

A list of shell commands to execute during that step.

caches

It is optional, used to cache dependencies between builds, speeding up execution (e.g., node_modules for Node.js apps).

Tips for Writing Effective Pipelines

• Keep steps small: One logical task per step makes debugging easier.
• Use caches wisely: Avoid unnecessary installs on every build.
• Secure secrets: Store credentials in Bitbucket repository variables.
• Use Docker images that match production to reduce "works on my machine" issues.
• Test changes locally using tools like Docker or by committing to a separate branch.

Common Pipeline Use Cases

Branch-specific Pipelines: Run different pipelines for different branches:

 pipelines:  
  branches:  
   master:  
    - step:  
      name: Build and Deploy  
      script:  
       - npm install  
       - npm run build  
       - ./deploy.sh  
   develop:  
    - step:  
      name: Run Tests Only  
      script:  
       - npm install  
       - npm test  

Pipeline for Pull Requests

 pipelines:  
  pull-requests:  
   "**":  
    - step:  
      name: Lint and Test PR  
      script:  
       - npm ci  
       - npm run lint  
       - npm test  

Here, ** matches all pull request source branches.

Deploy on Tag Push

 pipelines:  
  tags:  
   v*.*.*:  
    - step:  
      name: Production Deploy  
      script:  
       - ./deploy-prod.sh  

This triggers the pipeline when a version tag (e.g., v1.2.3) is pushed.

Advanced Pipeline Use Cases

Multiple Steps and Pipelines

 pipelines:  
  default:  
   - step:  
     name: Install  
     script:  
      - npm install  
   - step:  
     name: Test  
     script:  
      - npm test  
   - step:  
     name: Build  
     script:  
      - npm run build  

Parallel Steps: Run steps in parallel to speed up your pipeline

 pipelines:  
  default:  
   - parallel:  
     - step:  
       name: Lint  
       script:  
        - npm run lint  
     - step:  
       name: Unit Tests  
       script:  
        - npm test  

Custom Caching

 definitions:  
  caches:  
   custom-node: ~/.npm  
 pipelines:  
  default:  
   - step:  
     caches:  
      - custom-node  
     script:  
      - npm install  

Artifacts: Save build outputs between steps

 pipelines:  
  default:  
   - step:  
     name: Build  
     script:  
      - npm run build  
     artifacts:  
      - dist/**  
   - step:  
     name: Deploy  
     script:  
      - ./deploy.sh  

Here, the dist/ folder is preserved and passed to the next step.

Troubleshooting Pipeline Errors

Bitbucket provides detailed logs for each step in the web interface. Common issues include:

• Incorrect indentation (YAML is whitespace-sensitive)
• Missing or incorrect Docker image
• Script command errors (e.g., missing dependencies)

Always check logs and make small iterative changes.

Summary

The .bitbucket-pipelines.yml file is the heart of CI/CD in Bitbucket. You can automate builds, tests, deployments, and may more using it. By mastering its syntax and capabilities, you can streamline your development workflow, reduce errors, and ship faster.

Thanks