Set up and monitor deployments

Set up a deployment

This guide covers the general setup of deployment environments. If you’re seeking platform-specific information, check out the deployment guides.

First, we'll define your environments in Bitbucket settings.

You can set:

their name
what type of environment they are
the order they show on your dashboard
any variables specific to that environment
and, if you have the premium plan, who can deploy to each one.

Then all you need to do is reference them in your bitbucket-pipelines.yml file to see them on your deployments dashboard.

Step 1: Define your environments

First we'll add the details of your environments.

When you enable pipelines, we create 3 basic environments for you by default, a test environment called 'Test', a staging environment called 'Staging', and a production environment called (you've guessed it!) 'Production'.

The environment types are used to logically order your environments, nothing more, so don't worry if the types don't quite match up to the function you use them for.

Go into your repository settings.
In the Pipelines section, choose Deployments
Click on any environment to:
- change its name
- set environment specific deployment variables.
  Deployment variables override both team and repository variables. Also variables with the same name can have different values for each deployment environment. For example, you could set a different $DEPLOYMENT_SECRET_KEY for each environment. If you then also restrict the environment, only your admins can use your secret keys.
- restrict the ability to deploy to admins, or to specific branches.

If you want to add more environments, decide which type of environment best describes it (test, staging, or production) and click add environment in that section.

You can also move environments within their type by clicking the left hand edge and dragging:

Step 2: Configure your deployment steps

Add the deployment keyword, followed by the name of the environment, into the relevant step in your bitbucket-pipelines.yml file.

For example:

- step:
        name: Deploy to production
        deployment: production-east
        script:
          - python deployscript.py prod

This step will now show up in the deployment dashboard.

We support deploying to test, staging, and production type environments, and they must be listed in this order in each pipeline. For example, if you have 2 test and 2 production environments, the steps deploying to any test environment must come before any step deploying to production type environments.

Commit the update to your bitbucket-pipelines.yml file to run your deployment pipeline.

image: node:10.15.0

pipelines:
  default:
    - step:
        name: Build and push to S3
        script:
          - apt-get update
          - apt-get install -y python-dev
          - curl -O https://bootstrap.pypa.io/get-pip.py
          - python get-pip.py
          - pip install awscli
          - aws deploy push --application-name $APPLICATION_NAME --s3-location s3://$S3_BUCKET/test_app_$BITBUCKET_BUILD_NUMBER --ignore-hidden-files
    - step:
        name: Deploy to test
        image: aneitayang/aws-cli:1.0
        deployment: testbed
        script:
          - python deploy.py test
    - step:
        name: Deploy to staging
        image: aneitayang/aws-cli:1.0
        deployment: staging1
        trigger: manual
        script:
          - python deploy.py staging
    - step:
        name: Deploy to production
        image: aneitayang/aws-cli:1.0
        deployment: production-east
        trigger: manual
        script:
          - python deploy.py prod

Step 3: Track your deployments

Once your deployment step has run, you can track your deployments on the Deployments dashboard.

Understand the deployment dashboard

Use the deployments dashboard to get information about all your deployment environments at a glance. Also you can use deployment variables with permissions to make sure only the branches or people you want to deploy.

Deployment review and promotion

If you've made a deployment step manual, you will see a Promote button on the Deployments dashboard. Clicking on the Promote button launches the deployment preview screen where you can review the commits and the file changes that will be deployed. If it looks good, click Deploy and we'll trigger your manual deployment step.

Note: you can only have one in-progress deployment in each environment. Any later pipelines that deploy to the same environment will be automatically paused. You can manually resume the paused deployment step once the in-progress deployment completes.

Deployment information

There is a variety of information you can access from the environment card.

1. Deployment history

By clicking on the environment name you can see a history of all earlier deployments to an environment. You can click on any of these to get a deployment summary.

2. View pipeline

If you click on the pipeline number, it will take you to the summary for that run of the pipeline, where you can view logs and more.

3. Deployment summary

Access the deployment summary by clicking on the deployment on an environment card, or in the history list. The summary shows information about the deployment including:

The environment it was deployed to
The previous deployment in the environment
The status of the deployment
Who triggered the deployment (if the deployment was a manual step)
The date the deployment occurred
A full list of commits in the deployments
A file diff between the new deployment and the previous deployment in the environment
Any linked Jira issues you've mention in the commit message

If you use Jira to keep track of work, you can link Jira and Bitbucket, for added benefits.

Once they are linked, issues related to a deployment show up on the deployment summary and deployment preview screens, and your deployments will show up in relevant Jira issues. Just add the issue key, or keys, to your commit message and we'll do the rest.

Example

git commit -m "PT-323 Add created workers to container cluster"

In Bitbucket, this is shown as the following image.

In Jira, it is shown as:

If you rerun a successful deployment, Jira will continue to show the details of the first successful deployment, rather than any reruns.

Roll back deployments

Bitbucket Pipelines allow you to roll back a deployment step without running the entire pipeline. If your deployment failed, you can restore the last successful deployment in a couple of clicks.

Before you begin

For the Redeploy button to be enabled:

The initial deployment step in the pipeline must be completed successfully
The deployment permissions must allow the step to be redeployed (Premium plan only)
Artifacts can't be expired

Rolling back deployments

To roll back a deployment step:

Choose the deployment which you want to redeploy and click the Redeploy button.
In the Redeploy screen, review the changes and click Redeploy:

Alternatively, you can click Redeploy in the Deployments dashboard:

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Bitbucket Support