Bitbucket Cloud リポジトリをビルドする

Azure DevOps Services

Azure Pipelines では、すべての pull request を自動的にビルドして検証し、Bitbucket Cloud リポジトリに対してコミットできます。 この記事では、Bitbucket Cloud と Azure Pipelines との間の統合を構成する方法について説明します。

Bitbucket と Azure Pipelines は、適切に統合される 2 つの独立したサービスです。 Bitbucket Cloud ユーザーに Azure Pipelines へのアクセス権が自動的に付与されることはありません。 それらのユーザーを Azure Pipelines に明示的に追加する必要があります。

Bitbucket リポジトリにアクセスする

最初に Bitbucket Cloud リポジトリを選択し、そのリポジトリ内の YAML ファイルを選択して、新しいパイプラインを作成します。 YAML ファイルが存在するリポジトリは、self リポジトリと呼ばれます。 既定では、これはパイプラインによってビルドされるリポジトリです。

後で、別のリポジトリまたは複数のリポジトリをチェックアウトするようにパイプラインを構成できます。 これを行う方法については、複数のリポジトリのチェックアウトに関する記事を参照してください。

ビルド中にコードをフェッチするには、Azure Pipelines にリポジトリへのアクセス権が付与されているる必要があります。 さらに、パイプラインを設定するユーザーは Bitbucket への管理者アクセス権を持っている必要があります。これは、その ID を使用して Bitbucket に Webhook を登録するためです。

パイプラインの作成時に、Bitbucket Cloud リポジトリへの Azure Pipelines アクセス権を付与するための認証の種類は 2 つあります。

認証の種類 パイプライン実行で使われるもの
1. OAuth 個人用 Bitbucket ID
2. ユーザー名とパスワード 個人用 Bitbucket ID

OAuth 認証

OAuth は、個人用 Bitbucket アカウントのリポジトリで使用を開始するための最もシンプルな認証の種類です。 Bitbucket の状態の更新が、個人用 Bitbucket ID に代わって実行されます。 パイプラインが機能し続けるためには、リポジトリへのアクセスがアクティブなままである必要があります。

OAuth を使用するには、パイプラインの作成時にプロンプトが表示されたら、Bitbucket にログインします。 次に、[承認] をクリックして OAuth で承認します。 OAuth 接続は、後で使用するために Azure DevOps プロジェクトに保存され、作成されるパイプラインで使用されます。

注意

Azure DevOps Services ユーザー インターフェイスで読み込むことができる Bitbucket リポジトリの最大数は 2,000 です。

パスワード認証

ビルドと Bitbucket の状態の更新が、個人用 ID に代わって実行されます。 ビルドが機能し続けるためには、リポジトリへのアクセスがアクティブなままである必要があります。

パスワード接続を作成するには、Azure DevOps プロジェクト設定のサービス接続にアクセスします。 新しい Bitbucket サービス接続を作成し、ユーザー名とパスワードを指定して Bitbucket Cloud リポジトリに接続します。

CI トリガー

継続的インテグレーション (CI) トリガーを使用すると、指定したブランチに更新をプッシュするか、指定したタグをプッシュするたびにパイプラインが実行されます。

YAML パイプラインは、Azure DevOps スプリント 227 で導入された [暗黙的な YAML CI トリガー設定を無効化する] 設定が有効になっていない限り、すべてのブランチで CI トリガーを使用して既定で構成されます。 [暗黙的な YAML CI トリガーの無効化] 設定は、組織レベルまたはプロジェクト レベルで構成できます。 [暗黙的な YAML CI トリガーの無効化] 設定が有効になっているときに、YAML パイプラインに trigger セクションがない場合、YAML パイプラインの CI トリガーは有効になりません。 既定では、[暗黙的な YAML CI トリガーの無効化] は有効になっていません。

ブランチ

簡単な構文を使用して、CI トリガーを取得するブランチを制御できます。

