bitbucket-pipelines.yml を設定する

The bitbucket-pipelines.yml file defines your Pipelines builds configuration. If you're new to Pipelines, refer to the Get started with Bitbucket Pipelines doc for more information. 

基本構成 

基本構成では、プロジェクトをビルドおよびデプロイするためのスクリプトを作成したり、キャッシュを構成してビルドを高速化したりするなどの設定を行えます。また、ステップごとに異なるイメージを指定して、パイプラインで実行しているアクション間で異なる依存関係を管理することもできます。

パイプラインはステップの一覧として構成され、構成ファイル内で複数のパイプラインを定義できます。次の図では、default セクションで設定されたパイプラインを確認できます。パイプライン構成ファイルには、特定のキーワードで識別される複数のセクションを含めることができます。

パイプラインに関連する yml ファイルの構成を表す図

はじめる前に

  • ファイルには少なくとも、1 つ以上のステップを構成する 1 つ以上のパイプライン セクションと、ステップ内に 1 つのスクリプトを含める必要があります。

  • 各ステップでは 4 GB のメモリを使用可能です。

  • 1 つのパイプラインに、最大 100 のステップを含めることができます。

  • パイプラインの各ステップは、別の Docker コンテナを実行します。必要に応じて別のイメージを選択することで、各ステップで別のタイプのコンテナを使用できます。

手順 

1. yaml ファイルを構成するには、Bitbucket でリポジトリに移動し、左側のナビゲーション バーで [Pipelines] を選択します。 Bitbucket のインターフェイスを使用せずに yaml ファイルを構成することもできます。

2. 言語を選択します。

注意: Pipelines は、任意の言語で記述されたプロジェクトのビルドまたはデプロイ用に構成できます。言語ガイド

3. イメージを選択します。

ファイルには少なくとも、1 つ以上のステップを構成する 1 つ以上のパイプライン セクションと、ステップ内に 1 つのスクリプトを含める必要があります。

上の図に示された各セクションの説明は次のとおりです。


default

他のセクションのパイプライン定義に一致しないすべてのブランチのパイプライン定義が含まれます。

default パイプラインは、ブランチ固有のパイプラインが定義されている場合を除き、リポジトリへのプッシュのたびに実行されます。ブランチ パイプラインは branch セクションで定義できます。

: default パイプラインはタグまたはブックマークでは実行されません。


branches 

すべてのブランチ固有のビルド パイプラインのセクションを定義します。このセクションの名前または表現は、Git リポジトリのブランチと一致します。

リポジトリで特定のブランチをビルドするためのパイプライン構成の詳細については、「ブランチ ワークフロー」を参照してください。

 glob パターンのチート シートを確認してブランチ名を定義します。


tags

すべてのタグ固有のビルド パイプラインを定義します。このセクションの名前または表現は、Git リポジトリのタグや注釈つきタグと照合されます。

 glob パターンを確認してタグを定義します。


bookmarks

すべてのブックマーク固有のビルド パイプラインを定義します。

glob パターンのチート シートを確認してブックマークを定義します。


プル リクエスト

リポジトリ内から開始されたプル リクエストでのみ実行される特別なパイプライン。これによって、実行前に宛先ブランチを作業ブランチにマージします。フォークされたリポジトリからのプル リクエストは、パイプラインをトリガーしません。マージが失敗すると、パイプラインが停止します。

プル リクエスト パイプラインは定義されている任意のブランチおよびデフォルト パイプラインに加えて実行されるため、定義が重複すると 2 つのパイプラインが同時に実行される場合があります。

If you already have branches in your configuration, and you want them all to only run on pull requests, replace the keyword branches with pull-requests.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 pipelines: pull-requests: '**': #this runs as default for any branch not elsewhere defined - step: script: - ... feature/*: #any branch with a feature prefix - step: script: - ... branches: #these will run on every push of the branch staging: - step: script: - ...

glob パターンのチート シートを確認してプル リクエストを定義します。


runs-on

