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

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

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`または`ms.azure-pipelines-agent-job.post-task-tasks`ターゲットに使用されるターゲットタスク ID。次のような 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 スクリプトを自動的に挿入します。パイプラインの実行は、次の例のようになります。

単純なスクリプトを実行するパイプラインデコレーター

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') など) を使用する必要があります。

これを行うには、独自のカスタムパイプライン task を作成し、そこでターゲット入力を使用できます。 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.debugContext 変数を true するように設定できます。次に、パイプラインの概要ページを確認します。

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

パイプラインデコレーターコンテキストを表示する

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

次の方法で共有

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

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. ターゲットタスクを指定する

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