trigger:
- main
- releases/*

ブランチの完全な名前 (例: main) またはワイルドカード (例: releases/*) を指定できます。 ワイルドカード構文の詳細については、「ワイルドカード」を参照してください。

注意

変数は実行時 (トリガーの起動後) に評価されるため、トリガーで変数を使用することはできません。

注意

テンプレートを使用して YAML ファイルを作成する場合は、パイプラインのメイン YAML ファイルでのみトリガーを指定できます。 テンプレート ファイルにトリガーを指定することはできません。

exclude または batch を使用する複雑なトリガーの場合は、次の例に示すように完全な構文を使用する必要があります。

# specific branch build
trigger:
  branches:
    include:
    - main
    - releases/*
    exclude:
    - releases/old*

上記の例では、変更が main またはリリース ブランチにプッシュされると、パイプラインがトリガーされます。 ただし、old で始まるリリース ブランチに変更が加えられた場合はトリガーされません。

include 句を指定せずに exclude 句を指定すると、include 句に * を指定した場合と同じになります。

branches 一覧でブランチ名を指定するだけでなく、次の形式を使用してタグに基づいてトリガーを構成することもできます。

trigger:
  branches:
    include:
      - refs/tags/{tagname}
    exclude:
      - refs/tags/{othertagname}

トリガーを指定せず、[暗黙的な YAML CI トリガーを無効にする] 設定が有効になっていない場合、既定値は次のように記述します。

trigger:
  branches:
    include:
    - '*'  # must quote since "*" is a YAML reserved character; we want a string

重要

トリガーを指定すると、既定の暗黙的なトリガーが置き換えられ、含まれるように明示的に構成されたブランチへのプッシュのみがパイプラインをトリガーします。 インクルードは最初に処理され、次に除外がリストから削除されます。

CI 実行のバッチ処理

多くのチーム メンバーが頻繁に変更をアップロードしている場合は、開始する実行の数を減らすことができます。 パイプラインの実行中に batchtrue に設定すると、システムは実行が完了するまで待機し、まだビルドされていないすべての変更で別の実行を開始します。

# specific branch build with batching
trigger:
  batch: true
  branches:
    include:
    - main

注意

batch は、リポジトリ リソース トリガーではサポートされていません。

この例を明確にするために、Amain にプッシュした場合に、上記のパイプラインが実行されたとします。 そのパイプラインの実行中に、追加のプッシュ BC がリポジトリに送信されます。 これらの更新では、独立した新しい実行はすぐに開始されません。 ただし、最初の実行が完了すると、その時点までのすべてのプッシュがバッチ処理され、新しい実行が開始されます。

注意

パイプラインに複数のジョブとステージがある場合でも、2 回目の実行を開始する前にすべてのジョブとステージを完了またはスキップして、最初の実行が終了状態に達する必要があります。 このため、複数のステージまたは承認を含むパイプラインでこの機能を使用する場合は注意が必要です。 このような場合にビルドをバッチ処理する場合は、CI/CD プロセスを 2 つのパイプライン (ビルド用 (バッチ処理あり) とデプロイ用) に分割することをお勧めします。

パス

含めるか除外するファイル パスを指定できます。

# specific path build
trigger:
  branches:
    include:
    - main
    - releases/*
  paths:
    include:
    - docs
    exclude:
    - docs/README.md

パスを指定する場合は、Azure DevOps Server 2019.1 以降を使用している場合にトリガーするブランチを明示的に指定する必要があります。 パス フィルターのみでパイプラインをトリガーすることはできません。ブランチ フィルターも必要です。また、パス フィルターに一致する変更されたファイルは、ブランチ フィルターに一致するブランチからのものである必要があります。 Azure DevOps Server 2020 以降を使用している場合は、branches を省略して、パス フィルターと組み合わせて、すべてのブランチをフィルター処理できます。

ワイルドカードは、パス フィルターでサポートされています。 たとえば、src/app/**/myapp* に一致するすべてのパスを含めることができます。 パス フィルターを指定する場合は、ワイルドカード文字 (***、または ?)) を使用できます。

  • パスは、常にリポジトリのルートを基準にして指定されます。
  • パス フィルターを設定しない場合、リポジトリのルート フォルダーは既定で暗黙的に含まれます。
  • パスを除外した場合は、より深いフォルダーを指すよう修飾しない限り、それを含めることはできません。 たとえば、/tools を除外した場合、/tools/trigger-runs-on-these を含めることはできます
  • パス フィルターの順序は関係ありません。
  • Git のパスでは、"大文字と小文字が区別されます"。 実際のフォルダーと同じ大文字と小文字の区別を使用してください。
  • 変数は実行時 (トリガーの起動後) に評価されるため、パスで変数を使用することはできません。

