Bitbucket Cloud の使用を開始する
Bitbucket Cloud を初めてお使いですか? 新規ユーザー用のガイドをご利用ください。
bitbucket-pipelines.yml を設定する
bitbucket-pipelines.yml ファイルにより、Pipelines ビルド設定が定義されます。パイプラインを初めて使用する場合は、「Bitbucket Pipelines を使い始める」ドキュメントを参照してください。
基本構成
基本構成では、プロジェクトをビルドおよびデプロイするためのスクリプトを作成したり、キャッシュを構成してビルドを高速化したりするなどの設定を行えます。また、ステップごとに異なるイメージを指定して、パイプラインで実行しているアクション間で異なる依存関係を管理することもできます。
パイプラインはステップの一覧として構成され、構成ファイル内で複数のパイプラインを定義できます。次の図では、default セクションで設定されたパイプラインを確認できます。パイプライン構成ファイルには、特定のキーワードで識別される複数のセクションを含めることができます。
はじめる前に
ファイルには少なくとも、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 つのパイプラインが同時に実行される場合があります。
構成にすでにブランチがあり、すべてのブランチをプル リクエストでのみ実行したい場合、キーワード branches を 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 コンテナを実行します。必要に応じて別のイメージを選択することで、各ステップで別のタイプのコンテナを使用できます。
グローバル構成オプション
グローバル構成オプションに関連するキーワードの一覧とその説明
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 の変数セクションにある場合は、デフォルトの変数値が定義されます。デフォルトの変数は、次の場合で使用されます。
パイプラインが API を介してトリガーされ、パイプライン変数の値が指定されていない場合。
指定されている場合は、スケジュールされたパイプラインがデフォルトの変数値を使用します。
指定可能な値
キーワード「allowed-values」が yaml ファイルの変数セクションにある場合は、変数に割り当てられる値のリストを定義します。「allowed-values」が指定された場合は、デフォルト値も指定する必要があります。
parallel
並行ステップを使用すると、一連のステップを同時に実行して迅速にビルドしてテストできます。ステップを平行にした場合もパイプラインが使用するビルドの合計時間数は変わりませんが、結果はより早く表示されます。
パイプライン定義に設定できるステップの合計数は、並列または単独のどちらで実行されているかにかかわらず、100 に制限されます。
Define the parallel property with a list of steps to run concurrently:
例
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
pipelines:
default:
- step: # non-parallel step
name: Build
script:
- ./build.sh
- parallel: # these 2 steps will run in parallel
steps:
- 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.shFor details on using parallel steps, see Set up or run parallel steps.
fail-fast
fail-fast can be applied to all parallel steps or to a specific step in a parallel group:
If a step has fail-fast: false, then the step can fail without the whole parallel group stopping.
If a step has fail-fast: true, then the whole parallel group will stop if the step fails.
fail-fast is set to false by default.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
pipelines:
default:
- step:
name: Build
script:
- ./build.sh
- parallel:
# these option alows to force stop all running steps if any step fails
fail-fast: true
steps:
- step:
name: Integration 1
script:
- ./integration-tests.sh --batch 1
- step:
name: Integration 2
script:
- ./integration-tests.sh --batch 2
- step:
# option can be disabled for a step
# and its failure won't stop other steps in a group
fail-fast: false
name: Upload metadata
script:
- ./upload-metadata.shFor details on using fast fail for parallel steps, see Set up or run parallel steps — Failing fast.
step
ビルドの実行単位を定義します。ステップは bitbucket-pipelines.yml ファイルで読み込まれる順序で実行されます。1 つのパイプラインに、最大 100 のステップを含めることができます。
パイプラインの各ステップは個別の Docker コンテナを起動し、script で構成されたコマンドを実行します。各ステップは次のように構成できます。
別の Docker イメージを使用する。
カスタムの max-time を構成する。
固有のキャッシュとサービスを使用する。
後のステップで使用できるアーティファクトを生成する。
クローン セクションを置くことができます。
ステップは、実行前に手動トリガーを待機するように構成できます。ステップを手動として定義するには、bitbucket-pipelines.yml ファイルのステップに trigger: manual を追加します。手動ステップには次のような特徴があります。
設定されている順序でのみ実行できます。手動ステップをスキップすることはできません。
前の手順が正常に完了した場合にのみ実行できます。
リポジトリへの書き込みアクセス権限を持つユーザーのみがトリガーできます。
Pipelines の Web インターフェイス経由でトリガーされます。
ビルドが手動ステップとアーティファクトの両方を使用している場合、アーティファクトは、そのアーティファクトを生成した手順の完了後 14 日間保存されます。この期間が過ぎるとアーティファクトは期限切れとなり、パイプラインでは以降のあらゆる手動ステップを実行できなくなります。
注: パイプラインの最初ステップを手動ステップに設定することはできません。
Stage
ステージを使用すると、共有プロパティを持つパイプライン ステップをグループ化できます。たとえば、ステージを使用して、デプロイに必要なステップ (アプリのデプロイやデプロイの成否の確認など) をグループ化できます。
例 — ステージ
1
2
3
4
5
6
7
8
9
10
11
12
13
pipelines:
default:
- stage:
name: Build and test
steps:
- step:
name: Build app
script:
- sh ./build-app.sh
- step:
name: Run unit tests
script:
- sh ./run-tests.shパイプライン ステージの作成と使用については、「ステージ」を参照してください。
name
ステップの名前を定義し、ステップで実行される内容を可視化します。
image
Bitbucket Pipelines では、Docker コンテナを使用してビルドを実行します。
Bitbucket が提供する既定のイメージ(atlassian/default-image:1) を使用するか、カスタム イメージを定義できます。プライベート ネットワークでホストされていない、任意の公開または非公開の 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.shtrigger
ステップを自動で実行するか、誰かが手動でトリガーした後にのみ実行するかを指定します。トリガーのタイプは 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.pydeployment
[デプロイ] ダッシュボードを整理するために使用されるデプロイ ステップの環境タイプを設定します。既定の環境は、test、staging、または production です。デプロイ環境の作成と設定に関する詳細は「デプロイのセットアップと監視」をご参照ください。
デプロイ環境のステップを設定するには、環境名を含めます。たとえば、production env 1 という名前のデプロイ環境にステップを追加するには、次の手順に従います。
例
1
2
3
4
5
6
- step:
name: Deploy to test
image: aws-cli:1.0
deployment: production env 1
script:
- python deploy.py testsize
ステップまたはパイプライン全体に、追加メモリを割り当てられます。サイズ 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 minutesmax-time を指定しない場合、既定で 120 に設定されます。
clone
リポジトリのクローンをコンテナに作成した時の設定を含みます。ここでの設定には以下が含まれます。
LFS - Git lfs のサポート
depth - Git クローンの深度
enabled を false に設定すると、Git クローンが無効になります。
lfs (GIT のみ)
クローンでの LFS ファイルのダウンロードを有効にします。lfs を true に設定すると、リポジトリがクローンされる際にすべての LFS ファイルがダウンロードされます。指定しない場合は、lfs が初期設定で false になります。
例
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!"あるいは、特定のステップで lfs を有効にして、ビルド時間とリソースの使用量を削減することもできます。例:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
pipelines:
default:
- step:
name: Clone with lfs on
clone:
lfs: true
script:
- ls -lh large-file.zip # 26M large-file.zip
- step:
name: Clone with lfs off
clone:
lfs: false
script:
- apt-get update && apt-get install -y git-lfs
# Download only desired files
- git lfs pull --include=large-file.zip
- ls -lh large-file.zip # 26M large-file.zipdepth (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 は「true」に設定されています。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!"
oidc
Pipelines とリソース サーバーで OpenID Connect を使用できるようにします。oidc の値を、true に設定する必要があります。その後、OpenID Connect を設定します。
例
1
2
3
4
5
6
image: amazon/aws-cli
pipelines:
default:
- step:
oidc: true条件
条件またはルールを満たす場合にのみステップが実行されます。現在サポートされている条件は「チェンジセット」のみです。いずれかの変更済みファイルが includePaths. の表現と一致する場合のみ、changesets を使用してステップを実行します。includePaths で指定されたファイル マッチ パターンは、$BITBUCKET_CLONE_DIR ディレクトリの相対パスです。
考慮される変更内容は次のとおりです。
プル リクエスト パイプラインではすべてのコミットが考慮され、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
パイプライン構成の別の場所で使用されているリソースを定義します。リソースには、以下が含まれる可能性があります。
異なる Docker コンテナで実行されるサービス – 「Bitbucket Pipelines でサービスとデータベースを使用する」を参照してください。
キャッシュ - 「キャッシュの依存性」を参照してください。
YAML アンカー - yaml を分割して定義して使いやすくする方法。「YAML アンカー」を参照してください。
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:latestCache
ビルドの各ステップでインターネットから依存関係を再度ダウンロードすると、長い時間がかかる場合があります。キャッシュを使用すると、これらの依存関係はサーバーへ 1 回ダウンロードされ、ビルドのたびにローカルに読み込まれます。
例
1
2
3
4
5
6
7
8
9
10
definitions:
caches:
custom-npm-cache: node_modules
pipelines:
default:
- step:
caches:
- custom-npm-cache
script:
- npm install事前定義されたキャッシュのリストなど、キャッシュに関する情報は「キャッシュ」をご参照ください。
YAML アンカー
YAML アンカー - yaml を分割して定義して使いやすくする方法。「YAML アンカー」を参照してください。
この内容はお役に立ちましたか?