bitbucket-pipelines.yml を設定する

Pipelines の中心は bitbucket-pipelines.yml ファイルです。このファイルはすべてのビルド構成 (パイプライン) を定義します。このファイルはリポジトリのルート内に作成する必要があります。"コードとして構成" するために、bitbucket-pipelines.yml はリポジトリ内の他のすべてのファイルとともにバージョン管理され、IDE で編集できます。このファイルをまだ作成していない場合は、最初に「Bitbucket Pipelines の使用を開始する」をお読みください。

YAML は読みやすいファイル形式ですが、書き込みを行う際には注意が必要です。タブ文字は使用できないため、インデントにはスペースを使用する必要があります。

パイプラインではさまざまな処理を実行するよう構成できますが、YAML ファイルで最も基本的な内容として、必須キーワードがあります。

pipelines: すべてのパイプライン定義の開始をマークします。

default: 各プッシュで実行するステップが含まれます。

step: 各ステップはリポジトリのクローンを含む新しい Docker コンテナで開始され、その後、内部の script セクションのコンテンツを実行します。

script: 連続して実行されるコマンドの一覧です。


パイプラインには、Linux で実行可能な任意のソフトウェア言語を含めることができます。いくつかの例を示しますが、基本的に bitbucket-pipelines.yml ファイルは次のようになります。

pipelines:
  default:
    - step:
        script:
          - echo 'I made a pipeline!'

その後、以下のキーワードを使用し、ここにビルドできます。


複雑な設定がある場合に役立つテクニックをいくつか紹介します。

  • パイプを使用して、一般的なマルチステップ アクションを簡素化できます。
  • 類似したアクションを実行する複数のステップがある場合は、YAML アンカーを追加して設定のセクションを簡単に再使用できます。
  • You can do a rough check of your configuration using our online yml validator. Note: this doesn't have all the functionality we support (for example, YAML anchors) so is only an approximate guide.



主なコンセプト

パイプラインは、一連のステップで構成されます。

  • パイプラインの各ステップは、別の Docker コンテナを実行します。必要に応じて別のイメージを選択することで、各ステップで別のタイプのコンテナを使用できます。
  • ステップは、画像で示すように、環境内で指定されたコマンドを実行します。
  • 1 つのパイプラインに、最大 10 のステップを含めることができます。

コミットは、パイプラインを実行する必要があることを知らせます。実行されるパイプラインは、それが含まれるセクションによって異なります。

  • 既定 - すべてのコミットがこのパイプラインをトリガーします (他のセクションのいずれかと一致している場合を除く)
  • branch - ブランチの名前を指定するか、glob パターンを使用します。
  • タグ (Git のみ) またはブックマーク (Mercurial のみ) - タグまたはブックマークの名前を指定するか、glob パターンを使用します。
  • custom - 手動でトリガーされたときにのみ実行します。
  • pull-requests - ブランチ名を指定、または glob パターンを使用すると、パイプラインはこのブランチ上にプルリクエストがあるときにのみ実行されます。


インデントによる論理的な "セクション" 作成の概要

キーワード

次のキーワードを選択してビルド パイプラインを定義できます。この表では、キーワードを使用頻度に応じて紹介しています。強調表示された行は、論理セクションを定義するキーワードに対応します。

キーワード 説明
pipelines すべてのパイプライン定義を含みます
default

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

ブランチ

特定のブランチのパイプライン定義が含まれます。

tags 特定の Git タグおよび注釈付きタグのパイプライン定義が含まれます。
bookmarks 特定の Mercurial ブックマークのパイプライン定義が含まれます。
pull-requests プル リクエストでのみ実行されるパイプライン定義を含みます。 
カスタム Bitbucket Cloud の GUI から手動でトリガーできるパイプラインが含まれます。
variables [Custom pipelines only] Contains variables to be supplied when a the pipeline is launched
name [Custom pipelines only] The name for a variable you can enter when launching your custom pipeline
parallel 同時に実行するステップを含みます。
step