注意

Bitbucket Cloud リポジトリの場合、タグ トリガーを指定する唯一の方法は branches 構文を使用することです。 tags: 構文は、Bitbucket ではサポートされていません。

CI のオプトアウト

CI トリガーの無効化

trigger: none を指定すると、CI トリガーを完全にオプトアウトできます。

# A pipeline with no CI trigger
trigger: none

重要

ブランチに変更をプッシュすると、CI 実行を開始する必要があるかどうかを判断するために、そのブランチ内の YAML ファイルが評価されます。

個々のコミットの CI のスキップ

また、プッシュが通常トリガーするパイプラインの実行をスキップするように Azure Pipelines に指示することもできます。 Azure Pipelines では、プッシュの一部であるコミットのメッセージまたは説明に [skip ci] を含めるだけで、このプッシュの実行 CI をスキップします。 次のバリエーションのいずれかを使用することもできます。

  • [skip ci] または [ci skip]
  • skip-checks: true または skip-checks:true
  • [skip azurepipelines] または [azurepipelines skip]
  • [skip azpipelines] または [azpipelines skip]
  • [skip azp] または [azp skip]
  • ***NO_CI***

条件でトリガーの種類を使用する

実行を開始したトリガーの種類に応じて、パイプラインでさまざまなステップ、ジョブ、またはステージを実行するのが一般的なシナリオです。 これを行うには、システム変数 Build.Reason を使用します。 たとえば、次の条件をステップ、ジョブ、またはステージに追加して、PR 検証から除外します。

condition: and(succeeded(), ne(variables['Build.Reason'], 'PullRequest'))

新しいブランチが作成されたときのトリガーの動作

同じリポジトリに対して複数のパイプラインを構成するのが一般的です。 たとえば、アプリのドキュメントをビルドするためのパイプラインと、ソース コードをビルドするためのパイプラインがあるとします。 これらの各パイプラインで、適切なブランチ フィルターとパス フィルターを使用して CI トリガーを構成できます。 たとえば、docs フォルダーに更新をプッシュするときに 1 つのパイプラインをトリガーし、アプリケーション コードに更新をプッシュするときにもう 1 つのパイプラインをトリガーするとします。 このような場合は、新しいブランチが作成されたときにパイプラインがどのようにトリガーされるかを理解する必要があります。

新しいブランチ (ブランチ フィルターに一致する) をリポジトリにプッシュするときの動作を次に示します。

  • パイプラインにパス フィルターがある場合は、新しいブランチがそのパス フィルターに一致するファイルに変更を加えた場合にのみトリガーされます。
  • パイプラインにパス フィルターがない場合は、新しいブランチに変更がない場合でもトリガーされます。

ワイルドカード

ブランチ、タグ、またはパスを指定する場合は、正確な名前またはワイルドカードを使用できます。 ワイルドカード パターンでは、* が 0 個以上の文字と一致し、? が 1 つの文字と一致するようにできます。

  • YAML パイプラインでパターンを * で開始する場合は、"*-releases" のようにパターンを引用符で囲む必要があります。
  • ブランチとタグの場合:
    • ワイルドカードは、パターン内の任意の場所に表示できます。
  • パスの場合:
    • Azure DevOps Services を含む Azure DevOps Server 2022 以降では、パス パターン内の任意の場所にワイルドカードが表示され、* または ? を使用できます。
    • Azure DevOps Server 2020 以前では、最後の文字として * を含めることができますが、ディレクトリ名を単独で指定する場合と何も変わりません。 パス フィルターの途中に * を含めることはできず? を使用することはできません。
