Pulumi CI/CD with Bitbucket Pipelines

Bitbucket Pipelines is an CI/CD service built into Bitbucket Cloud. It allows you to build, test, and deploy your code automatically to your Pulumi staging and production stacks based on commits to specific Git branches.

This guide provides examples for integrating Bitbucket Pipelines with a Pulumi AWS TypeScript project, but the outlined steps can be adapted for other projects in your favorite language.

Prerequisites

• Sign up for a Pulumi account

• Create a Pulumi Access Token

• Install the latest Pulumi CLI

• Create a Bitbucket account with Pipelines enabled

• Create a new Bitbucket repository, and ensure you do not initialize it with a README

• Create a new Pulumi project and initialize it as a git repository

Setting up environment variables

To use Pulumi within Bitbucket Pipelines, there are a few environment variables you’ll need to set.

The first is PULUMI_ACCESS_TOKEN, which is required to authenticate with Pulumi in order to perform the preview or update.

Next, you will need to set environment variables specific to your cloud resource provider. For example, if your stack is managing resources on AWS, you will need to set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

Bitbucket pipeline configuration

In Bitbucket, a CI/CD pipeline is defined in a yaml file labeled .bitbucket-pipelines.yml. This file must exist in the root of your repository and defines how Bitbucket Pipelines will build and deploy your Pulumi stack.

Here’s an example configuration:

# This is an example Bitbucket starter pipeline configuration
# Use a skeleton to build, test and deploy using manual and parallel steps
# -----
# You can specify a custom docker image from Docker Hub as your build environment.

image: atlassian/default-image:4

pipelines:
  pull-requests:
    '**':
      - step:
          script:
            - if [ "${BITBUCKET_PR_DESTINATION_BRANCH}" != "main" ]; then printf 'target branch not main, skipping preview'; exit; fi
      - step:
          name: 'Run Pulumi Preview'
          image: pulumi/pulumi-nodejs:latest
          script:
            - npm ci
            - pulumi login
            - pulumi stack select $STACK
            - pulumi preview

  branches:
    main:
      - step:
          name: 'Run Pulumi Up'
          image: pulumi/pulumi-nodejs:latest
          script:
            - npm ci
            - pulumi login
            - pulumi stack select $STACK
            - pulumi up --yes

When working with Pulumi in Bitbucket Pipelines with Pulumi, you will need to specify when certain actions, like previews, are run.

'**':
  - step:
      script:
        - if [ "${BITBUCKET_PR_DESTINATION_BRANCH}" != "main" ]; then printf 'target branch not main, skipping preview'; exit; fi

This step and script ensures that the following Pulumi preview step only runs if the pull request is targeting the main branch. This avoids unnecessary previews for pull requests to other branches.

Running the pipeline

Once the .bitbucket-pipelines.yml is committed, each push or pull request to the main branch of the repository will trigger the pipeline, automating the deployment of your infrastructure. You can monitor the pipeline status in the Pipelines tab in Bitbucket.