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

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 つの方法は、strategymatrix を使うことです。 変数を使用して、パイプラインのさまざまな部分にデータを便利に配置できます。 この例では、変数を使用して、使用するイメージの名前を渡します。

  • 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 呼び出しを使用できます。

次の例には 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: |
      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'

注意

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

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

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

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

注意

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

次のステップ

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

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

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

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