Bitbucket Pipelines is an integrated CI/CD service, built into Bitbucket. It allows you to automatically build, test and even deploy your code, based on a configuration file in your repository. Essentially, we create containers in the cloud for you. Inside these containers you can run commands (like you might on a local machine) but with all the advantages of a fresh system, custom configured for your needs.

To set up Pipelines you need to create and configure the bitbucket-pipelines.yml file in the root directory of your repository. This file is your build configuration, and using configuration-as-code means it is versioned and always in sync with the rest of your code.

The bitbucket-pipelines.yml file holds all the build configurations for your repository. YAML is a file format that is easy to read, but writing it requires care. Indenting must use spaces, as tab characters are not allowed.

There is a lot you can configure in the bitbucket-pipelines.yml file, but at its most basic the required keywords are:

pipelines: contains all your pipeline definitions.

defaultcontains the steps that run on every push.

step: each step starts a new Docker container with a clone of your repository, then runs the contents of your script section.

script: a list of commands that are executed in sequence.

Step 1: Choose a language template

Pipelines can build and test anything that can run on Linux as we run your builds in Docker containers. We've provided templates in Bitbucket to help you get started with popular languages and platforms: PHP, JavaScript/Node.js (npm), Java (Maven/Gradle), Python, Ruby, C#, C++ (make) and more.

image showing pipelines navigation

  1. Select Pipelines from the left hand navigation bar.
  2. Select the language template you'd like to use. 

Don't see your language? Don't worry, there is always the Other option in the More menu if you can't see what you need. This uses our default Docker image that contains many popular build tools, and you can add your own using apt-get commands in your script.

Step 2: Configure your pipelines

You'll need to edit the bitbucket-pipelines.yml file to include the commands required to build your software. You can also use pipes, found in the right hand side of the editor, to quickly add in popular configurations.

Picture of the editor

  1. Use the editor to customize the file to suit your needs. There are some basic examples below.

    Browse some example configurations

    Here's a very basic configuration that runs a command to check the version of python in the container:

        - step:
              - python --version

    You can replace the contents of the script section with the commands you use to build and test. If you have quite a few commands to run, you might like to put them in a separate script file, and call that within your step. Also, if your test reports end up in an expected directory, you'll see the output of any failed tests in the logs.

    After you've built and tested your code, you might want another step which deploys your build to a staging environment. We'll make it manually triggered, so you can deploy at the click of a button on the Pipelines page:

        - step:
            name: Build and test
              - python
        - step:
            name: Deploy to staging
            trigger: manual
            deployment: staging
              - python

    We also have more information on how to configure this file.

  2. Select Commit file when you are happy with your edit and ready to run your first Pipeline.

You've now created your default pipeline. Wahoo! 

Pipelines will now automatically trigger whenever you push changes to your repository, running the default pipeline.

To get the most out of pipelines, you can add more to the bitbucket-pipelines.yml file. For example, you can define which Docker image you'd like to use for your build, create build configurations for specific branches, tags, and bookmarks, make sure any test reports are displayed or define which artifacts you'd like to pass between steps.

What's next?

Now that you've got the basics, have a look at how you can view your pipelines.