パイプラインをカスタマイズする

[アーティクル]
08/08/2024

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

パイプラインをカスタマイズする一般的な方法に関するステップバイステップチュートリアル。

前提条件

「最初のパイプラインを作成する」の手順に従って、作業パイプラインを作成します。

`azure-pipelines.yml` ファイルの概要

パイプラインは、リポジトリ内の YAML ファイルを使用して定義されます。通常、このファイルは azure-pipelines.yml という名前で、リポジトリのルートにあります。

Azure Pipelines のパイプライン ページに移動し、作成したパイプラインを選択し、パイプラインのコンテキストメニューで [編集] を選択して、パイプラインの YAML エディターを開きます。

Note

Azure DevOps ポータルでパイプラインを表示および管理する方法については、「パイプラインの表示と管理」を参照してください。

YAML ファイルの内容を確認します。

 trigger:
 - main

 pool:
   vmImage: 'ubuntu-latest'

 steps:
 - task: Maven@4
   inputs:
     mavenPomFile: 'pom.xml'
     mavenOptions: '-Xmx3072m'
     javaHomeOption: 'JDKVersion'
     jdkVersionOption: '1.11'
     jdkArchitectureOption: 'x64'
     publishJUnitResults: false
     testResultsFiles: '**/surefire-reports/TEST-*.xml'
     goals: 'package'

注意

YAML ファイルの内容は、開始したサンプルリポジトリや Azure Pipelines で行われたアップグレードによって異なる場合があります。

このパイプラインは、チームがリポジトリのメインブランチに変更をプッシュするか、pull request を作成するたびに実行されます。これは、Microsoft がホストする Linux マシン上で実行されます。パイプラインプロセスには、Maven タスクを実行する 1 つのステップがあります。

ビルドするプラットフォームを変更する

さまざまな開発言語用の SDK とツールが既に含まれている Microsoft によってホストされるエージェントでプロジェクトをビルドできます。または、必要な特定のツールを備えたセルフホステッドエージェントを使用することもできます。

ビルドで [パイプラインの編集] アクションを選択するか、パイプラインのメインページから [編集] を選択して、パイプラインのエディターに移動します。
現在、パイプラインは Linux エージェントで実行されます。
```
pool:
  vmImage: "ubuntu-latest"
```
Windows や Mac などの別のプラットフォームを選択するには、vmImage 値を変更します。
```
pool:
  vmImage: "windows-latest"
```
```
pool:
  vmImage: "macos-latest"
```
[保存] を選択し、変更を確認して、パイプラインが別のプラットフォームで実行されているのを確認します。

ステップを追加する

パイプラインにステップとしてさらにスクリプトまたはタスクを追加できます。タスクは、事前パッケージ化されたスクリプトです。タスクは、アプリのビルド、テスト、公開、またはデプロイに使用できます。 Java の場合、使用した Maven タスクはテストと結果の公開を処理しますが、タスクを使用してコードカバレッジの結果を公開することもできます。

パイプラインの YAML エディターを開きます。

YAML ファイルの末尾に次のスニペットを追加します。

- task: PublishCodeCoverageResults@1
  inputs:
    codeCoverageTool: "JaCoCo"
    summaryFileLocation: "$(System.DefaultWorkingDirectory)/**/site/jacoco/jacoco.xml"
    reportDirectory: "$(System.DefaultWorkingDirectory)/**/site/jacoco"
    failIfCoverageEmpty: true

[保存] を選択して変更を確認します。
テストとコードカバレッジの結果を表示するには、ビルドを選択し、[テスト] タブと [カバレッジ] タブに移動します。

複数のプラットフォーム間でのビルド

複数のプラットフォームでプロジェクトをビルドしてテストできます。これを行う 1 つの方法は、strategy と matrix を使うことです。変数を使用して、パイプラインのさまざまな部分にデータを便利に配置できます。この例では、変数を使用して、使用するイメージの名前を渡します。

azure-pipelines.yml ファイルで、次のコンテンツを置き換えます。

pool:
  vmImage: "ubuntu-latest"

次のコンテンツを含む:

strategy:
  matrix:
    linux:
      imageName: "ubuntu-latest"
    mac:
      imageName: "macOS-latest"
    windows:
      imageName: "windows-latest"
  maxParallel: 3

pool:
  vmImage: $(imageName)

