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

아티클
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 파이프라인에서 다른 작업 전에 실행합니다. 소스 코드 체크 아웃이 발생하는 방식의 차이로 인해 이 대상은 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 . 파이프라인 실행은 다음 예제와 유사합니다.

간단한 스크립트를 실행하는 파이프라인 데코레이터

참고 항목

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

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 설정할 수 있습니다. 그런 다음 파이프라인 요약 페이지를 확인합니다.

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

파이프라인 데코레이터 컨텍스트 보기

태스크를 선택하여 런타임 값을 표시하고 컨텍스트를 사용할 수 있는 로그를 확인합니다.

다음을 통해 공유

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

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

디버그

관련된 문서

피드백

추가 리소스