파이프라인 데코레이터 작성

아티클
10/27/2023

Azure DevOps Services | Azure DevOps Server 2022

파이프라인 데코레이터를 사용하면 모든 작업의 시작과 끝에 단계를 추가할 수 있습니다. 파이프라인 데코레이터를 작성하는 프로세스는 조직의 모든 파이프라인에 적용되므로 단일 정의에 단계를 추가하는 프로세스와 다릅니다.

조직에서 릴리스할 수 있는 모든 빌드 출력에서 바이러스 스캐너를 실행해야 한다고 가정합니다. 파이프라인 작성자는 해당 단계를 추가할 필요가 없습니다. 단계를 자동으로 삽입하는 데코레이터를 만듭니다. 파이프라인 데코레이터는 모든 파이프라인 작업이 끝날 때 바이러스 검사를 수행하는 사용자 지정 작업을 삽입합니다.

팁

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.post-task-tasks` 대상에 `ms.azure-pipelines-agent-job.pre-task-tasks` 사용되는 대상 작업 ID입니다. GUID 문자열은 다음과 같아야 합니다. `89b8ac58-8cb7-4479-a362-1baaacc6c7ad`

대상

대상	설명
`ms.azure-pipelines-agent-job.pre-job-tasks`	클래식 빌드 또는 YAML 파이프라인에서 다른 작업 전에 실행합니다. 소스 코드 검사out이 발생하는 방식의 차이로 인해 이 대상은 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 파이프라인에서 다른 작업을 실행합니다.

참고 항목

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

참고 항목

서비스 연결 사용량이 있는 파이프라인 데코레이터 작업은 클래식 릴리스 파이프라인에서 지원되지 않습니다.

3. 데코레이터 설치

조직에 파이프라인 데코레이터를 추가하려면 확장을 설치해야 합니다. 프라이빗 확장만 파이프라인 데코레이터에 기여할 수 있습니다. 확장을 사용하려면 먼저 확장을 작성하고 조직과 공유해야 합니다.

확장이 조직 과 공유되면 확장을 검색하고 설치합니다.

파일을 저장한 다음 , 확장을 빌드하고 설치합니다. 기본 파이프라인을 만들고 실행합니다. 데코레이터는 모든 작업의 끝에 스크립트를 자동으로 삽입합니다 dir . 파이프라인 실행은 다음 예제와 유사합니다.

Pipeline decorator running a simple script

참고 항목

데코레이터는 조직의 모든 파이프라인에 있는 모든 작업에서 실행됩니다. 이후 단계에서는 데코레이터가 실행되는 시기와 방법을 제어하는 논리를 추가합니다.

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_)에 액세스하려면 삽입된 파이프라인 태스크는 파이프라인 변수const inputString = tl.getInput('target_targetInput')가 아닌 azure-pipelines-tasks-task-lib의 메서드를 사용해야 합니다.

이렇게 하려면 사용자 고유의 사용자 지정 파이프라인 작업을 만들고 그곳에서 대상 입력을 사용할 수 있습니다. 다음과 같은 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 설정할 수 있습니다. 그런 다음 파이프라인 요약 페이지를 확인합니다.

다음 이미지와 비슷한 내용이 표시됩니다.

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(삽입된 작업 입력 버전)

디버그

관련된 문서

피드백

피드백

추가 리소스