[保存] を選択し、変更を確認して、ビルドが 3 つの異なるプラットフォームで最大 3 つのジョブを実行することを確認します。

各エージェントは、一度に 1 つのジョブのみを実行できます。複数のジョブを並列で実行するには、複数のエージェントを構成する必要があります。また、十分な数の並列ジョブも必要です。

複数のバージョンを使用してビルドする

その言語の異なるバージョンを使用してプロジェクトをビルドするには、matrix のバージョンと変数を使用できます。この手順では、1 つのプラットフォームで 2 つの異なるバージョンの Java を使用して Java プロジェクトをビルドするか、異なるプラットフォームで異なるバージョンの Java を実行できます。

注意

コンテキストで strategy を複数回使用することはできません。

1 つのプラットフォームと複数のバージョンでビルドする場合は、Maven タスクの前と vmImage の後に、次のマトリックスを azure-pipelines.yml ファイルに追加します。
```
strategy:
  matrix:
    jdk10:
      jdkVersion: "1.10"
    jdk11:
      jdkVersion: "1.11"
  maxParallel: 2
```
次に、Maven タスクで次の行を置き換えます。
```
jdkVersionOption: "1.11"
```
置き換えた後の行は次のとおりです。
```
jdkVersionOption: $(jdkVersion)
```
$(imageName) 変数は、必ず任意のプラットフォームに戻してください。

複数のプラットフォームとバージョンでビルドする場合は、公開タスクの前に azure-pipelines.yml ファイル内のコンテンツ全体を次のスニペットに置き換えます。

trigger:
- main

strategy:
  matrix:
    jdk10_linux:
      imageName: "ubuntu-latest"
      jdkVersion: "1.10"
    jdk11_windows:
      imageName: "windows-latest"
      jdkVersion: "1.11"
  maxParallel: 2

pool:
  vmImage: $(imageName)

steps:
- task: Maven@4
  inputs:
    mavenPomFile: "pom.xml"
    mavenOptions: "-Xmx3072m"
    javaHomeOption: "JDKVersion"
    jdkVersionOption: $(jdkVersion)
    jdkArchitectureOption: "x64"
    publishJUnitResults: true
    testResultsFiles: "**/TEST-*.xml"
    goals: "package"

[保存] を選択し、変更を確認して、ビルドが 2 つの異なるプラットフォームおよび SDK で 2 つのジョブを実行することを確認します。

CI トリガーをカスタマイズする

パイプライントリガーにより、パイプラインが実行されます。 trigger: を使用すると、更新プログラムをブランチにプッシュするたびにパイプラインを実行できます。 YAML パイプラインは、既定で、既定のブランチの CI トリガー (通常は main) で構成されます。特定のブランチまたは pull request 検証用にトリガーを設定できます。 pull request 検証トリガーの場合は、次の 2 つの例に示すように、trigger: ステップを pr: に置き換えます。既定では、プル要求の変更ごとにパイプラインが実行されます。

