bitbucket-pipelines.yml を設定する

Pipelines のビルド構成は bitbucket-pipelines.yml ファイルで定義できます。Pipelines を初めて利用される場合は、Bitbucket Pipelines を使い始めるのドキュメントをご確認ください。 

基本構成 

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

パイプラインはステップの一覧として構成され、構成ファイル内で複数のパイプラインを定義できます。次の図では、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 つのパイプラインが同時に実行される場合があります。

構成にすでにブランチがあり、すべてのブランチをプル リクエストでのみ実行したい場合、キーワード branchespull-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 pipelines: custom: custom-name-and-region: #name of this pipeline - variables: #list variable names under here - name: Username - name: Region default: "ap-southeast-2" - step: script: - echo "User name is $Username" - echo "and they are in $Region"

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

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

name  

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

default

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

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 コンテナを起動し、スクリプトで構成されたコマンドを実行します。各ステップは次のように構成できます。

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

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

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

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

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

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

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

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

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

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

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

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

name

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

image

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

  • Bitbucket が提供する既定のイメージ (atlassian/default-image:2) を使用するか、カスタム イメージを定義できます。プライベート ネットワークでホストされていない、任意の公開または非公開の Docker イメージを指定できます。

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

イメージを指定するには、次のイメージを使用します: <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

ステップを自動で実行するか、誰かが手動でトリガーした後にのみ実行するかを指定します。トリガーのタイプは manual または automatic に設定できます。トリガーのタイプが定義されていない場合、初期設定ではステップは自動で実行されます。最初のステップを手動にはできません。パイプライン全体を手動トリガーからのみ実行する場合は、カスタム パイプラインを使用します。

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

[Deployments (デプロイ)] ダッシュボードで使用されるデプロイ ステップの環境タイプを設定します。有効な値は、teststaging、または production です。

次のステップが Deployments ビューの test 環境に表示されます。

有効な値: teststaging、または production

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

size

ステップまたはパイプライン全体に、追加メモリを割り当てられます。サイズ 2x を指定すると、利用可能なメモリが倍増します (例: 4GB メモリ → 8GB メモリ)。

現時点では、有効なサイズは 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

after-script セクション内のコマンドは、ステップが成功したか失敗した時に実行します。after-script が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 クローンの深度

  • enabled を false に設定すると、Git クローンが無効になります。

oidc

Pipelines とリソース サーバーで OpenID Connect を使用できるようにします。oidc の値を、true に設定する必要があります。その後、OpenID Connect を設定します。

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

lfs (GIT のみ)

クローンでの LFS ファイルのダウンロードを有効にします。指定しない場合は、初期設定では false に設定されます。注意: このキーワードは Git リポジトリでのみサポートされます。

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

enabled の設定を false にすると、Git クローンが無効になります。

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!"

条件

条件またはルールを満たす場合にのみステップが実行されます。現在サポートされている条件は「チェンジ セット」のみです。いずれかの変更済みファイルが includePaths の表現と一致する場合のみ、チェンジ セットを使用してステップを実行します。

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

プル リクエスト パイプラインではすべてのコミットが考慮され、includePath パターン一覧を提供すると、1 つ以上のコミットの変更がいずれかの条件に一致する場合にステップが実行されます。パターン マッチングの形式は、glob パターンに従います。

以下の例では、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 アンカー」を参照してください。

 

最終更新日 2021年09月29日)
次でキャッシュ 9:05 PM on Oct 21, 2021 |

その他のヘルプ