パイプライン構成の共有

Being able to share your YAML configuration in Bitbucket Pipelines allows you to define and share pipeline definitions within the same repository or workspace, which enables you to streamline your pipeline definitions by not having to repeatedly create each pipeline configuration.

Setup YAML sharing for your repository

1. Create a seperate YAML file within your repository, with the suffix *pipelines.yml. For the sake of the example below, we are placing this file at .bitbucket/shared-pipelines.yml. Put your Pipeline definition under the 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.

2. In your main bitbucket-pipelines.yml file, declare a name and slug for your Import Source under definitions: imports. When importing from within the same repository, the slug is simply the path to the file you want to import:

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.

Example of importing in a custom triggered pipeline:

Example of importing in a branch triggered pipeline for a branch named main

ワークスペースに対する YAML 共有の設定

1. Create a repository in the workspace where you’ll be adding the shared pipeline definition. For more information on creating a repository, refer to our Create a Git repository help document.

2. Create a separate YAML file (as with Step 1 above of sharing config within a repository) but note that pipelines shared between repositories must additionally have their export files declare export: true as a top-level property, to allow them to be shared across repositories. In the example below, we’re saving our shared configuration in a repository called shared-pipelines and have again saved this export file at .bitbucket/shared-pipelines.yml.

例

You can also use the main bitbucket-pipelines.yml configuration file of a repository to share pipelines under the definition section while also having pipelines configured as usual for that repository. It must also declare export: true in this case.

3. In the repository where you want to reuse the pipeline definition, you need to declare a name and slug for your import source. When importing from a seperate repository, the slug must specify the repo name and the git branch or tag reference of your target configuration. If you are using a custom filepath, you’ll need to specify this path, but if you are exporting from the bitbucket-pipelines.yml file of another repository, you do not need to specify the file path:

4. Further on in the same bitbucket-pipelines.yml, 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.

Example importing in custom triggered pipelines:

main というブランチでトリガーされるパイプラインでインポートする例

YAML 共有のフォーマットとルール

Import Sources

• An import source slug can use any of the three structures below:

  • {config-filepath} for imports within the same repository.

  • {repo-slug-of-exported-pipeline}:{branch/tag-to-import-from} for imports from the bitbucket-pipelines.yml file of a seperate repository.

  • {repo-slug-of-exported-pipeline}:{branch/tag-to-import-from}:{config-filepath} for imports from other files of a seperate repository.

• For imports from external repositories:

  • import ステートメントは常にターゲット ブランチの HEAD コミットを参照します。

  • import ステートメントは常にパイプライン名と完全に一致します。glob パターンの一致はサポートされていません。

  • If you want to reference your exported YAML at particular points in time for use in import statements, you can use a tag instead of the branch name to reference a specific commit rather than the HEAD if the branch.

• You can specify up to a maximum of 50 import sources in any one pipelines file.

Import Statements

• An import statement uses the following structure:

  • {pipeline-name}@{import-source-name}

Inline Import Statements (Legacy)

Previously, we have supported an inline syntax for import statements that does not use import source definitions. This structure only supports the use-case of sharing pipelines definitions from the bitbucket-pipelines.yml file of another repository. This format is still supported, but not recommended:

• {repo-slug-of-exported-pipeline}:{branch/tag-to-import-from}:{pipeline-name}

セキュリティとアクセス

Important note: Users can execute pipelines that import configurations from repositories they do not have direct access to, if that pipeline configuration has explicitly been declared as export: true.

• 共有パイプラインの構成は、ユーザーに使用されるものとは異なるアクセス制御スキームに従います。

• これは、共有パイプライン構成が保存されているリポジトリにユーザーがアクセスできず、権限の問題によりビルドが失敗するという複雑なシナリオを回避するためです。

• 外部パイプラインのインポートは、ユーザーではなくリポジトリが行うアクションとして扱われます。パイプラインは、export: true に設定されていれば、そのワークスペース内のすべてのリポジトリと「共有」されていると見なされます。

• パイプラインの .yaml ファイルを export: true でマークしたら、その内容はビルド ログなどから推測できる可能性があるため、同じワークスペース内のどのリポジトリでもそのパイプライン構成ファイルの内容を表示できると想定してください。

• Do not store sensitive information directly within the configuration of exported Pipelines. Always leverage variables and secrets for managing sensitive information as these values are inherited from the importing repository.

• 注: ユーザーが UI を介して共有パイプライン構成が保存されているソース ファイルに移動しようとしても、リポジトリを表示する権限がない場合、UI でそのソース ファイルを表示することはできません。

FAQ