Pipelines でランナーを使用するには、ステップに runs-on パラメーターを追加すると、必要なすべてのラベルのある次に利用可能なランナーで実行されます。一致するすべてのランナーがビジー状態の場合、1 つのランナーが再び利用可能になるまでステップは待機します。リポジトリ内にすべてのラベルに一致するオンライン ランナーがない場合、ステップは失敗します。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 pipelines: custom: customPipelineWithRunnerStep: - step: name: Step 1 runs-on: - 'self.hosted' - 'my.custom.label' script: - echo "This step will run on a self hosted runner with 128 GB of memory."; - step: name: Step 2 script: - echo "This step will run on Atlassian's infrastructure as usual.";

custom 

Bitbucket Cloud インターフェイスから手動またはスケジュール実行でのみトリガーできるパイプラインを定義します。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 image: node:10.15.0 pipelines: custom: # Pipelines that are triggered manually sonar: # The name that is displayed in the list in the Bitbucket Cloud GUI - step: script: - echo "Manual triggers for Sonar are awesome!" deployment-to-prod: # Another display name - step: script: - echo "Manual triggers for deployments are awesome!" branches: # Pipelines that run automatically on a commit to a branch staging: - step: script: - echo "Auto pipelines are cool too."

詳細は、「パイプラインを手動で実行する」を参照してください。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 image: node:10.15.0 pipelines: default: - step: name: Build and test script: - npm install - npm test tags: # add the 'tags' section release-*: # specify the tag - step: # define the build pipeline for the tag name: Build and release script: - npm install - npm test - npm run release branches: staging: - step: name: Clone script: - echo "Clone all the things!"


高度な設定

サービスを実行し、テストを並行して実行するには、詳細オプションを使用します。手動ステップの構成や各ステップの最大時間の設定などが行えるほか、2 倍のステップを構成して 8 GB のメモリを使用することもできます。

はじめる前に

  • パイプラインの YAML ファイルには、キーワードと 1 つ以上のステップを含むセクションが少なくとも 1 つ必要です。

  • 各ステップでは 4 GB のメモリを使用可能です。

  • 1 つのパイプラインに、最大 100 のステップを含めることができます。

  • パイプラインの各ステップは、別の Docker コンテナを実行します。必要に応じて別のイメージを選択することで、各ステップで別のタイプのコンテナを使用できます。

グローバル構成オプション

yaml ファイルのグローバル構成オプションを表す図

オプションのステップの構成を示す図

グローバル構成オプションに関連するキーワードの一覧とその説明


variables

[カスタム パイプラインのみ] パイプラインの起動時に提供される変数が含まれます。変数を有効化するには、パイプラインを実行するときに入力するカスタム パイプラインの下に変数を定義します。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 pipelines: custom: custom-name-and-region: #name of this pipeline - variables: #list variable names under here - name: Username - name: Role default: "admin" # optionally provide a default variable value - name: Region default: "ap-southeast-2" allowed-values: # optionally restrict variable values - "ap-southeast-2" - "us-east-1" - "us-west-2" - step: script: - echo "User name is $Username and role is $Role" - echo "and they are in $Region"

[ブランチ] > ⋯ > [ブランチのパイプラインを実行] > [カスタム] の順にアクセスし、カスタム パイプラインを実行する場合、変数の値を設定してカスタム パイプラインを実行できます。

キーワード variables は、サービスの定義の一部にすることもできます。

name  

キーワード名が yaml の variables セクションにある場合、このキーワードはカスタム パイプラインを実行するときに追加または更新できる変数を定義します。Pipelines は、キーワードをステップ内で使用できます。

default

キーワードのデフォルトが yaml の変数セクションにある場合は、デフォルトの変数値が定義されます。デフォルトの変数は、次の場合で使用されます。

指定可能な値

キーワード「allowed-values」が yaml ファイルの変数セクションにある場合は、変数に割り当てられる値のリストを定義します。「allowed-values」が指定された場合は、デフォルト値も指定する必要があります。

parallel

並行ステップを使用すると、一連のステップを同時に実行して迅速にビルドしてテストできます。ステップを平行にした場合もパイプラインが使用するビルドの合計時間数は変わりませんが、結果はより早く表示されます。