ビルドの実行単位を定義します。これは、実行されるコマンドと一意のコンテナの設定を定義します。

name ステップの名前を定義し、ステップで実行される内容を可視化します。
image ステップに使用される Docker イメージ。イメージを指定しない場合、パイプラインは既定の Bitbucket イメージで実行されます。各ステップで同じイメージ タイプを使用するよう、グローバルに定義することもできます。
trigger ステップが手動または自動のどちらであるかを指定します。trigger タイプを指定しない場合、既定で自動に設定されます。
デプロイメント

デプロイメント ステップの環境タイプを定義します。

有効な値: teststaging、または production

size

パイプラインとステップの追加リソースをプロビジョニングするために使用されます。

有効な値: 1x または 2x

script ビルドを実行するためのコマンドの一覧が含まれます。
pipe

特定のパイプを使用するよう指定します。

after-script ステップが成功または失敗した時に実行する一連のコマンド。
artifacts ステップで生成され、次のステップで共有できるファイル (レポートや JAR ファイルなど) を定義します。
options すべてのパイプラインに適用するグローバル設定を含みます。
max-time

ステップを実行できる最長時間 (分)。

0 〜 120 の整数を使用します。max-time を指定しない場合、既定で 120 に設定されます。

clone リポジトリのクローンをコンテナに作成した時の設定を含みます。
lfs クローンでの LFS ファイルのダウンロードを有効化します。指定しない場合、既定で false に設定されます。
depth

すべてのパイプラインの Git クローンの深度を定義します。

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

注: このキーワードは Git リポジトリでのみサポートされます。

定義 パイプライン構成の他の場所で使用する、サービスやカスタム キャッシュなどのリソースを定義します。
services ビルドで使用するサービスを定義します。このサービスはリンクされた別のコンテナで実行されます。
caches 読み込み時間を短縮するため、サーバー上でキャッシュする依存関係を定義します。

pipelines

パイプライン定義の開始。このキーワードの下で、次のうち 1 つ以上を使用してビルド パイプラインを定義する必要があります。

  • default (以下のいずれとも一致しないすべてのブランチ)
  • ブランチ (Git および Mercurial)
  • タグ (Git)
  • ブックマーク (Mercurial)
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!" 

default

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

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


ブランチ

すべてのブランチ固有のビルド パイプラインのセクションを定義します。このセクションの名前または表現は、次の情報と照合されます。

  • Git リポジトリのブランチ
  • Mercurial リポジトリの名前付きブランチ

ブランチ名の処理には glob パターンを使用できます。

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


tags

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


bookmarks

すべてのブックマーク固有のビルド パイプラインを定義します。このセクションの名前または表現は、Mercurial リポジトリのブックマーク名に照合されます。タグ名の処理には glob パターンを使用できます。


image: node:10.15.0
  
pipelines:
  default:
    - step:
        name: Build and test
        script:
          - npm install
          - npm test
  bookmarks:                      # add the 'bookmarks' section
    release-*:                    # specify the bookmark
      - step:                     # define the build pipeline for the bookmark
          name: Build and release
          script:
            - npm install
            - npm test
            - npm run release
  branches:
    staging:
      - step:
          name: Clone
          script:
            - echo "Clone all the things!"

pull-requests

プル リクエスト上でのみ実行される特別なパイプライン。Pull-requests のインデント レベルは branches と同じです。

このタイプのパイプラインは他のパイプラインとは少し異なる方法で実行されます。これがトリガーされると、実行前に、宛先ブランチが作業ブランチにマージされます。マージが失敗すると、パイプラインは停止します。


リポジトリ内から開始されたプル リクエストにのみ適用されます。フォークされたリポジトリからのプル リクエストでは、パイプラインはトリガーされません。

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:
            - ...
ヒント: 設定にすでに branches があり、すべてをプル リクエスト時にのみ実行したい場合、キーワード branches pull-requests で置き換えます (すでに default でパイプラインを使用している場合、これを pull-requests の下に移動し、キーワードを default から "**" に変更して実行します)。

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


