Modern teams need CI CD that adapts as fast as their product changes. Large YAML files grow unwieldy, selectors become brittle, and teams struggle to get fast feedback across parallel streams of work. You might have encountered slow pull request checks, long lived pipelines that try to do everything, or difficult maintenance when onboarding new microservices. These pain points compound as headcount and repo count rise, and they tend to show up as missed SLAs for builds, inconsistent deployment gates, and limited observability across concurrent runs. Bitbucket Pipelines now introduces a new way to define automation that addresses these realities with event driven rules that orchestrate multiple pipelines at once.

Bitbucket’s new triggers and conditions model brings separation of concerns to pipeline design. Instead of intertwining pipeline definitions with the rules that decide when they run, you can now define reusable custom pipelines and then wire them to events using a top level triggers property. Each trigger evaluates well defined condition blocks. When a condition is true, Bitbucket fans out all referenced pipelines to run concurrently. This model avoids the first match limitation of legacy selectors and better reflects how work really flows in modern teams.

Atlas Bench has been piloting this approach with clients who operate at scale. The result is clearer YAML, modular pipelines that can be developed independently, and faster feedback because matching pipelines run side by side. Teams also benefit from unique build statuses per pipeline, which improves visibility in pull requests and commit views. In this article, we summarize the shift, explain key capabilities, and offer a step by step guide to help you adopt triggers with confidence. We close with best practices, a migration checklist, and a path to keep pace with upcoming Bitbucket enhancements.

The Shift: Introducing Triggers

What triggers introduce

A top level triggers property lets you declare event driven rules that reference one or more custom pipelines. Each rule contains a condition expression and a list of pipelines. When an event fires, Bitbucket evaluates all conditions for that trigger type and runs all pipelines for each matching condition in parallel. This removes the first match constraint and gives you a clean separation between what a pipeline does and when it should run.
Conditions use logical operators and pattern matching through glob to express precise rules. You can combine logical and, or, greater than, less than, equality and negation, and you can match branch or tag names with glob. This allows expressive combinations such as hotfix branches that always run unit tests and security scans, or feature branches that run lint and unit tests but deploy only when merging to main.
Pull request pipelines gain more flexibility. You can now key off the destination branch along with the source branch. That means feature to main can run stricter gates than feature to develop. Each pipeline gets its own build status, which clarifies results in the pull request view and supports clear ownership for failures.
How triggers and conditions work together: You define one or more trigger types and attach condition blocks under each. For example, repository push and pull request push are supported today. Each condition evaluates environment variables such as Bitbucket branch and Bitbucket PR destination branch and, when true, launches the pipelines listed in that condition. This gives you a unit like rule set that can evolve without changing the internals of your pipelines. Conditions can be as simple or as advanced as you need. Teams often start with exact branch matches for main or release branches, then adopt glob based families like feature star or hotfix star. By expressing rules in a single place, you reduce duplication and make it easier to review changes in pull requests. The mental model is easy to explain to new contributors, which shortens onboarding time. Fan out is the default behavior. When multiple conditions match for an event, Bitbucket runs all pipelines from those conditions simultaneously, up to platform limits. This helps teams cut build feedback times by running unit tests, lint, security scans, and preview deployments in parallel instead of serializing them in a single long pipeline.
Benefits of event driven automation
- Faster feedback through parallel execution, improved observability through unique build statuses per pipeline, and reduced YAML sprawl due to separation of triggers from pipeline definitions. Teams report clearer ownership since each modular pipeline maps to a domain like tests, scans, or deploy. This clarity shows up in pull requests as multiple statuses that tell you exactly what passed and what failed.
- More control over pull request gates. With destination branch awareness in pull request triggers, you can gate merges into main more strictly than merges into develop. Parallel fan out lets you require a set of checks to pass together and avoids accidental green due to shared statuses. Teams can express security or compliance checks as distinct pipelines and track them independently.
- Better long term maintainability. Moving logic into conditions reduces duplication and allows pipeline definitions to remain reusable across repos via imports. The platform supports up to twenty conditions per trigger type and up to one hundred pipelines from a single trigger, which is usually ample for large organizations with dozens of checks per change.
Technical differences from traditional selectors
- Triggers versus first match selectors
  - Legacy selectors pick the first matching clause. Triggers evaluate all condition blocks and run all referenced pipelines for the matching blocks at once. This is a significant model upgrade for teams that need true fan out across independent checks and gates.
- Advanced logic with operators and glob patterns
  - Condition expressions add logical operators and glob to match real world branch and tag strategies. You can combine multiple variables such as branch, tag, and pull request destination to capture intent precisely without hacks or duplication in selectors. This reduces branching logic inside pipeline scripts and step conditions.
- Migration to the triggers syntax
  - Instead of branches or custom selectors, you define a top level triggers section and map events to pipelines. The change is straightforward and can be done gradually since the legacy model continues to run alongside triggers. If both match, both mechanisms run, which allows staged rollout and easy rollback if needed.

[Suggested image: "Annotated YAML snippet of Bitbucket Pipelines triggers and conditions"]

Woman viewing agile workflow diagram on large screen.

Key Features and Improvements

Top level triggers for workflow separation
- Clean separation between pipeline definitions and their execution rules. Pipelines live under the custom section, while triggers at the top level declare when to run them. This reduces entanglement and allows teams to share or import pipelines across repositories without rewriting when logic each time.
- Supports dynamic pipelines. Providers can return triggers and custom pipelines at runtime, enabling advanced generation strategies for monorepos or templated projects. This makes it practical to scale uniform practices across many services while keeping repo specific logic in code.
- Coexists with legacy selectors. You can adopt triggers incrementally without a big bang rewrite. If a repository relies on existing branch selectors for deploy behavior, you can move lint and tests to triggers first, validate outcomes, then complete the migration when ready.
Flexible condition logic with operators and glob
- Condition blocks understand logical operators and glob for pattern matching, which allows precise targeting across branch families. This lowers the need for custom scripts to infer intent from branch names. It also clarifies rules during code review because expressions are compact and readable in YAML.
- Practical examples include feature star for developer feedback, release star for promotion and tagging flows, and hotfix star for urgent patches. Teams can combine conditions to ensure that critical checks always run for sensitive paths. The same approach works for tags to control release builds or production deployments.
- Expressions are future proof because they separate the matching logic from pipeline steps. When your branching model evolves, you change the condition rather than duplicating changes inside each pipeline. This keeps configuration debt from growing unchecked as teams scale.
Parallel execution of multiple pipelines per event
- When a condition matches, Bitbucket runs all referenced pipelines in parallel. This takes advantage of available capacity to shorten wall clock time for feedback. In practice, many teams cut pull request check times by running unit tests, static analysis, and security scans side by side rather than serially.
- The platform supports up to one hundred pipelines initiated from a single trigger. Combined with up to twenty condition blocks per trigger type, this gives ample headroom for complex enterprises with many independent checks. It also makes progressive delivery patterns easier to express as separate pipelines that run in lockstep.
- Parallelism surfaces bottlenecks clearly. If a team sees one pipeline consistently trailing, they can invest in caching, test splitting, or optimized images. The visibility is a direct benefit of unique build statuses per pipeline.
Enhanced pull request pipeline capabilities
- Triggers can evaluate both source and destination branches for pull request events. This addresses a long standing gap for teams that gate certain merges more strictly than others. You can require deeper test suites or additional security checks on merges to main, while keeping developer feedback faster on merges to develop.
- Each parallel pipeline returns its own build status. This cleanly separates pass or fail signals and helps reviewers understand precisely what needs attention. No more shared or collapsed statuses that make it hard to see which check failed.
- Pull request feedback becomes more actionable. Teams can assign pipeline owners for test, lint, security, or deploy checks and ask the right people to fix failures quickly.
Unique build status for each pipeline
- Build status improvements ensure that every pipeline has a distinct status with a meaningful name. This change removes ambiguity when several pipelines run on the same commit or pull request. Contributors can now scan the list of statuses and know exactly which pipeline succeeded or failed.
- The change improves reporting for audits because you can show a complete set of independent checks. It also reduces the need for manual cross referencing between logs to find the failing component. Managers and leads get clearer dashboards without custom aggregation logic.
- Adoption is straightforward because this is a platform improvement that applies when you use triggers. You define meaningful names for your custom pipelines and those names flow through to commit and pull request views.

Comparing Old vs New Workflow Models

Traditional selector models were simple, but that simplicity led to limits at scale. The old approach evaluated clauses until the first match and then executed a single pipeline. Patterns were limited and could not express complex branch logic without workarounds in scripts. As teams added more checks, they often stuffed everything into one pipeline with serialized steps, which slowed feedback and made failures harder to triage. This made large YAML files fragile and difficult to modify without unintended side effects.