パイプライン定義に設定できるステップの合計数は、並列または単独のどちらで実行されているかにかかわらず、100 に制限されます。

同時に実行するステップをインデントで定義します。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 pipelines: default: - step: # non-parallel step name: Build script: - ./build.sh - parallel: # these 2 steps will run in parallel - step: name: Integration 1 script: - ./integration-tests.sh --batch 1 - step: name: Integration 2 script: - ./integration-tests.sh --batch 2 - step: # non-parallel step script: - ./deploy.sh

並行ステップについて詳細をご確認ください

step

ビルドの実行単位を定義します。ステップは bitbucket-pipelines.yml ファイルで読み込まれる順序で実行されます。1 つのパイプラインに、最大 100 のステップを含めることができます。

パイプラインの各ステップは個別の Docker コンテナを起動し、script で構成されたコマンドを実行します。各ステップは次のように構成できます。

  • 別の Docker イメージを使用する。

  • カスタムの max-time を構成する。

  • 固有のキャッシュとサービスを使用する。

  • 後のステップで使用できるアーティファクトを生成する。

  • クローン セクションを置くことができます。

ステップは、実行前に手動トリガーを待機するように構成できます。ステップを手動として定義するには、bitbucket-pipelines.yml ファイルのステップに trigger: manual を追加します。手動ステップには次のような特徴があります。

  • 設定されている順序でのみ実行できます。手動ステップをスキップすることはできません。

  • 前の手順が正常に完了した場合にのみ実行できます。

  • リポジトリへの書き込みアクセス権限を持つユーザーのみがトリガーできます。

  • Pipelines の Web インターフェイス経由でトリガーされます。

ビルドが手動ステップとアーティファクトの両方を使用している場合、アーティファクトは、そのアーティファクトを生成した手順の完了後 14 日間保存されます。この期間が過ぎるとアーティファクトは期限切れとなり、パイプラインでは以降のあらゆる手動ステップを実行できなくなります。

: パイプラインの最初ステップを手動ステップに設定することはできません。

name

ステップの名前を定義し、ステップで実行される内容を可視化します。

image

Bitbucket Pipelines では、Docker コンテナを使用してビルドを実行します。

  • You can use the default image (atlassian/default-image:1) provided by Bitbucket or define a custom image. You can specify any public or private Docker image that isn't hosted on a private network.

  • イメージは、グローバルまたはステップ レベルで定義できます。ブランチ レベルでは定義できません。

イメージを指定するには、次のイメージを使用します: <your_account/repository_details>:<tag>

イメージの使用および作成の詳細については、「Docker イメージをビルド環境として使用する」を参照してください。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 pipelines: default: - step: # non-parallel step name: Build script: - ./build.sh - parallel: # these 2 steps will run in parallel - step: name: Integration 1 script: - ./integration-tests.sh --batch 1 - step: name: Integration 2 script: - ./integration-tests.sh --batch 2 - step: # non-parallel step script: - ./deploy.sh

trigger

