パイプライン デコレーターの作成

Azure DevOps Services | Azure DevOps Server 2022

パイプライン デコレーターを使用すると、すべてのジョブの先頭と末尾にステップを追加できます。 パイプライン デコレーターを作成するプロセスは、組織内のすべてのパイプラインに適用されるため、1 つの定義にステップを追加するプロセスとは異なります。

組織で、リリース可能なすべてのビルド出力でウイルス スキャナーを実行する必要があるとします。 パイプライン作成者は、そのステップを追加することを忘れずに行う必要はありません。 ステップを自動的に挿入するデコレーターを作成します。 パイプライン デコレーターは、すべてのパイプライン ジョブの最後にウイルス スキャンを行うカスタム タスクを挿入します。

1. 拡張機能にコントリビューションを追加する

次の例では、 コントリビューション モデルを理解していることを前提としています。

1. 拡張機能を作成します。 拡張機能が作成されると、 vss-extension.json ファイルが作成されます。
2. 新しいパイプライン デコレーターの vss-extension.json ファイルにコントリビューションを追加します。

vss-extension.json

{
    "manifestVersion": 1,
    "contributions": [
        {
            "id": "my-required-task",
            "type": "ms.azure-pipelines.pipeline-decorator",
            "targets": [
                "ms.azure-pipelines-agent-job.post-job-tasks"
            ],
            "properties": {
                "template": "my-decorator.yml"
            }
        }
    ],
    "files": [
        {
            "path": "my-decorator.yml",
            "addressable": true,
            "contentType": "text/plain"
        }
    ]
}

コントリビューション オプション

プロパティとその用途を見てみましょう。

目標値

この例では、すべてのビルド ジョブの最後に実行する必要があるため、 ms.azure-pipelines-agent-job.post-job-tasks を使用します。

この拡張機能は、パイプライン デコレーターを提供します。 次に、デコレーターの動作を定義するテンプレート YAML ファイルを作成します。

2. デコレーター YAML ファイルを作成する

拡張機能のプロパティで、"my-decorator.yml" という名前を選択しました。 投稿のルートにそのファイルを作成します。 各ジョブの後に実行する一連のステップが保持されます。 基本的な例から始めて、完全なタスクまで作業します。

my-decorator.yml (初期バージョン)

steps:
- task: CmdLine@2
  displayName: 'Run my script (injected from decorator)'
  inputs:
    script: dir

3. デコレータを取り付け

パイプライン デコレーターを組織に追加するには、拡張機能 インストールする必要があります。 パイプライン デコレーターを提供できるのはプライベート拡張機能のみです。 拡張機能を使用するには、その拡張機能を作成して組織と共有する必要があります。

拡張機能が組織と共有されたら、拡張機能を検索インストールします。

ファイルを保存し、 ビルドして拡張機能をインストールします。 基本的なパイプラインを作成して実行します。 デコレーターは、すべてのジョブの最後に dir スクリプトを自動的に挿入します。 パイプラインの実行は、次の例のようになります。

4. 注入条件

この例では、ビルド出力が一般にリリースされる可能性がある場合にのみ、ウイルス スキャナーを実行する必要があります。 たとえば、既定のブランチ (通常はmain) からのビルドのみがリリースされているとします。 デコレーターは、既定のブランチに対して実行されているジョブに制限する必要があります。

更新されたファイルは次のようになります。

my-decorator.yml (改訂版)

steps:
- ${{ if eq(resources.repositories['self'].ref, resources.repositories['self'].defaultBranch) }}:
  - script: dir
    displayName: 'Run my script (injected from decorator)'

この機能拡張ポイントの機能を確認できます。 現在のジョブのコンテキストを使用して、実行時にステップを条件付きで挿入します。 YAML 式を使用して、挿入する手順とタイミングを決定します。 使用可能なデータの完全な一覧についてはパイプライン デコレーター式コンテキストを参照してください。