trigger:
  branches:
    include:
    - main
    - releases/*
    - feature/*
    exclude:
    - releases/old*
    - feature/*-working
  paths:
    include:
    - docs/*.md

PR トリガー

また、pull request が指定されたターゲット ブランチのいずれかで開かれるとき、またはそのような pull request に対して更新が行われるたびにパイプラインが実行されるように pull request (PR) トリガーを構成することもできます。

ブランチ

pull request を検証するときにターゲット ブランチを指定できます。 たとえば、masterreleases/* をターゲットとする pull request を検証するには、次の pr トリガーを使用できます。

pr:
- main
- releases/*

この構成により、新しい pull request が初めて作成されたときと、その pull request に対して更新が行われるたびに、新しい実行が開始されます。

ブランチの完全な名前 (例: master) またはワイルドカード (例: releases/*) を指定できます。

注意

変数は実行時 (トリガーの起動後) に評価されるため、トリガーで変数を使用することはできません。

注意

テンプレートを使用して YAML ファイルを作成する場合は、パイプラインのメイン YAML ファイルでのみトリガーを指定できます。 テンプレート ファイルにトリガーを指定することはできません。

新しい各実行により、pull request のソース ブランチから最新のコミットがビルドされます。 これは、Azure Pipelines が他のリポジトリ (Azure Repos、GitHub など) で pull request をビルドする方法 (マージ コミットをビルドする) とは異なります。 残念ながら、Bitbucket は、pull request のソース ブランチとターゲット ブランチの間でマージされたコードが含まれた、マージ コミットに関する情報を公開しません。

YAML ファイルに pr トリガーが含まれていない場合は、次のような pr トリガーを記述したかのように、すべてのブランチに対して pull request 検証が自動的に有効になります。 この構成により、任意の pull request が作成されたときと、任意のアクティブな pull request のソース ブランチにコミットが送信されたときに、ビルドがトリガーされます。

pr:
  branches:
    include:
    - '*'  # must quote since "*" is a YAML reserved character; we want a string

重要

pr トリガーを指定すると、既定の暗黙的な pr トリガーが置き換えられ、含まれるように明示的に構成されたブランチへのプッシュのみがパイプラインをトリガーします。

特定のブランチを除外する必要があるより複雑なトリガーの場合は、次の例に示すように完全な構文を使う必要があります。

# specific branch
pr:
  branches:
    include:
    - main
    - releases/*
    exclude:
    - releases/old*

パス

含めるか除外するファイル パスを指定できます。 次に例を示します。

# specific path
pr:
  branches:
    include:
    - main
    - releases/*
  paths:
    include:
    - docs
    exclude:
    - docs/README.md

ヒント:

  • パス フィルターでは、ワイルド カードはサポートされていません。
  • パスは、常にリポジトリのルートを基準にして指定されます。
  • パス フィルターを設定しない場合、リポジトリのルート フォルダーは既定で暗黙的に含まれます。
  • パスを除外した場合は、より深いフォルダーを指すよう修飾しない限り、それを含めることはできません。 たとえば、/tools を除外した場合、/tools/trigger-runs-on-these を含めることはできます
  • パス フィルターの順序は関係ありません。
  • Git のパスでは、"大文字と小文字が区別されます"。 実際のフォルダーと同じ大文字と小文字の区別を使用してください。
  • 変数は実行時 (トリガーの起動後) に評価されるため、パスで変数を使用することはできません。

複数の PR 更新

PR に対する追加の更新によって、同じ PR に対する進行中の検証の実行を取り消すかどうかを指定できます。 既定値は、true です。

# auto cancel false
pr:
  autoCancel: false
  branches:
    include:
    - main

PR 検証のオプトアウト

pr: none を指定することで、pull request の検証を完全にオプトアウトできます。

# no PR triggers
pr: none

詳しくは、YAML スキーマPR トリガーに関する記事を参照してください。

注意

pr トリガーが起動しない場合は、UI で YAML PR トリガーをオーバーライドしていないことを確認します。

情報提供の実行

情報提供の実行では、Azure DevOps が YAML パイプラインのソース コードの取得に失敗したことが通知されます。 ソース コードの取得は、プッシュされたコミットなどの外部イベントに応答して実施されます。 また、コードの変更があるかどうかや、スケジュールされた実行を開始するかどうかなどのチェックのために、内部トリガーに応答して実施されます。 ソース コードの取得は複数の原因で失敗する可能性があります。よくある原因として Git リポジトリ プロバイダーによる要求調整が挙げられます。 情報提供の実行の存在は、Azure DevOps がパイプラインを実行しようとしたことを意味しないこともあります。

情報提供の実行は、次のスクリーンショットで示すようなものです。

Screenshot of an informational pipeline run.

情報提供の実行は、次の属性によって認知できます。

  • 状態は Canceled です
  • 期間は < 1s です
  • 実行名に、次のテキストのいずれかが含まれいる。
    • Could not retrieve file content for {file_path} from repository {repo_name} hosted on {host} using commit {commit_sha}.
    • Could not retrieve content for object {commit_sha} from repository {repo_name} hosted on {host}.
    • Could not retrieve the tree object {tree_sha} from the repository {repo_name} hosted on {host}.
    • Could not find {file_path} from repository {repo_name} hosted on {host} using version {commit_sha}. One of the directories in the path contains too many files or subdirectories.
  • 通常、実行名には YAML パイプラインの読み込みが失敗する原因になった BitBucket/GitHub エラーが含まれています
  • ステージ/ジョブ/ステップはありません

詳細は、「情報提供の実行」を参照してください。

制限事項

Azure Pipelines は、リポジトリから Azure DevOps ポータルのドロップダウン リストに最大 2,000 個のブランチを読み込みます。たとえば、[手動のビルドとスケジュールされたビルドの既定のブランチ] 設定に読み込んだり、パイプラインを手動で実行するときにブランチを選択したときです。 目的のブランチが一覧に表示されない場合は、目的のブランチ名を手動で入力してください。

よく寄せられる質問

Bitbucket 統合に関連する問題は、次のカテゴリに分類されます。

  • トリガーの失敗: リポジトリに更新をプッシュしたときに、パイプラインがトリガーされません。
  • 間違ったバージョン: パイプラインは実行されますが、ソース/YAML の予期しないバージョンが使用されています。

トリガーの失敗

CI/PR トリガーを使用して新しい YAML パイプラインを作成しましたが、パイプラインはトリガーされていません。

次の各手順を実行して、失敗するトリガーをトラブルシューティングしてください。

  • YAML CI または PR トリガーは、UI のパイプライン設定によってオーバーライドされますか? パイプラインの編集時に、[...] を選択し、[トリガー] を選択します。

    Pipeline settings UI.

    リポジトリで使用できるトリガーの種類 ([継続的インテグレーション] または [pull request 検証]) に対する "ここから YAML トリガーをオーバーライドする" 設定を調べます。

    Override YAML trigger from here.

  • Webhook は、Bitbucket から Azure Pipelines への更新の伝達のために使用されます。 Bitbucket で、リポジトリの設定に移動し、[Webhook] に移動します。 Webhook があることを確認します。
  • パイプラインが一時停止または無効化されていませんか? パイプライン用のエディターを開いて、[設定] を選択して確認してください。 パイプラインが一時停止または無効化されている場合、トリガーは機能しません。

  • 正しいブランチの YAML ファイルを更新しましたか? ブランチに更新をプッシュすると、そのブランチ内の YAML ファイルによって CI の動作が制御されます。 ソース ブランチに更新をプッシュすると、ソース ブランチとターゲット ブランチのマージによって生成される YAML ファイルによって PR の動作が制御されます。 正しいブランチの YAML ファイルに、必要な CI または PR 構成があることを確認します。

  • トリガーを正しく構成しましたか? YAML トリガーを定義する場合は、ブランチ、タグ、パスに対して include 句と exclude 句の両方を指定できます。 include 句がコミットの詳細と一致していることと、exclude 句がそれらを除外していないことを確認します。 トリガーの構文を確認し、正確であることを確認します。

  • トリガーまたはパスを定義するときに変数を使用しましたか? これはサポートされていません。

  • YAML ファイルにテンプレートを使用しましたか? その場合は、トリガーがメインの YAML ファイルで定義されていることを確認します。 テンプレート ファイル内で定義されたトリガーはサポートされていません。

  • 変更のプッシュ先のブランチまたはパスを除外しましたか? 変更を含まれているブランチに含まれているパスにプッシュしてテストします。 トリガーのパスは、大文字と小文字が区別される点に注意してください。 トリガーのパスを指定するときには、実際のフォルダーと同じ大文字と小文字を使用してください。

  • 新しいブランチをプッシュしましたか? その場合、新しいブランチで新しい実行が開始されない場合があります。 「新しいブランチが作成されたときのトリガーの動作」セクションを参照してください。

CI トリガーまたは PR トリガーは正常に動作していましたが、 今は動作していません。

まず、前の質問のトラブルシューティング手順を実行します。 その後、次の追加手順に従います。

  • PR でマージ競合が発生していますか? パイプラインをトリガーしなかった PR の場合は、パイプラインを開き、マージの競合があるかどうかをチェックします。 マージ競合を解決してください。

  • プッシュ イベントまたは PR イベントの処理に遅延が発生していますか? これは通常、問題が 1 つのパイプラインだけで発生しているか、またはプロジェクト内のすべてのパイプラインもしくはリポジトリで発生しているかを確認することで、見分けることができます。 いずれかのリポジトリへのプッシュまたは PR 更新でこの現象が発生している場合は、更新イベントの処理に遅延が発生している可能性があります。 ステータス ページでサービスの停止が発生しているかどうかを確認してください。 ステータス ページに問題が表示される場合は、Microsoft のチームが既に作業を開始しているはずです。 この問題に関する最新情報をこまめに確認してください。

ユーザーが YAML ファイルを更新するときに、トリガーのブランチの一覧をオーバーライドしないようにする必要があります。 どうすればよいですか?

コードを投稿するアクセス許可を持つユーザーは、YAML ファイルを更新し、追加のブランチを含めたり除外したりできます。 そのため、ユーザーは YAML ファイルに独自の機能やユーザー ブランチを含め、その更新を機能またはユーザー ブランチにプッシュすることができます。 これにより、そのブランチに対するすべての更新に対してパイプラインがトリガーされる可能性があります。 この動作を防ぐ場合は、次の手順を実行できます。

  1. Azure Pipelines UI でパイプラインを編集します。
  2. [トリガー] メニューに移動します。
  3. [ここから YAML 継続的インテグレーション トリガーを上書きする] を選択します。
  4. トリガーに含めるブランチまたは除外するブランチを指定します。

これらの手順に従うと、YAML ファイルで指定された CI トリガーはすべて無視されます。

バージョンが正しくない

パイプラインで間違ったバージョンの YAML ファイルが使用されています。 なぜでしょうか。

  • CI トリガーの場合、プッシュするブランチにある YAML ファイルが評価され、CI ビルドを実行する必要があるかどうかが確認されます。
  • PR トリガーの場合、PR のソース ブランチとターゲット ブランチをマージした結果の YAML ファイルが評価され、PR ビルドを実行する必要があるかどうかが確認されます。