In Bitbucket Pipelines, Concurrency Groups run steps that share a concurrency-group name one at a time, while the environment keyword applies an environment's variables and restrictions to a step without deployment locks. Both work alongside the classic deployment keyword, which you still add to a step if you want it tracked on the Deployments dashboard.
Atlassian's Bitbucket Pipelines is evolving to give development teams more control and flexibility in their continuous integration/continuous delivery (CI/CD) workflows. Bitbucket Cloud has recently rolled out two powerful new features, Concurrency Groups and Environments, that break apart the old one-size-fits-all deployment model into more granular, customizable components. These enhancements make pipeline deployments less rigid and more user-friendly by decoupling previously intertwined functions like deployment locks, environment variables, and permissions.
We at Atlas Bench have been closely following these changes. In fact, we recently delivered a presentation on Concurrency Groups and Environments to one of our clients, highlighting how these tools can streamline their Bitbucket Pipelines. In this blog post, we’ll revisit those key points, explain each new feature in depth, and show you how to start using them to enhance your own CI/CD process.
Rigid Deployments (Old Model): In the past, Bitbucket Pipelines’ Deployments feature was somewhat rigid. It forced teams to adopt an all-or-nothing approach. For example, even if a team only needed specific pieces (like environment variables or permission controls), they still had to use deployment locks and the Deployments dashboard. This monolithic approach made it hard to tailor pipeline behavior to unique needs.
User Feedback for Flexibility: Development teams voiced their need for more customization and control. Atlassian received consistent feedback that users wanted to enable just the parts of deployment functionality they required, without the overhead of unwanted features. This demand set the stage for a more modular pipeline design.
A Modular Transformation: Atlassian listened. The introduction of Concurrency Groups and Environments is the first step in breaking down the monolithic deployment framework into smaller, focused features. Instead of one deployment keyword controlling everything, you now have discrete options to manage concurrency and environment settings independently. This modular approach lets you pick and choose the capabilities you need for each pipeline step.
Preserving Core Capabilities: Importantly, these changes are additive and preserve the core capabilities of Deployments. Concurrency Groups and Environments are designed to complement the existing deployments feature. They can work alongside the traditional deployment keyword. In fact, Atlassian has indicated that in the future the deployment keyword may evolve into a shorthand that automatically configures these new capabilities for backward compatibility, giving you enhanced control without breaking existing setups.
One-at-a-Time Execution: Concurrency Groups let you ensure that only one pipeline step runs at a time for a given defined group. In other words, if multiple steps belong to the same concurrency group, Bitbucket will run them sequentially rather than all at once. This is ideal for preventing conflicts (for example, avoiding two deployments running simultaneously on the same environment or resource).
Easy Configuration via Labels: There’s no complex setup needed: you simply assign a label (a name of your choosing) to the concurrency-group field in your pipeline step definitions. Any steps with the same concurrency-group name automatically become part of that group. These groups are dynamic, so you don’t need to predefine them anywhere; the name itself acts as the grouping key.
Automatic Queueing (FIFO Order): When more than one step is triggered in the same group, Bitbucket Pipelines will queue the additional steps. Only one step in the group runs at any given time. The moment one step finishes, the next step in that group’s queue (first-in-first-out) will automatically start. In the Pipelines UI, you’ll see queued steps marked as "Waiting to run", which then switch to "In progress" once their turn comes.
Replaces Legacy Deployment Locks: Previously, Bitbucket enforced deployment locks to prevent two pipelines from deploying to the same environment concurrently. Concurrency Groups serve a similar purpose but with much more flexibility. Importantly, you no longer need to use the deployment keyword just to get one-at-a-time execution. Now concurrency is controlled by the group name itself, independent of any specific deployment environment.
Current Limits and Future Enhancements: At launch, each Concurrency Group processes one step at a time (effectively a queue with a concurrency limit of 1). This covers most use cases, such as ensuring only one build or one deployment runs at a time for a given target. Atlassian has indicated that more configurability is coming. For instance, future updates may allow higher concurrency limits (e.g. permitting two parallel runs per group) and introduce advanced queueing strategies (possibly a "fast-forward" option in the queue). These enhancements will further refine how teams can tailor Concurrency Groups to their needs.
Setting up a concurrency group in your Bitbucket pipeline is straightforward. Simply add a concurrency-group attribute to any step in your bitbucket-pipelines.yml and give it a group name. For instance, consider the following minimal pipeline configuration:
yamlpipelines:
default:
- step:
name: Build
concurrency-group: build-group
script:
- echo "Building the application"
In this example, any step labeled with concurrency-group: build-group will respect the concurrency rule. If one step named "Build" is already running under the group build-group, a second step tagged with the same group will not start immediately. Instead, it will wait until the running one finishes. Bitbucket Pipelines automatically handles this queueing for you across the entire repository. Even if different pipelines use the same concurrency group name, they will all funnel into a single execution sequence.
Note: If you also want to track a step on the Deployments dashboard, you should still include the deployment: <environment> keyword alongside the concurrency-group on that step. The concurrency group will handle the queuing and sequential execution (taking precedence over the normal deployment lock), while the deployment keyword ensures the run is recorded on the deployment dashboard.
Decoupled Environment Configuration: The new environment keyword lets you apply environment-specific configuration to a pipeline step without using the full deployment mechanism. It separates out things like environment variables and access controls from the traditional Deployments framework. This means you can attach an environment context (for example, "staging" or "production") to a step without triggering deployment locks or other deployment-related overhead.
Variables and Permissions Built In: When you use environment: <name> on a step, Bitbucket will pull in any variables defined for that environment and enforce any restrictions associated with it. Environments in Bitbucket can have:
Environment Variables: custom variables or secret values that your script can use (for example, database passwords or API keys specific to that environment).
Admin-Only Permissions: you can mark an environment so that only pipeline runs triggered by admins are allowed (or you can require manual approvals for non-admins).
Branch Restrictions: you can limit which branches are allowed to run steps for a given environment (for instance, only the main branch or release branches can use the production environment).
No Automatic Locks (Greater Parallelism): Unlike a full deployment, using an environment does not inherently lock that environment. Multiple steps (even in parallel) can target the same environment name simultaneously, and each will get the appropriate variables and checks applied. This is much more flexible: for example, you could have two parallel steps both using environment: staging to run integration tests; each step will load the staging config and run at the same time. (In the old model, marking both as "staging" deployments would have serialized them because of the deployment lock.)
Uses Existing Configuration: Bitbucket still uses the same Deployments settings screen in your repository to manage environment details. You define environments (like "Dev", "Staging", "Production") and set their variables and rules in that interface as before. There’s no new interface to learn: the pipeline’s environment keyword simply references one of those predefined environments by name and leverages whatever configuration you’ve already set up.
Works Alongside Deployments: The Environments feature doesn’t replace the concept of Deployments. Instead, it offers a more granular way to use only the parts you need. You can apply the environment keyword on any step where you want environment-specific context without the other aspects of deployments. And if you do want full deployment tracking (with locks and the deployment dashboard entry), you can still use the classic deployment keyword on a step (or even combine it with an environment and concurrency-group on the same step). The key point is that you now have the flexibility to use environment settings independently from the heavier deployment framework when appropriate.
Adding an environment to a pipeline step is as simple as including the environment field in your bitbucket-pipelines.yml and assigning it an environment name that you’ve configured in Bitbucket. For example:
yamlpipelines:
default:
- step:
name: "Deploy to production environment"
environment: production
script:
- echo "Deploying to production"
In the above example, the step will run with the production environment's context. This means any variables stored for the "production" environment will be available during the step (for instance, a production database URL or API token), and any rules (like requiring admin permissions or restricting execution to the main branch) will be enforced. We didn’t need to use the deployment keyword here. This pipeline step simply uses the production configuration without locking the environment. You could even run another step with environment: production at the same time (for example, in a parallel stage or in a separate pipeline run), and both would execute concurrently while pulling in the same production settings.
Configurable Concurrency: Atlassian is working on allowing more than one step to run concurrently in a Concurrency Group. Today, each group has a fixed limit of one-at-a-time, but future updates may let you raise the concurrency limit (for example, allowing 2 or 3 parallel executions within the same group). This would give teams finer control over how strict or relaxed the sequencing should be.
Advanced Queue Strategies: Another anticipated improvement is support for different queueing strategies beyond the default first-in-first-out. Atlassian has mentioned a possible "fast-forward" queue option. This feature could allow newer pipeline runs to jump ahead in the queue under certain conditions (to avoid waiting behind older, potentially irrelevant builds). Such capabilities would make queue management smarter, ensuring your CI/CD pipeline is as efficient as possible.
Deployment Keyword Evolution: The classic deployment keyword isn’t going away. However, Atlassian plans to redefine it in a more flexible way. In the future, using deployment in your pipeline could act as a convenient shorthand that automatically enables a set of granular features behind the scenes (for example, applying an environment's variables and concurrency controls for that step). This approach would allow teams still using the old syntax to seamlessly benefit from the new capabilities.
Further Modularization: Concurrency Groups and Environments are just the beginning. We can expect Atlassian to continue breaking down the deployment process into additional modular components. Each piece of functionality (such as approvals, notifications, or other deployment behaviors) might become individually configurable. That means more power to tailor Bitbucket Pipelines to fit your workflow, rather than forcing your workflow to fit the tool.
Bitbucket Pipelines is steadily becoming more flexible and powerful, driven by user feedback. We anticipate more updates in the coming months, and as always, Atlas Bench will keep you informed and help you make the most of these new features as they roll out.
Bitbucket Pipelines’ new Concurrency Groups and Environments represent a significant leap forward in CI/CD flexibility. By breaking apart the once-rigid deployment framework, Atlassian is empowering teams to deploy and release on their own terms. Teams can now pick and choose only the components they need for a given workflow. Whether it’s preventing overlapping runs with Concurrency Groups or injecting secure configuration with Environments, these features can make your pipelines safer, faster, and easier to manage.
As an early adopter and Atlassian Solution Partner, Atlas Bench is excited about the possibilities these enhancements bring to our clients’ workflows. We encourage you to experiment with Concurrency Groups and Environments in your Bitbucket Pipelines and see the benefits for yourself.