考慮する必要がある別の条件があります。ユーザーがウイルススキャン手順を既に含めている場合はどうなりますか? もう一度実行する時間を無駄にしないでください。 この簡単な例では、ジョブで見つかった script タスクがウイルス スキャナーを実行しているふりをします。 (実際の実装では、代わりにチェックするカスタム タスクがあります)。

スクリプト タスクの ID が d9bafed4-0b18-4f58-968d-86655b4d2ce9。 別のスクリプト タスクが表示される場合は、挿入しないでください。

my-decorator.yml (最終バージョン)

steps:
- ${{ if and(eq(resources.repositories['self'].ref, resources.repositories['self'].defaultBranch), not(containsValue(job.steps.*.task.id, 'd9bafed4-0b18-4f58-968d-86655b4d2ce9'))) }}:
  - script: dir
    displayName: 'Run my script (injected from decorator)'

5. ターゲット タスクを指定する

ターゲット タスク ID を指定し、このターゲット タスクの前または後にタスクを挿入できます。 ターゲット タスクを指定するには、次の例のようにマニフェスト ファイルvss-extension.json変更します。

vss-extension.json

{
    "contributions": [
        {
            "id": "my-required-task",
            "type": "ms.azure-pipelines.pipeline-decorator",
            "targets": [
                "ms.azure-pipelines-agent-job.pre-task-tasks",
                "ms.azure-pipelines-agent-job.post-task-tasks"
            ],
            "properties": {
                "template": "my-decorator.yml",
                "targettask": "target-task-id"
            }
        }
    ],
    ...
}

'targettask' プロパティを設定するときに、ターゲット タスクの ID を指定できます。 タスクは、指定したターゲット タスクのすべてのインスタンスの前後に挿入されます。

ターゲット タスクの入力挿入を指定する

挿入されるタスクへの入力として挿入するターゲット タスクの入力の一覧を指定できます。

この機能は、 カスタム パイプライン タスクを操作するように設計されています。 これは、パイプライン変数を介してターゲット パイプライン タスク入力へのアクセスを提供することを目的としていません。

ターゲット パイプライン タスクの入力 ( target_ プレフィックスを持つ入力) にアクセスするには、挿入されたパイプライン タスクで、パイプライン変数ではなく、 azure-pipelines-tasks-task-lib のメソッド ( const inputString = tl.getInput('target_targetInput') など) を使用する必要があります。

これを行うには、独自のカスタム パイプライン task を作成し、そこでターゲット入力を使用できます。 CmdLine@2など、いずれかのすぐに使用できるタスクの機能が必要な場合は、CmdLine@2 タスクのコピーを作成しデコレーター拡張機能を使用して発行できます。

この入力の一覧を指定するには、次の例のようにマニフェスト ファイルvss-extension.json変更します。

vss-extension.json (挿入されたタスク入力バージョン)

{
    "contributions": [
        {
            "id": "my-required-task",
            "type": "ms.azure-pipelines.pipeline-decorator",
            "targets": [
                "ms.azure-pipelines-agent-job.pre-task-tasks",
                "ms.azure-pipelines-agent-job.post-task-tasks"
            ],
            "properties": {
                "template": "my-decorator.yml",
                "targettask": "target-task-id",
                "targettaskinputs": ["target-task-input", "target-task-second-input"]
            }
        }
    ],
    ...
}

'targettaskinputs' プロパティを設定することで、挿入する必要がある入力の一覧を指定できます。 これらの入力は、プレフィックス "target_" を持つタスクに挿入され、 target_target-task-inputなどの挿入されたタスクで使用できるようになります。

デバッグ

デコレーターを作成するときにデバッグが必要になる場合があります。 また、コンテキストで使用できるデータを確認することもできます。

パイプラインをキューに登録するときに、 system.debugContext 変数を true するように設定できます。 次に、パイプラインの概要ページを確認します。

次の図のような内容が表示されます。

タスクを選択すると、ランタイム値とコンテキストが使用可能であることが示されるログが表示されます。

関連記事

• YAML 式の構文について
• パイプライン デコレーター式コンテキスト
• Web 拡張機能を開発する
• 認証ガイド