Configure bitbucket-pipelines.yml

With Bitbucket Pipelines you can store and manage your build configurations in a single bitbucket-pipelines.yml file. The content of bitbucket-pipelines.yml is structured around keywords that shape the anatomy of your build configuration.

 


 

 


 

Before you begin

 

  To start using Pipelines you must enable it in Bitbucket Cloud. You can find the guidelines in Get started with Bitbucket Pipelines.

Hint: Add the bitbucket-pipelines.yml file in the onboarding process or create it locally and push it to the master branch of the repository that you want to build. 

 

  Make sure that the name, placement, and content of your bitbucket-pipelines.yml file follow the guidelines.

Name The name of the file must be bitbucket-pipelines.yml
Location The file must be located in the root directory of the repository that you want to build.
Format

The content of the file must be compliant with our bitbucket-pipelines.yml guidelines outlined below.

 

  Finally, some tips:

  • bitbucket-pipelines.yml is indented only with spaces, not tabs. 
  • It's important to use consistent spacing. In general and in bitbucket-pipelines.yml (wink)
  • You can try validating your bitbucket-pipelines.yml with online YAML linter.

You can find the full list of limitations in Limitations of Bitbucket Pipelines.

 


 

Overview  

We run your builds with Docker. If youdon't specify an image, we'll run your build with the default one, but it's better to get an environment that meets the specific needs of your configuration.

You can build the following pipelines:

  • default 
  • branches
  • tags (Git only)
  • bookmarks (Mercurial only)
  • custom

You can start with a simple configuration with the default pipeline, which is run on all branches that don't have any branch-specific configuration and have the bitbucket-pipelines.yml file in the root directory.

You can add specific build configurations for branches, tags, and bookmarks. You can refer to branch, tag, and bookmark names by specifying their name or by using glob patterns

If you want to trigger some build pipelines manually, you can add them in the custom section.

Currently, each pipeline can have one step in which you can override the main Docker image. Each step contains at least one script.

 

 

 


 

Keywords

 Keywords are unique and can't be changed. A quick reference table for keywords that you can use:

 

Keyword

Required

Description

image

no

A Docker image with which we run your builds. If you don't specify the image, your builds run in the default Bitbucket image. You can override the main image at the step level.

clone no

Defines the depth of Git clones for all pipelines.

You can either specify any positive number greater than zero or a full clone. If you don't specify the Git clone depth, it defaults to 50.

Note: This keyword is supported only for Git repositories.

pipelines

yes

Defines the start of your build pipeline.

default

no

Contains the pipeline definition for all branches that don't have specific configuration in other sections.

branches

no

Contains build pipelines for specific Git branches and Mercurial named branches.

tags no Contains build pipelines for specific Git tags and annotated tags.
bookmarks no Contains build pipelines for specific Mercurial bookmarks.
custom no Contains build pipelines that can be triggered manually from the Bitbucket Cloud GUI.

step

yes

Defines a build execution unit. This is the set of commands that are executed on a single build agent. You can specify an image for a step.

script

yes

Contains the list of bash commands that are executed in sequence.

 


 

image (optional)

Bitbucket Pipelines uses Docker containers to run your builds.

  • You can use the default image (atlassian/default-image:latest) provided by Bitbucket or define a custom one. You can specify any public or private Docker image that's not hosted on a private network. 
  • You can define images on the global or step level. You can't define an image on the branch level.

To specify an image, use

image: <your_account/repository_details>:<tag>

For more information about using and creating images, see Use Docker images as build environments in Bitbucket Pipelines

Examples 

 

image: java
Uses the image with the latest Java version
image: java:u866
Uses Java in the u866 version
image: nodesource/node:iojs-2.0.2
Uses the non-official node version with version iojs-2.0.2

The Docker image that you want to use must have Bash.

 


 

clone (optional)

You can define the depth of clones on the global level.  You can either specify any positive number greater than zero or a full clone. If you don't specify the Git clone depth, it defaults to 50.

Note: This keyword is supported only for Git repositories.

If you're using the clone keyword, always specify the depth:

 

bitbucket-pipelines.yml
# This is a sample build configuration for Javascript.
# Only use spaces to indent your .yml configuration.
# -----
# You can specify a custom docker image from Docker Hub as your build environment.
image: node:4.6.0
clone:           # the 'clone' section 
  depth: 5       # the depth, in this case the clone will contain last five commits
 
pipelines:
  default:
    - step:
        script:
          - echo "Clone all the things!"

 


 

pipelines (required)

The start of your build pipeline. You can build the following pipelines:

  • default 
  • branches (Git and Mercurial)
  • tags (Git)
  • bookmarks (Mercurial)

 


 

default (optional)

Steps in the default pipeline are performed on all branches unless specified otherwise. You can add branch-specific configuration in the branches section.

Note: The default pipeline doesn't run on tags or bookmarks.

 


 