The triggers model flips that pattern. The platform evaluates all conditions for a given event and runs all referenced pipelines that match. Condition expressions support logical operators and glob, which allow precise and readable rules that match real branching strategies. Each pipeline runs in parallel where capacity allows and returns its own build status, so you get better performance and better observability. The result is a modular, scalable approach that keeps configuration neatly organized as your workflow evolves.

Here is a concise comparison you can share with your team.

Aspect	Traditional selectors	Triggers model
Matching behavior	First match runs one pipeline	All matching entries run in parallel
Condition complexity	Basic branch or tag patterns	Logical operators, comparisons, and glob
Pipelines per event	Single pipeline	Many pipelines, explicit list per condition
Observability	Shared or fewer statuses	Unique status per pipeline
Pull request targeting	Limited destination awareness	Source and destination based conditions

Example migration
- Old model
  - branches: main
  - Runs a single pipeline when pushing to main. Limited flexibility and no fan out. Harder to extend when you need multiple checks to run together.
- New model
  - triggers with a repository push rule that includes main runs unit tests, scan, and deploy pipelines in parallel. Each pipeline has its own build status and can be owned by a different team, which shortens time to fix when a check fails.

Practical Implementation Guide

Step by step setup
- Add a top level triggers section in bitbucket pipelines YAML. Declare trigger types such as repository push or pull request push. For each, add one or more condition blocks. Inside each block, list the custom pipelines to run when the condition evaluates to true. Keep pipeline definitions in the custom section.
- Start with a small target like feature branches to validate behavior. Move common checks such as unit tests and lint into custom pipelines, then reference them in triggers. Confirm that multiple pipelines appear and run in parallel, and validate that each produces a unique build status in pull requests.
- Gradually expand coverage. Add hotfix and release branches, then introduce destination aware pull request rules. Confirm that both legacy selectors and triggers can run side by side during migration. When ready, remove redundant selector clauses to reduce confusion.
Example YAML configuration
- Use this pattern to get started. It demonstrates repository pushes to main and pull request pushes from feature branches to main along with a hotfix rule.

triggers:
  repository-push:
    - condition: BITBUCKET_BRANCH == "main"
      pipelines:
        - unit-tests
        - scan
        - deploy
  pullrequest-push:
    - condition: glob(BITBUCKET_BRANCH, "feature/*") && BITBUCKET_PR_DESTINATION_BRANCH == "main"
      pipelines:
        - unit-tests
        - lint
    - condition: glob(BITBUCKET_BRANCH, "hotfix/*")
      pipelines:
        - unit-tests
pipelines:
  custom:
    unit-tests:
      - step:
          name: Unit Tests
          script:
            - npm ci
            - npm test
    lint:
      - step:
          name: Lint
          script:
            - npm run lint
    scan:
      - step:
          name: Scan
          script:
            - ./scan.sh
    deploy:
      - step:
          name: Deploy
          script:
            - ./deploy.sh

Only custom pipelines can be referenced by triggers. If you use imported pipelines, keep them under the custom section so triggers can invoke them. The platform supports up to twenty conditions per trigger type and up to one hundred pipelines initiated from a single trigger, which is ample for enterprise scale use.
Supported trigger types and usage tips
- Repository push covers commits to branches and creation of tags. Use it to run default checks on each push and to orchestrate release tagging flows.
- Pull request push covers creation and updates to pull requests. Pair it with destination branch rules to apply stricter checks for protected branches.
- Atlassian plans to expand trigger types beyond these two, so keep an eye on the documentation and community space for updates. Adopt a naming convention for custom pipelines that reads well in build statuses and pull request views, such as Tests Unit or Security Scan.
Migration steps from legacy selectors
- Inventory your existing selectors and list the pipelines they start. Identify shared logic that can be factored into custom pipelines.
- Create equivalent custom pipelines and define triggers that replicate your current behavior event by event. Keep legacy selectors in place while you validate triggers in a branch.
- Roll out incrementally. Start with low risk checks, validate parallel fan out and statuses, then migrate deploy flows. Remove obsolete selectors to prevent duplicate runs once you confirm parity.

Best Practices and Considerations

