Split your pipelines workflows across multiple files

As part of our focus on building features around team scale and performance, we are happy to announce that Bitbucket Pipelines now supports sharing of CI/CD configurations within a repository. This feature is now available as part of our Premium plan, and expands on the already introduced capability to share pipeline workflow configurations between separate repositories.

With this feature, your teams can modularize your pipelines definitions into dedicated files distributed around your repository, for use in your main bitbucket-pipelines.yml. This brings several benefits:

• Help break up large static pipelines files to reduce complexity overload.
• Re-use pipelines – define them once and refer to them whenever needed.
• Put pipelines definitions closer to the code that they manage – useful for monorepos where a pipeline may only be relevant to a particular module or service.

You can also use this new feature to import pipeline configuration from seperate repositories, either from their bitbucket-pipelines.yml file (as was possible previously) or from any YAML file in the repository (new!).

Here’s how it works.

Configuring your bitbucket-pipelines.yml file

In order to import pipelines configurations from, follow the following three steps:

1. Create a separate YAML file within your repository, with the suffix *pipelines.yml. For the sake of this example, we are placing this file at .bitbucket/shared-pipelines.yml. Put your Pipeline definition under definitions: pipelines section of the file.

All pipelines defined under the definitions: pipelines section will be exported and can be imported by the main pipelines file in that repository. Check out the example below.

definitions:
  pipelines:
    shared-pipeline:
      - step:
          name: "hello world"
          script:
            - echo hello

2. In your main bitbucket-pipelines.yml file, declare a named Import Source under definitions: imports that refers to your new exported pipelines file:

definitions:
  imports:
    shared-pipelines: .bitbucket/shared-pipelines.yml

3. Further on in the same bitbucket-pipelines.yml file, specify the import property in your pipeline, referencing the pipeline name and the name of the import source from which you want to import the shared pipeline configuration. You can use any of the pipelines start-conditions when importing a pipeline. In this example, we’re specifying a custom pipeline so it’s easy to trigger and test:

pipelines:
  custom:
    import-pipeline: 
      import: shared-pipeline@shared-pipelines

You can now trigger import-pipeline in your repository, and it will use the configuration that you’ve exported in .bitbucket/pipelines.yml

Cross-Repository Export

You can also make these shared pipelines available to other repositories in the same workspace, by declaring export: true at the root level of the shared config file:

export: true

definitions:
  pipelines:
    shared-pipeline:
      - step:
          name: "hello world"
          script:
            - echo hello

You can now import this pipeline into another repository. Assuming the above file is located at .bitbucket/shared-pipelines.yml in the shared-pipelines repo on branch main, you can import it into another repository’s bitbucket-pipelines.yml config file as below:

definitions:
  imports:
    shared-pipelines: shared-pipelines:main:.bitbucket/shared-pipelines.yml

pipelines:
  custom:
    import-pipeline: 
      import: shared-pipeline@shared-pipelines

Further Info

To learn more about how to set up config sharing, please refer to the support documentation.

We are working on some really exciting capabilities that are going to grant customers an unprecedented level of flexibility with sharing and configuring pipelines in the future, so stay tuned with our public roadmap.