トリガーを設定する場合は、azure-pipelines.yml ファイルの先頭に次のいずれかのスニペットを追加します。
```
trigger:
  - main
  - releases/*
```
```
pr:
  - main
  - releases/*
```
ブランチの完全な名前 (例: main) またはプレフィックスに一致するワイルドカード (例: releases/*) を指定できます。

パイプラインの設定

パイプラインの設定は、パイプラインの詳細ページの [その他の操作] メニューから表示および構成できます。

パイプライン設定とその他のアクションメニューのスクリーンショット。

セキュリティの管理 - セキュリティの管理
名前の変更/移動 - パイプライン名とフォルダーの場所を編集します。
状態バッジ - リポジトリにステータスバッジを追加する
削除 - すべてのビルドと関連する成果物を含むパイプラインを削除します。
スケジュールされた実行 - スケジュールされた実行ビュー

[設定] を選択して、次のパイプライン設定を構成します。

パイプライン設定ページのスクリーンショット。

パイプラインの設定ウィンドウで、次の設定を構成できます。

新しい実行要求の処理 - パイプラインで新しい実行が開始されないようにしたい場合があります。
- 既定では、新しい実行要求の処理は有効です。この設定により、手動実行を含むすべてのトリガーの種類の標準処理が可能になります。
- 一時停止されたパイプラインでは、実行要求を処理できますが、これらの要求は実際に開始されることなくキューに入れられます。新しい要求処理が有効になると、キュー内の最初の要求から実行処理が再開されます。
- 無効なパイプラインでは、ユーザーが新しい実行を開始できなくなります。この設定が適用されている間は、すべてのトリガーも無効になります。無効なパイプラインを使用しているすべてのビルドポリシーには、[PR 概要] ウィンドウのビルドポリシーの横に「ビルドをキューに登録できません」というメッセージが表示され、ビルドポリシーの状態が壊れます。
YAML ファイルパス - 別の YAML ファイルを使用するようにパイプラインに指示する必要がある場合は、そのファイルへのパスを指定できます。この設定は、YAML ファイルを移動または名前の変更をする必要がある場合にも役立ちます。
この実行に含まれる作業項目を自動的にリンクする - 特定のパイプライン実行に関連付けられている変更には、作業項目が関連付けられている可能性があります。これらの作業項目を実行にリンクするには、このオプションを選択します。 [この実行に含まれる作業項目を自動的にリンクする] が選択されている場合は、特定のブランチを指定するか、既定のすべてのブランチに * を指定する必要があります。ブランチを指定した場合、作業項目はそのブランチの実行にのみ関連付けられます。 * を指定すると、すべての実行に作業項目が関連付けられます。
- 実行が失敗したときに通知を受け取るには、「チームの通知を管理する方法」を参照してください

セキュリティの管理

パイプラインのセキュリティは、パイプラインのランディングページの [その他の操作] からプロジェクトレベルで設定できます。パイプラインの詳細ページからパイプラインレベルで設定することもできます。

パイプライン操作のセキュリティをサポートするために、組み込みセキュリティグループにユーザーを追加したり、ユーザーまたはグループに個別のアクセス許可を設定したり、定義済みロールにユーザーを追加したりできます。 Azure Pipelines のセキュリティは、Web ポータルでユーザーまたは管理者のコンテキストから管理します。パイプラインのセキュリティの構成の詳細については、「パイプラインのアクセス許可とセキュリティロール」を参照してください。

失敗時に作業項目を作成

YAML パイプラインには、クラシックビルドパイプラインのような [失敗時に作業項目を作成] 設定はありません。クラシックビルドパイプラインは単一ステージであり、[失敗時に作業項目を作成] はパイプライン全体に適用されます。 YAML パイプラインは複数ステージになる可能性があり、パイプラインレベルの設定が適切でない場合があります。 YAML パイプラインで [失敗時に作業項目を作成] を実装するには、作業項目の作成 REST API 呼び出しや Azure DevOps CLI az boards work-item create コマンドなどのメソッドをパイプライン内の目的のポイントで使用できます。

次の例には 2 つのジョブがあります。最初のジョブはパイプラインの作業を表しますが、失敗した場合は 2 番目のジョブが実行され、パイプラインと同じプロジェクトにバグが作成されます。

# When manually running the pipeline, you can select whether it
# succeeds or fails.
parameters:
- name: succeed
  displayName: Succeed or fail
  type: boolean
  default: false

trigger:
- main

pool:
  vmImage: ubuntu-latest

jobs:
- job: Work
  steps:
  - script: echo Hello, world!
    displayName: 'Run a one-line script'

  # This malformed command causes the job to fail
  # Only run this command if the succeed variable is set to false
  - script: git clone malformed input
    condition: eq(${{ parameters.succeed }}, false)

# This job creates a work item, and only runs if the previous job failed
- job: ErrorHandler
  dependsOn: Work
  condition: failed()
  steps: 
  - bash: |
      az boards work-item create \
        --title "Build $(build.buildNumber) failed" \
        --type bug \
        --org $(System.TeamFoundationCollectionUri) \
        --project $(System.TeamProject)
    env: 
      AZURE_DEVOPS_EXT_PAT: $(System.AccessToken)
    displayName: 'Create work item on failure'

注意

Azure Boards では、アジャイルやベーシックなど、複数の異なるプロセスを使用して作業項目の追跡を構成できます。各プロセスには異なる作業項目の種類があり、各プロセスですべての作業項目タイプを使用できるわけではありません。各プロセスでサポートされる作業項目の種類の一覧については、「作業項目の種類 (WIT)」を参照してください。

前の例では、ランタイムパラメーターを使用して、パイプラインが成功するか失敗するかを構成しました。パイプラインを手動で実行する場合は、succeed パラメーターの値を設定できます。パイプラインの最初のジョブの 2 番目 script のステップは succeed パラメーターを評価し、succeed が false に設定されている場合にのみ実行されます。

パイプライン内の 2 番目のジョブは最初のジョブに依存しており、最初のジョブが失敗した場合にのみ実行されます。 2 番目のジョブでは、Azure DevOps CLI az boards work-item create コマンドを使用してバグを作成します。パイプラインから Azure DevOps CLI コマンドを実行する方法の詳細については、「YAML パイプラインでコマンドを実行する」を参照してください。

YAML パイプラインには、クラシックビルドパイプラインのような [失敗時に作業項目を作成] 設定はありません。クラシックビルドパイプラインは単一ステージであり、[失敗時に作業項目を作成] はパイプライン全体に適用されます。 YAML パイプラインは複数ステージになる可能性があり、パイプラインレベルの設定が適切でない場合があります。 YAML パイプラインに [失敗時に作業項目を作成] を実装するには、パイプラインの目的のポイントで作業項目の作成 REST API 呼び出しを使用できます。

# When manually running the pipeline, you can select whether it
# succeeds or fails.
parameters:
- name: succeed
  displayName: Succeed or fail
  type: boolean
  default: false

trigger:
- main

pool:
  vmImage: ubuntu-latest

jobs:
- job: Work
  steps:
  - script: echo Hello, world!
    displayName: 'Run a one-line script'

  # This malformed command causes the job to fail
  # Only run this command if the succeed variable is set to false
  - script: git clone malformed input
    condition: eq(${{ parameters.succeed }}, false)

# This job creates a work item, and only runs if the previous job failed
- job: ErrorHandler
  dependsOn: Work
  condition: failed()
  steps: 
  - bash: |
      curl \
        -X POST \
        -H 'Authorization: Basic $(System.AccessToken)' \
        -H 'Content-Type: application/json-patch+json' \
        -d '[
              {
                "op": "add",
                "path": "/fields/System.Title",
                "from": null,
                "value": "git clone failed"
              }
            ]' \
        "$(System.CollectionUri)$(System.TeamProject)/_apis//wit/workitems/$Bug?api-version=7.1-preview.3
"
    env:
        SYSTEM_ACCESSTOKEN: $(System.AccessToken)
    displayName: 'Create work item on failure'

注意

パイプライン内の 2 番目のジョブは最初のジョブに依存しており、最初のジョブが失敗した場合にのみ実行されます。 2 番目のジョブでは、Azure DevOps API az boards work-item create コマンドを使用してバグを作成します。

この例では 2 つのジョブを使用しますが、この同じ方法を複数のステージで使用できます。

注意

YAML 複数ステージパイプラインをサポートしているリリースエラー時のバグの作成などのマーケットプレース拡張機能を使用することもできます。

次のステップ

パイプラインのカスタマイズの基本を学習しました。次に、使用する言語のパイプラインのカスタマイズの詳細を学習することをお勧めします。

または、CI パイプラインを CI/CD パイプラインに拡張するには、アプリを環境にデプロイする手順を含むデプロイジョブを含めます。

このガイドのトピックの詳細については、ジョブ、タスク、タスクのカタログ、変数、トリガー、またはトラブルシューティングを参照してください。

YAML パイプラインで他にできることについては、YAML スキーマのリファレンスを参照してください。

次の方法で共有

パイプラインをカスタマイズする

前提条件

`azure-pipelines.yml` ファイルの概要

ビルドするプラットフォームを変更する

ステップを追加する

複数のプラットフォーム間でのビルド

複数のバージョンを使用してビルドする

CI トリガーをカスタマイズする

パイプラインの設定

セキュリティの管理

失敗時に作業項目を作成

次のステップ

フィードバック

その他のリソース

次の方法で共有

パイプラインをカスタマイズする

前提条件

azure-pipelines.yml ファイルの概要

ビルドするプラットフォームを変更する

ステップを追加する

複数のプラットフォーム間でのビルド

複数のバージョンを使用してビルドする

CI トリガーをカスタマイズする

パイプラインの設定

セキュリティの管理

失敗時に作業項目を作成

次のステップ

フィードバック

その他のリソース

`azure-pipelines.yml` ファイルの概要