branches (optional)

Serves as a container for all branch-specific build pipelines. The names or expressions in this section are matched against:

  • branches in your Git repository
  • named branches in your Mercurial repository

You can use glob patterns for handling the branch names.

 


 

tags (optional)

Serves as a container for all tag-specific build pipelines. The names or expressions in this section are matched against tags and annotated tags in your Git repository. You can use glob patterns for handling the tag names.

 

bitbucket-pipelines.yml
# This is a sample build configuration for Javascript.
# Only use spaces to indent your .yml configuration.
# -----
# You can specify a custom docker image from Docker Hub as your build environment.
image: node:4.6.0
  
pipelines:
  default:
    - step:
        script:
          - npm install
          - npm test
  tags:                         # add the 'tags' section
    release-*:                  # specify the tag
      - step:                   # define the build pipeline for the tag
          script:
            - npm install
            - npm test
            - npm run release
  branches:
    staging:
      - step:
          script:
            - echo "Clone all the things!" 

 


 

bookmarks (optional)

Serves as a container for all bookmark-specific build pipelines. The names or expressions in this section are matched against bookmarks in your Mercurial repository. You can use glob patterns for handling the tag names.

 

bitbucket-pipelines.yml
# This is a sample build configuration for Javascript.
# Only use spaces to indent your .yml configuration.
# -----
# You can specify a custom docker image from Docker Hub as your build environment.
image: node:4.6.0
  
pipelines:
  default:
    - step:
        script:
          - npm install
          - npm test
  bookmarks:                      # add the 'bookmarks' section
    release-*:                    # specify the bookmark
      - step:                     # define the build pipeline for the bookmark
          script:
            - npm install
            - npm test
            - npm run release
  branches:
    staging:
      - step:
          script:
            - echo "Clone all the things!"

 


 

custom (optional)

Serves as a container for all pipelines that can be triggered manually from the Bitbucket Cloud interface.


# This is a sample build configuration.
# Only use spaces to indent your bitbucket-pipelines.yml configuration.
# -----
# You can specify a custom docker image from Docker Hub as your build environment.
image: node:4.6.0
   
pipelines:
  custom: # Pipelines that are triggered manually
    sonar: # The name that is displayed in the list in the Bitbucket Cloud GUI
      - step:
          script:
            - echo "Manual triggers for Sonar are awesome!"
    deployment-to-prod: # Another display name
      - step:
          script:
            - echo "Manual triggers for deployments are awesome!"
  branches:  # Pipelines that run automatically on a commit to a branch
    staging:
      - step:
          script:
            - echo "Automated pipelines are cool too."


With the configuration like the one above, you should see the following pipelines in the 'Run pipeline' dialog in Bitbucket Cloud:



For more information, see Run pipelines manually.

 


 

step (required)

Defines a build execution unit. Steps are executed in the order in which they appear in the pipeline. Currently, each pipeline can have only one step. You can override the main Docker image by specifying an image in a step.

 


 

script (required)

Contains the list of Bash commands that are executed in sequence. Scripts are executed in the order in which they appear in a step.

  • We don't support multi-line strings yet, which means that you need to provide a list of commands.
  • We recommend that you move large scripts to a separate script file and call it from bitbucket-pipelines.yml

 


 

Glob patterns cheat sheet

Glob patterns don't allow any expression to start with a star. Every expression that starts with a star needs to be put in quotes.

feature/*
  • Matches with feature/<any_branch>. 
  • The glob pattern doesn't match the slash (/), so Git branches like feature/<any_branch>/<my_branch> are not matched for feature/*.
feature/bb-123-fix-links
  • If you specify the exact name of a branch, a tag, or a bookmark, the pipeline defined for the specific branch overrides any more generic expressions that would match that branch. 
  • For example, let's say that you specified a pipeline for feature/* and feature/bb-123-fix-links. On a commit to the feature/bb-123-fix-links branch Pipelines will execute steps defined for feature/bb-123-fix-links and will not execute the steps defined in feature/*.
'*'
  • Matches all branches, tags, or bookmarks. The star symbol (*) must be in single quotes.
  • This glob pattern doesn't match the slash (/), so Git branches like feature/bb-123-fix-links are not matched for '*'. If you need the slash to match, use '**' instead of '*'.
'**'
  • Matches all branches, branches, tags, or bookmarks. For example, it includes branches with the slash (/) like feature/bb-123-fix-links. The ** expression must be in quotes.
'*/feature'
  • This expression requires quotes.

'master' and duplicate branch names

  • Names in quotes are treated the same way as names without quotes. For example, Pipelines sees master and 'master' as the same branch names.  
  • In the situation described above, Pipelines will match only against one name (master or'master', never both).
  • We recommend that you avoid duplicate names in your bitbucket-pipelines.yml file.

 


 

 

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport