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

[アーティクル]
10/27/2023

Azure DevOps Services | Azure DevOps Server 2022

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

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

ヒント

Azure DevOps 拡張機能 SDK を使用した拡張機能開発に関する最新のドキュメントを確認してください。

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

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

拡張機能を作成します。拡張機能が作成されると、ファイルが作成されます vss-extension.json 。
新しいパイプラインデコレーターのファイルに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"
        }
    ]
}

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

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

プロパティ	説明
`id`	コントリビューション識別子。この拡張機能のコントリビューション間で一意である必要があります。
`type`	このコントリビューションがパイプラインデコレーターであることを指定します。文字列 `ms.azure-pipelines.pipeline-decorator`にする必要があります。
`targets`	デコレーターは、ジョブ/指定されたタスクの前、後、またはその両方の前に実行できます。使用可能なオプションについては、次の表を参照してください。
`properties.template`	(必須)テンプレートは、パイプラインデコレーターの手順を定義する拡張機能に含まれる YAML ファイルです。これは、拡張機能フォルダーのルートからの相対パスです。
`properties.targettask`	使用される `ms.azure-pipelines-agent-job.pre-task-tasks` ターゲットタスク ID または `ms.azure-pipelines-agent-job.post-task-tasks` ターゲット。次のような GUID 文字列にする必要があります `89b8ac58-8cb7-4479-a362-1baaacc6c7ad`

目標値

移行先	説明
`ms.azure-pipelines-agent-job.pre-job-tasks`	クラシックビルドまたは YAML パイプライン内の他のタスクの前に実行します。ソースコードチェックアウトの発生方法の違いにより、このターゲットは YAML パイプラインでチェックした後、クラシックビルドパイプラインでチェックアウトする前に実行されます。
`ms.azure-pipelines-agent-job.post-checkout-tasks`	クラシックビルドまたは YAML パイプラインの最後 `checkout` のタスクの後に実行します。
`ms.azure-pipelines-agent-job.post-job-tasks`	クラシックビルドまたは YAML パイプライン内の他のタスクの後に実行します。
`ms.azure-pipelines-agent-job.pre-task-tasks`	クラシックビルドまたは YAML パイプラインで指定されたタスクの前に実行します。
`ms.azure-pipelines-agent-job.post-task-tasks`	クラシックビルドまたは YAML パイプラインで指定したタスクの後に実行します。
`ms.azure-release-pipelines-agent-job.pre-task-tasks`	クラシック RM パイプラインで指定されたタスクの前に実行します。
`ms.azure-release-pipelines-agent-job.post-task-tasks`	クラシック RM パイプラインで指定したタスクの後に実行します。
`ms.azure-release-pipelines-agent-job.pre-job-tasks`	クラシック RM パイプライン内の他のタスクの前に実行します。
`ms.azure-release-pipelines-agent-job.post-job-tasks`	クラシック RM パイプライン内の他のタスクの後に実行します。

Note

YAML パイプライン内のデプロイジョブは、サポートとターゲットのみをサポート ms.azure-pipelines-agent-job.pre-job-tasks します ms.azure-pipelines-agent-job.post-job-tasks 。ジョブでは、すべての YAML パイプラインターゲットがサポートされます。

この例では、すべてのビルドジョブの最後に実行する必要があるために使用 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

Note

サービス接続を使用するパイプラインデコレータータスクは、クラシックリリースパイプラインではサポートされていません。

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

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

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

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

Pipeline decorator running a simple script

Note

デコレーターは、組織内のすべてのパイプラインのすべてのジョブで実行されます。後の手順では、デコレーターを実行するタイミングと方法を制御するロジックを追加します。

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')必要があります。

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

Note

この機能は、ターゲットタスクの前または後に挿入されたタスクでのみ使用できます。

この入力の一覧を指定するには、次の例のように 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

Note

変数を含むシークレット値を取得したり、他のタスクから取得したりするターゲットタスク入力は挿入されません。

デバッグ

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

パイプラインをキューにsystem.debugContexttrue入れるときに変数を設定できます。次に、パイプラインの概要ページを確認します。

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

View pipeline decorator context

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

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

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

vss-extension.json

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

目標値

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

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

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

4. 注入条件

my-decorator.yml (改訂版)

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

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

vss-extension.json

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

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

デバッグ

フィードバック

フィードバック

その他のリソース

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

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

vss-extension.json

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

目標値

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

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

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

4. 注入条件

my-decorator.yml (改訂版)

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

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

vss-extension.json

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

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

デバッグ

関連記事

フィードバック

フィードバック

その他のリソース

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

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

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

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