[New Premium feature] Share pipeline workflow configurations across your repositories

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 across repositories. This feature is now available as part of our Premium plan.

With this feature, your teams can create centralized pipelines yml workflows and import that workflow to other repositories in your workspace. This brings several benefits:

• Consistent workflows across your team that are compliant with your organization’s policies.
• Reduce copying and pasting yml from one repo to another.
• Developers can focus more on coding than configuring workflows.
• Less error-prone.

Here’s how it works.

Configuring your bitbucket-pipelines.yaml files

In order to share your pipeline configurations, follow the following three steps:

First, create a repository within your workspace for the shared pipeline definition, for this example, we're going to call our repo shared-pipeline.

Note: Pipeline configurations can be shared from any repository, they do not need to be in a dedicated repository. We are just using a dedicated repository here for the sake of example.

Next, create a bitbucket-pipelines.yml with export: true at the top level of the file and put your Pipeline definition under definitions -> pipelines section of the file, here is an example for a pipeline called shared-pipeline-config:

export: true

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

All pipelines defined under definitions -> pipelines section will be exported and can be imported by other repositories in the same workspace.

Finally, in the repository where you want to reuse the pipeline definition (let's call it importing-repo), you need to use the import attribute in your Pipeline at the location you want to import the shared pipeline. In the example, we are importing the config from shared-pipeline-config to be used as the config for importing-pipeline:

pipelines:
  custom:
    importing-pipeline: 
      import: shared-pipeline:master:shared-pipeline-config

You can now trigger importing-pipeline in importing-repo and it will use the configuration from the exported pipeline config.

To learn more about how to set it up please refer to the support documentation.

Please note:

To use import pipeline configurations, users can execute pipelines that import configurations from repositories they do not have read permissions for in Bitbucket Cloud if that Pipeline configuration has explicitly been declared as export: true. For more details about security and access regarding sharing pipeline configurations, please refer to the corresponding sections in the support documentation.

FAQ:

Question: Can I share pipeline configurations across different workspaces? Are my shared pipeline configurations secure from outside my workspace?

Answer: Pipeline config sharing is scoped to the workspace in which pipeline configurations are set to be exported from. Exported pipeline configurations cannot be accessed by repositories that are not in the same workspace.

---

Question: How do I maintain the stability of the configuration when importing from another repo? What happens if the config in the exporting repo changes and breaks my build?

Answer: Pipelines config import statements support pinning your import to either a Git branch or a Git tag.

When targetting a branch, the import will always pull from the HEAD of that branch, meaning you will get the latest version of the exported pipeline configuration, we recommend using this model if you want to maintain currency with any upstream changes.

When targeting a tag, the pipeline configuration will always be imported from the commit referenced by the tag pinned. This allows customers to create static point-in-time references and version their pipeline configurations. In the future, we may add support for pinning to specific commits if this is something users see value in.

---

Question: What happens if a pipeline is rerun and the imported configuration has changed since the first time it was run?

Answer: If the entire pipeline is rerun, the pipeline configuration will be reimported at the point in time that the rerun executes. If the configuration has changed since the initial run, the executed configuration will reflect the new configuration.

---

Question: What happens if a step is rerun and the imported configuration has changed since the first time it was run?

Answer: If a single step is rerun, the configuration for that step will be exactly the same as the first time the step was run. To reiterate, this is different to the behavior when the entire pipeline is rerun.

---

Question: How are variables and secrets handled when importing pipeline configurations?

Answer: All the variables and secrets from the importing repository will be available to the build, including when that build is executing an imported pipeline configuration. If the imported configuration utilizes variables in its scripts, and those variable values are made available by the repository it was imported by, then those variable values will be executed in the build.

Variable values from the exporting repository are not shared or reused in importing repositories.

Note: There is a known limitation with using variables in Custom Pipelines that utilize a shared pipeline configuration. If a repository imports a shared pipeline configuration and uses it as part of a Custom Pipeline, variable values specified at runtime via the UI will not pass to the pipeline execution. Instead, the default values specified in the exported Pipeline configuration will be used instead.

---

Question: Can I customize elements of the imported Pipeline config like Step Size, Max Time, Image, etc?

Answer: The only way to configure the imported Pipeline Configuration is via Variables and Secrets.

---

Question: Can individual steps be shared?

Answer: Not currently, sharing is limited to entire Pipeline Configurations. Depending on customer demand, we may consider adding support for Step sharing in a future release.

---

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.