Bitbucket deployment guidelines

We believe development tools are more powerful when they provide flexibility but also steer teams towards the practices that help them succeed. In the design of Bitbucket Deployments, we're using our experience working with thousands of customers to recommend and reinforce the practices we see working for teams in the trenches.

This page shares some of the thinking behind Bitbucket Deployments, expanding on our upcoming blog post on this topic.

Built for Continuous Delivery

Bitbucket Deployments is built for teams doing continuous delivery, which generally means deploying to SaaS/web environments at least once per week, and preferably much more often. We believe this is the future of software development, and want to help as many teams get there as possible.

The key tenet of continuous delivery is keeping your code always releasable. In Bitbucket, that means you are doing feature branches with branch-based validation (automated/manual testing and code review), then merging to the default main branch with release-ready code that is automatically or manually deployed.

If you're always keeping your main branch releasable, this implies:

• you should fix problems on your main branch and redeploy it, rather than deploying hot-fixes built on other branches into your environments

• your build pipeline should be fast enough that running tests before deployment is a natural part of making sure your changes haven't broken anything

• if promoting builds through environments is a part of your normal process, you should also do it in an emergency, and optimize your normal process to be able to handle this.

Another common prerequisite is to use feature toggle or feature flags to make new functionality available independent of new code going out.

Our recommended workflow

Our deployment tooling was focused on a three-environment workflow that we've seen commonly used in the wild. The exact names sometimes vary, but the following process is extremely common:

• Feature branches are merged to main once they pass code review and have been tested automatically by Pipelines

• Pipelines deploys automatically to Test, on each commit on the main branch

• Pipelines has a manual step to deploy to Staging, triggered once the integrated features have been manually tested in the test environment

  • The staging upgrade verifies that any pre-deployment scripts, database schema changes, etc. will work successfully in production

• Pipelines has a manual step to deploy to Production, once the Staging environment has been verified.

Some teams may skip steps in this flow (e.g. test/staging environments) or automate some of the manual steps, but we're expecting most teams to use these steps in roughly the same order.

It's also important to note here that features are not released directly by code deployment, but via a feature flag, once they are ready for customers to use.

Why not more environments?

Bitbucket Deployments is designed to track the history of shared environments, so this excludes a few things you might expect:

• Feature- or dev-specific environments don't benefit as much from long-term tracking as shared environments, so we have not included them for now.

• Production rollout strategies like blue-green or canary deployments should be considered a single production deployment in Bitbucket, rather than two distinct deployments or environments. We have decided to model your production environment as a single unit whose code changes can be tracked on a longer timeframe, as we believe this provides the most benefit to the team. Introducing detailed deployment rollout information would obscure and complicate things, and duplicate the information that your rollout orchestration tool provides.

• Geographic regions are not currently handled, and we see this as an area for potential future improvements. We are open to suggestions on how best to fit this into Bitbucket Deployments.

Outside of those, we're looking to understand where more than three shared environments makes sense. It seems that most teams operating in this kind of model are struggling with complexity and having an unclear pipeline for getting code into production. We would not like to encourage this until we understand more about the benefits and purposes of each environment in a 4- or 5-environment model.

Note: you can continue deploying code using Bitbucket Pipelines but not actually tracking deployments (i.e. don't put the deployment attribute on your step) if you have more than the three environments we provide, or your environment names do not match the ones provided.

Use artifact-based deployments instead of branch-based deployments.

Although Pipelines fully supports branch-based deployment as well, we recommend using manual steps with artifact promotion as a safer method of deploying the same artifact to multiple environments. Rebuilding the branch for each deployment can result in slight differences of code (e.g. dependency versions) between environments.

What are your deployment best practices?

Please share your ideas and suggestions with us at pipelines-feedback@atlassian.com!