カスタム

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


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 "Automated pipelines are cool too."


上記のような構成では、Bitbucket Cloud の [パイプラインの実行] ダイアログに次のパイプラインが表示されます。



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

variables

[Custom pipelines only] Sometimes it's useful to add or update variables when you run a custom pipeline, for example to give a version number, or a single use value.

To enable this, define the variables under your custom pipeline that you want to enter when you run the pipeline:

pipelines:
  custom:
    custom-name-and-region: #name of this pipeline
      - variables:          #list variable names under here
          - name: Username
          - name: Region
      - step:
          script:
            - echo "User name is $Username"
            - echo "and they are in $Region"

Then, when you run a custom pipeline (Branches > ⋯ > Run pipeline for a branch > Custom:..) you'll be able to fill them in.

picture of the interface to update variable values

Other than the custom pipeline use, the keyword variables can also be part of a services definition (see below).

name

When the keyword name is in a variables section of your yaml it defines what variables you can add or update when you run a custom pipeline.

We can also use the keyword name inside a step, to name the step, see the other usage of name explained below.

parallel

並行ステップを使用すると、一連のステップを同時に実行して、ビルドやテストを迅速に行えます。

ステップを並行した場合も、パイプラインが使用する合計のビルド時間数は変わりません。ただし、結果はより早く表示されます。

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

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

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 ファイルで読み込まれる順序で実行されます。パイプラインでは最大 10 ステップを使用できます。

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

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

  • 設定されている順序でのみ実行できます。手動ステップをスキップすることはできません。
  • 前の手順が正常に完了した場合にのみ実行できます。
  • リポジトリへの書き込みアクセス権限を持つユーザーのみがトリガーできます。
  • Pipelines の Web インターフェイス経由でトリガーされます。

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

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

name

ステップに名前を設定して、表示やレポートをわかりやすくすることができます。

名前を使用しているパイプラインのイメージj

image

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

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

イメージを指定するには、次のように指定します。

image: <your_account/repository_details>:<tag>

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

image: openjdk
最新の openjdk バージョンのイメージを使用
image: openjdk:8
openjdk バージョン 8 のイメージを使用
image: nodesource/node:iojs-2.0.2
バージョン iojs-2.0.2の非公式ノードバージョンを使用します。
image: openjdk 					#this image will be used by all steps unless overridden 
   
pipelines:
  default:
    - step:
      image: nodesource/node:iojs-2.0.2 #override the global image for this step
      script:
        - npm install
        - npm test
    - step: 					#this step will use the global image
	  script:
        - npm install
        - npm test


trigger

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

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


デプロイメント

[Deployments] ダッシュボードで使用される、デプロイメント ステップの環境タイプを設定します。

有効な値は teststaging、または production です。

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

    - step:
        name: Deploy to test
        image: aws-cli:1.0
        deployment: test
        script:
          - python deploy.py test

size

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

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

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

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

pipelines:
  default:
    - step:
        script:
          - echo "All good things..."
    - step:
        size: 2x # Double resources available for this step.
        script:
          - echo "Come to those who wait."

パイプライン全体のリソースを増やす

グローバル サイズを使用すると、すべてのステップに "2x" サイズが継承されます。

options:
  size: 2x

pipelines:
  default:
    - step:
        name: Step with more memory
        script:
          - echo "I've got double the memory to play with!"

script

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


pipes


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

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

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 ベースのパイプを指定できます。

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

after-script

after-script セクション内のコマンドは、ステップが成功または失敗した時に実行します。これは、特に after-script が BITBUCKET_EXIT_CODE の値を使用している場合、クリーンアップ コマンド、テスト カバレッジ、通知、またはロールバックの実行に便利です。

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

  • そのセクションでは以降のコマンドは実行されません。
  • ステータスに対して報告されているステータスには影響しません。
pipelines:
  default:
    - step:
        name: Build and test
        script:
          - npm install
          - npm test
        after-script:
          - echo "after script has run!"