Specifies whether a step will run automatically or only after someone manually triggers it. You can define the trigger type as manual or automatic. If the trigger type is not defined, the step defaults to running automatically. The first step cannot be manual. If you want to have a whole pipeline only run from a manual trigger then use a custom pipeline.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 pipelines: default: - step: name: Build and test image: node:10.15.0 script: - npm install - npm test - npm run build artifacts: - dist/** - step: name: Deploy image: python:3.7.2 trigger: manual script: - python deploy.py

deployment

Sets the type of environment for your deployment step, and it is used in the Deployments dashboard. The Valid values are: test, staging, or production.

The following step will display in the test environment in the Deployments view.

1 2 3 4 5 6 - step: name: Deploy to test image: aws-cli:1.0 deployment: test script: - python deploy.py test

size

You can allocate additional memory to a step, or to the whole pipeline. By specifying the size of 2x, you'll have double the memory available, for example 4 GB memory → 8 GB memory.

現時点では、有効なサイズは 1x および 2x です。

2x パイプラインは、倍のビルド時間数 (分) を使用します。

例: 1 つのステップのサイズをオーバーライドする

1 2 3 4 5 6 7 8 9 pipelines: default: - step: script: - echo "All good things..." - step: size: 2x # Double resources available for this step. script: - echo "Come to those who wait."

script 

連続して実行されるコマンドの一覧が含まれています。スクリプトは、ステップに記載された順序で実行されます。大規模なスクリプトは個別のスクリプト ファイルに移動し、それらを bitbucket-pipelines.yml から呼び出すことをおすすめします。

pipe

パイプは多くの作業をバックグラウンドで実行して、複雑なタスクを容易にします。つまり、ユーザーは使用したいパイプを選択し、必要な変数を指定するだけです。パイプのリポジトリで、実行中のコマンドを確認できます。パイプの詳細はこちらをご覧ください

Opsgenie にメッセージを送信するパイプは、次の例のようになります。

1 2 3 4 5 6 7 8 9 10 11 12 pipelines: default: - step: name: Alert Opsgenie script: - pipe: atlassian/opsgenie-send-alert:0.2.0 variables: GENIE_KEY: $GENIE_KEY MESSAGE: "Danger, Will Robinson!" DESCRIPTION: "An Opsgenie alert sent from Bitbucket Pipelines" SOURCE: "Bitbucket Pipelines" PRIORITY: "P1"

独自のパイプを作成することもできます。その場合、次の構文を使用して Docker ベースのパイプを指定できます。

1 pipe: docker://<DockerAccountName>/<ImageName>:<version>

after-script

Commands inside an after-script section will run when the step succeeds or fails. This could be useful for clean up commands, test coverage, notifications, or rollbacks you might want to run, especially if your after-script uses the value of BITBUCKET_EXIT_CODE.

: after-script セクションのコマンドが失敗した場合、次のようになります。

  • そのセクションでは以降のコマンドは実行されません。

  • ステップに対して報告されているステータスには影響しません。

1 2 3 4 5 6 7 8 9 pipelines: default: - step: name: Build and test script: - npm install - npm test after-script: - echo "after script has run!"

artifacts

ステップで生成され、次のステップで共有できるファイル (レポートや JAR ファイルなど) を定義します。

アーティファクトは glob パターンを使用して定義できます。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 pipelines: default: - step: name: Build and test image: node:10.15.0 script: - npm install - npm test - npm run build artifacts: - dist/** - step: name: Deploy to production image: python:3.7.2 script: - python deploy-to-production.py

詳細については、「アーティファクトをステップで使用する」を参照してください。

options

すべてのパイプラインに適用するグローバル設定を含みます。ここで使用する主なキーワードは max-time です。

max-time

ステップを実行できる最大時間 (分単位) を、グローバルまたはステップの各レベルで定義できます。0 より大きく 120 より小さい整数を使用します。

1 2 3 4 5 6 7 8 9 10 11 12 13 options: max-time: 60 pipelines: default: - step: name: Sleeping step script: - sleep 120m # This step will timeout after 60 minutes - step: name: quick step max-time: 5 script: - sleep 120m #this step will timeout after 5 minutes

max-time を指定しない場合、既定で 120 に設定されます。

clone

リポジトリのクローンをコンテナに作成した時の設定を含みます。ここでの設定には以下が含まれます。

  • LFS - Git lfs のサポート

  • depth - Git クローンの深度

  • Setting  enabled setting to false will disable git clones.

lfs (GIT のみ)

Enables the download of LFS files in your clone. If defaults to false if not specified. Note that the keyword is supported only for Git repositories.

1 2 3 4 5 6 7 8 9 clone: lfs: true pipelines: default: - step: name: Clone and download script: - echo "Clone and download my LFS files!"

depth (Git のみ)

すべてのパイプラインの Git クローンの深度を定義します。注意: このキーワードは Git リポジトリでのみサポートされます。

深度を指定する際は、0 より大きい整数を使用します。フル クローンには full を使用します。Git クローンの深度を指定しない場合、既定で 50 に設定されます。

1 2 3 4 5 6 7 8 9 clone: depth: 5 # include the last five commits pipelines: default: - step: name: Cloning script: - echo "Clone all the things!"

enabled

By default, enabled is set to ‘true’. Setting enabled to ‘false’ will disable git clones. If you don’t need access to the source code in your build, you may want to disable clones which will improve the build time and save build minutes.

1 2 3 4 5 6 7 8 9 pipelines: default: - step: name: No clone clone: enabled: false script: - echo "I don't need to clone in this step!"

oidc

Enables the use of OpenID Connect with Pipelines and your resource server. The oidc value must be set to true to set up and configure OpenID Connect.

1 2 3 4 5 6 image: amazon/aws-cli pipelines: default: - step: oidc: true

条件

This allows steps to be executed only when a condition or rule is satisfied. Currently, the only condition supported is changesets. Use changesets to execute a step only if one of the modified files matches the expression in includePaths. The file match pattern specified in the includePaths is relative to the $BITBUCKET_CLONE_DIR directory.

考慮される変更内容は次のとおりです。

In a pull-request pipeline, all commits are taken into account, and if you provide an includePathlist of patterns, a step will be executed when at least one commit change matches one of the conditions. The format for pattern matching follows the glob patterns.


次の例では、step1 はパイプラインをトリガーしたコミットで、path1 ディレクトリ内の XML ファイルまたは path2 で入れ子になったディレクトリ構造の任意のファイルに変更が含まれる場合にのみ実行します。

1 2 3 4 5 6 7 8 9 10 11 12 - step: name: step1 script: - echo "failing paths" - exit 1 condition: changesets: includePaths: # only xml files directly under path1 directory - "path1/*.xml" # any changes in deeply nested directories under path2 - "path2/**"

ファイルに変更がない場合、ステップはスキップされ、パイプラインが成功します。

その他の種類のパイプラインでは最後のコミットのみが考慮されます。たとえば、規定の main ブランチにおけるプル リクエストのマージ コミットでは問題ありませんが、同時に複数のコミットをブランチにプッシュする場合や指定されたブランチに複数回プッシュする場合は、失敗しているステップが次回の実行でスキップされるために、失敗しているパイプラインが緑色に変わる直感的でない挙動が生じることがあります。

条件とマージ チェック

プル リクエストのマージ チェックでビルド結果の成功が共通している場合、ステップの条件によってブランチ パイプラインの誤検知が発生する可能性がある点に注意してください。ビルド結果の一貫性がもっとも重要である場合は、条件の完全な回避を検討するか、プルリクエスト パイプラインのみを使用します。

definitions

パイプライン構成の別の場所で使用されているリソースを定義します。リソースには、以下が含まれる可能性があります。

services

Pipelines はサービス用に別々の docker コンテナをスピンアップできます。これによりビルドが高速化され、サービスを容易に編集できるようになります。

完全に構成されたサービスの例
MySQL のサービス コンテナー (既定のデータベース pipelines、ユーザー root、パスワード let_me_in を含む、localhost:3306 で利用可能な空のデータベース) が必要な場合は、次のように追加できます。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 definitions: services: mysql: image: mysql variables: MYSQL_DATABASE: pipelines MYSQL_ROOT_PASSWORD: let_me_in pipelines: default: - step: services: - docker - mysql script: - ... definitions: services: mysql: mysql:latest

サービスの使用方法の詳細をご確認ください

キャッシュ

ビルドの各ステップでインターネットから依存関係を再度ダウンロードすると、長い時間がかかる場合があります。キャッシュを使用すると、これらの依存関係はサーバーへ 1 回ダウンロードされ、ビルドのたびにローカルに読み込まれます。

1 2 3 4 5 6 7 8 9 10 definitions: caches: bundler: vendor/bundle pipelines: default: - step: caches: - npm script: - npm install


YAML アンカー

YAML アンカー - yaml を分割して定義して使いやすくする方法。「YAML アンカー」を参照してください。

 

その他のヘルプ