Modularize pipelines for composability
- Keep each pipeline focused on one concern such as tests, lint, security, build, or deploy. Give pipelines clear names that appear cleanly in build statuses. Use shared scripts and images to keep the implementation efficient and consistent across repos.
- Prefer small, reusable steps over monolithic scripts. This helps isolate failures and makes it easier to cache or parallelize heavy tasks like test suites.
- Treat pipelines as versioned building blocks. When used with imports, teams can roll out improvements across multiple repos with a single change to a shared definition.
Monitor with separate build statuses
- Unique statuses per pipeline improve triage speed. Use dashboards or pull request checks to enforce that all required pipelines pass.
- Establish ownership for each pipeline so alerts and failures reach the right team. Document remediation playbooks for common failures such as flaky tests or scan false positives.
- Use naming conventions that reflect responsibility such as Team Sec Security Scan or Team QA Unit Tests. This keeps pull request checks self explanatory for reviewers.
Gradual migration from legacy selectors
- Run both models side by side during the transition. Validate metrics like total runtime and failure rates to ensure triggers deliver the expected improvements.
- Move foundational checks first. Confirm parallel fan out and unique statuses work as planned. Then tackle deploy and release pipelines which often have more constraints.
- Retire selectors as you complete each phase to avoid duplicate runs and confusion in pull request statuses.
Limits and supported configurations
- Up to twenty conditions per trigger type and up to one hundred pipelines can be launched by a single trigger. Keep an eye on these limits as you scale.
- Triggers support dynamic pipelines and imported custom pipelines as long as they are defined under the custom section.
- The list of trigger types currently includes repository push and pull request push with more planned. Rely on the official documentation for updates and nuances in variables and evaluation order.
Common errors in modular pipelines and how to fix them
- Misconfigured pattern matching
  - Symptom: pipelines never start for feature branches.
  - Fix: validate glob expressions and confirm the correct environment variables are used in conditions. Example: glob BITBUCKET BRANCH, feature star.
- Overlapping triggers cause duplicate runs
  - Symptom: the same custom pipeline runs twice for one event.
  - Fix: audit all condition blocks across trigger types. Deconflict by tightening expressions or by removing legacy selector clauses once triggers are fully in place.
- Environment variable conflicts
  - Symptom: pipelines read stale or conflicting values across parallel runs.
  - Fix: namespace variables per pipeline, avoid reliance on mutable shared state, and pass values explicitly through artifacts or step outputs where needed.
- Leaky ownership and unclear status names
  - Symptom: reviewers cannot tell which pipeline failed or who should fix it.
  - Fix: adopt a naming convention that includes team or function and ensure alerting is mapped to pipeline ownership.

Looking Ahead

Triggers and conditions are just the start of a broader shift toward event driven workflows in Bitbucket Pipelines. Atlassian has signaled expanding the catalog of trigger types and bringing the condition syntax to individual steps for fine grained control. That means you will be able to combine top level orchestration with step level gating inside pipelines to achieve even more precise behavior. Teams should plan for this by keeping conditions readable and by keeping steps single purpose so that future conditions map cleanly to step intent. To stay current, follow the Pipeline start conditions documentation, subscribe to Bitbucket product news, and monitor the Pipelines community space. These channels will highlight new trigger types, syntax improvements, and best practices from other teams. As with any platform update, early adopters often share patterns that save hours of trial and error. Consider setting aside time each quarter to review your pipelines against new capabilities and to retire any workarounds that are no longer needed. Atlas Bench can help you design a roadmap tailored to your context. We start with an assessment of your current YAML, selectors, and pipeline runtime metrics. Then we propose a phased migration plan that balances risk and impact, with clear milestones like parallelizing tests, splitting scan steps, and implementing destination aware pull request gates. Along the way, we help you instrument unique build statuses to improve visibility for developers and stakeholders. The goal is a modular pipeline portfolio that scales with your product and your team.

Interested in learning more? Contact Atlas Bench to book a complimentary consultation with our Certified Atlassian Experts.

Start using Bitbucket Pipelines triggers today and get faster clearer build results.

undefined

Atlas Bench is an Atlassian Platinum Solution Partner with deep Cloud Specialization, helping Data Center customers move beyond migration and fully transform on the Atlassian Cloud Platform. We deliver Atlassian’s System of Work end to end through four collections: Strategy, Teamwork, Service, and Software, connecting planning to execution, aligning teams around outcomes, modernizing service delivery, and accelerating software development.

We are also recognized as an Atlassian World Class Software Development Partner of the Year (Americas), and we bring AI leadership to every engagement. By leveraging Rovo for automation and purpose built agents, we reduce manual work, unlock knowledge across tools, and speed up decision making so organizations realize measurable value faster in cloud.

Reimagining How you Structure Workflows in Bitbucket Pipelines