artifacts

パイプラインのあるステップから後のステップへ共有するファイルを定義します。アーティファクトは glob パターンを使用して定義できます。

アーティファクトの定義方法の例:

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 の整数を使用します。

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


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

clone

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

  • lfs - Git lfs のサポート
  • depth - Git クローンの深度

lfs

クローン時に Git LFS ファイルをダウンロードするように指定するグローバル設定です。

注: このキーワードは Git リポジトリでのみサポートされます。

clone:
  lfs: true
  
pipelines:
  default:
    - step:
        name: Clone and download
        script:
          - echo "Clone and download my LFS files!"


depth

This global setting defines how many commits we clone into the pipeline container. Use a whole number greater than zero or if you want to clone everything (which will have a speed impact) use full.

If you don't specify the Git clone depth, it defaults to the last 50, to try and balance the time it takes to clone and how many commits you might need.

注: このキーワードは Git リポジトリでのみサポートされます。

clone:
  depth: 5       # include the last five commits
 
pipelines:
  default:
    - step:
        name: Cloning
        script:
          - echo "Clone all the things!"


定義

パイプライン構成の別の場所で使用される リソースを定義します。リソースには以下を含めることができます。

services

必要なすべてのリソースを 1 つのイメージでビルドするのではなく、サービス用に別の docker コンテナを開始することができます。これにより、ビルドの速度が上がり、イメージ全体を再度開始することなく、非常に簡単に 1 つのサービスに変更を加えられるようになります。

So if we want a MySQL service container (a blank database available on localhost:3306 with a default database pipelines, user root and password let_me_in) we could add:

definitions: 
  services: 
    mysql: 
      image: mysql 
      variables: 
        MYSQL_DATABASE: pipelines 
        MYSQL_ROOT_PASSWORD: let_me_in


caches

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

カスタム バンドル キャッシュの定義方法の例:

definitions:
  caches:
    bundler: vendor/bundle


Glob パターンのヒント

Glob patterns don't allow any expression to start with a star. Every expression that starts with a star needs to be put in quotes.

feature/*
  • feature/<any_branch> と一致します。
  • glob パターンはスラッシュ (/) とは一致しないので、feature/<任意のブランチ>/<ブランチ> などの Git ブランチは、feature/* には一致しません。
feature/bb-123-fix-links
  • ブランチ、タグ、またはブックマークの正確な名前を指定すると、特定のブランチに対して定義されたパイプラインは、そのブランチに一致する一般的な表現をすべて上書きします。
  • たとえば、feature/*feature/bb-123-fix-links のパイプラインを指定したとします。feature/bb-123-fix-links へのコミットの際、Pipelines では、feature/bb-123-fix-links に対して定義されたステップを実行しますが、feature/* で定義されたステップは実行しません。
'*'
  • すべてのブランチ、タグ、またはブックマークと一致します。アスタリスク (*) は一重引用符で囲む必要があります。
  • この glob パターンはスラッシュ (/) とは一致しないので、feature/bb-123-fix-links などの Git ブランチは '*' には一致しません。スラッシュを一致させる必要がある場合は、'*' ではなく '**' を使用します。
'**'
  • Matches all branches, tags, or bookmarks. For example, it includes branches with the slash (/) like feature/bb-123-fix-links. The ** expression must be in quotes.
'*/feature'
  • この表現には引用符が必要です。

'master' および重複するブランチ名

  • 引用符で囲まれた名前は、引用符で囲まれていない名前と同様に処理されます。たとえば Pipelines では、master と 'master'  は同じブランチ名とみなされます。
  • 上記の場合、Pipelines では 1 つの名前とのみ (両方ではなく、master または 'master') 照合されます。
  • bitbucket-pipelines.yml ファイルでは名前の重複を避けることをお勧めします。

なお、以下の説明もご覧ください:



最終更新日 2019 年 6 月 6 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する

このセクションの項目

Powered by Confluence and Scroll Viewport.