質問: パイプライン構成を複数の異なるワークスペースで共有できますか? 共有パイプライン構成は自身のワークスペースの外からでも安全ですか?

回答: パイプライン構成の共有の範囲は、パイプライン構成のエクスポート元のワークスペースに限定されます。エクスポート対象のパイプライン構成には、同じワークスペースにないリポジトリからはアクセスできません。

質問: 別のリポジトリからインポートするときに、構成の安定性を維持するにはどうすればよいですか? エクスポート中のリポジトリの構成が変更され、ビルドが中断された場合はどうなりますか?

回答: パイプライン構成のインポート ステートメントでは、インポートを Git ブランチまたは Git タグに固定できます。

ブランチをターゲットにする場合、インポートは常にそのブランチの HEAD から取得されます。つまり、エクスポート対象パイプライン構成の最新バージョンを取得することになるため、アップストリームで変更が発生しても最新性を維持したい場合は、このモデルを使用することをお勧めします。

タグをターゲットにする場合、パイプライン構成は常に、固定されたタグが参照するコミットからインポートされます。これにより、ユーザーは静的なポイントインタイム参照を作成し、パイプライン構成をバージョン管理できます。将来的には、特定のコミットへの固定をユーザーが重視している場合には、そのサポートを追加する可能性があります。

質問: パイプラインを再実行して、最初に実行されてからインポート対象構成が変更されていた場合はどうなりますか?

回答: パイプライン全体が再実行された場合、再実行が実行された時点でパイプライン構成が再インポートされます。初回実行後に構成が変更された場合、実行される構成には新しい構成が反映されます。

質問: ステップを再実行して、最初に実行されてからインポート対象構成が変更されていた場合はどうなりますか?

回答: 1 つのステップを再実行した場合、そのステップの構成は、そのステップを最初に実行したときとまったく同じになります。繰り返しになりますが、これはパイプライン全体が再実行されたときの動作とは異なります。

質問: パイプライン構成をインポートするとき、変数とシークレットはどのように処理されますか?

回答: ビルドでインポート対象パイプライン構成を実行しているときを含め、インポート対象リポジトリのすべての変数とシークレットをビルドで使用できます。インポート対象構成のスクリプトで変数が使用されていて、インポートされたリポジトリによってそれらの変数値が利用可能になっている場合、それらの変数値はビルドで実行されます。

エクスポートするリポジトリの変数値は、リポジトリのインポートでは共有も再利用もされません。

注: 共有パイプライン構成を利用するカスタム パイプラインでの変数の使用には既知の制限があります。リポジトリで共有パイプライン構成をインポートし、それをカスタム パイプラインの一部として使用する場合、UI を介して実行時に指定された変数値はパイプライン実行に渡されません。代わりに、エクスポート対象パイプライン構成で指定されている既定値が使用されます。

Question: Can I import a pipeline from a different branch / reference of the same repository?

Answer: Yes. You can use the {repo-slug-of-pipeline}:{branch/tag-to-import-from}:{config-filepath} import source slug pattern to reference an export file on a different branch / tag than your main pipelines file, e.g. for a file on test of the repo same-repo:

Note: When making this type of reference, you will need to declare export: true in the export config file, despite being in the same repository.

質問: インポート対象パイプライン構成の要素 (ステップ サイズ、最大時間、イメージなど) をカスタマイズできますか?

Answer: Yes. Refer to our Dynamic pipelines help documentation for more details.

質問: ステップは 1 つずつ共有できますか?

Answer: Yes, individual steps can be shared. See the example provided in the following community post for more information: Share a step across pipelines.

質問: definitions セクションに保存されている場合、shared-pipeline の共有パイプライン構成をテストするにはどうすればよいですか?

回答: yaml アンカーを使用できます。例を以下に示します。

質問: 同じ名前の 2 つの異なるリポジトリで定義した場合、caches や services のような定義の優先順位はどうなりますか?

回答: グローバル オプション (image、clone、max-time、size、docker) と caches や services のような定義は、常にインポート リポジトリではなくエクスポート リポジトリから取得します。

たとえば、次のような .bitbucket/shared-pipelines.yml ファイルがリポジトリにあるとします。

And bitbucket-pipelines.yml importing this config can be configured as in the example provided below:

The default pipeline triggered in this repository will use docker and redis service defined in shared-pipeline, with redis:6 image for redis service. And my-custom-cache, my-custom-cache-without-key from the exporting file and not the importing file.

加えて、ステップ ビルド イメージは maven:3.9-eclipse-temurin-1 ではなく、atlassian/default-image:3 です。