워크플로 포맷 - YAML

VPC 환경에서 이용 가능합니다.

워크플로 파일은 정해진 포맷에 맞게 작성되어야만 유효한 워크플로로 인식되며 실행이 가능합니다.
이 문서에서는 워크플로 정의에 필요한 YAML 포맷과 각 속성의 의미에 대해 설명합니다.

워크플로 기본 구조

Name: <workflow-name>
Version: v1
Triggers:
  - Type: PUSH
    Branches:
      - main
Actions:
  <action-name>:
    # Identifies the action. Do not modify this value.
    Identifier: ncp/sourcebuild@v1.0.0
    # Defines the action's properties.
    Config:
       ....

워크플로 이름

워크플로 이름을 지정합니다.
이름은 다음과 같은 조건을 만족해야 합니다

• 최소 1자 이상이어야 합니다.
• 최대 100자 이하여야 합니다.
• 영문 대소문자(A-Z, a-z), 숫자(0-9), 하이픈(-), 언더스코어(_)만 사용할 수 있습니다.

워크플로 스키마 버전

워크플로 스키마에 대한 버전정보를 명시적으로 지정합니다.

워크플로 트리거 설정

워크플로 트리거는 특정 이벤트가 발생했을 때 워크플로를 자동으로 실행하도록 설정하는 영역입니다.

트리거는 리스트 형태로 정의되며, 여러 개의 트리거를 병렬로 설정할 수 있습니다.
현재는 PUSH 트리거만 지원되며, 추후 PR, SCHEDULE 등 다양한 트리거 타입이 추가될 예정입니다.
트리거 설정은 아래와 같은 포맷을 따릅니다.

푸시 트리거 (Type: PUSH)

푸시 트리거는 리포지토리에 Push 이벤트가 발생했을 때 워크플로를 실행하도록 설정합니다.

Triggers:
  - Type: PUSH
    Branches:
      - main
      - dev

위 예시에서는 main, dev 브랜치로의 Push 이벤트가 발생할 경우 워크플로가 실행됩니다.

브랜치를 제한하지 않고 모든 브랜치에서 Push 이벤트를 감지하려면 Branches 속성을 생략할 수 있습니다.

Triggers:
  - Type: PUSH

워크플로 액션 기본구조

워크플로에서 실제로 실행되는 작업 단위를 "액션"이라고 하며, Actions는 하나 이상의 액션을 정의하는 필수 항목입니다.
액션은 지정한 순서 또는 조건에 따라 실행되며, 리소스를 빌드하거나 배포하는 등 정의된 액션에 따라 다양한 작업을 수행합니다.

Actions:
  <action-name>:
    # Identifies the action. Do not modify this value.
    Identifier: ncp/sourcebuild@v1.0.0
    # Defines the action's properties.
    Config:
      # Specifies the resource you want to use
      Resource:
        ...
    DependsOn:
      - <previous-action>

액션 이름은 Actions 하위 객체의 키(Key)로 사용되며, 고유해야 합니다. 각 액션은 다음과 같은 속성을 가집니다:

Identifier

Identifier는 실행할 액션을 지정하는 고유 식별자입니다.
올바르지 않은 포맷의 식별자는 유효성 검사에서 오류가 발생할 수 있습니다.

예: ncp/sourcebuild@v1.0.0

Config

Config는 각 액션의 실행을 위한 설정 값을 지정하는 영역입니다.
해당 속성의 포맷은 사용하는 액션의 Identifier에 따라 달라지므로, 해당 액션에 맞는 포맷을 확인해야 합니다.

자세한 Config 포맷은 워크플로 액션 목록 문서를 참고해 주십시오.

DependsOn

DependsOn은 해당 액션이 실행되기 전에 반드시 완료되어야 하는 선행 액션을 지정할 수 있는 속성입니다.
액션 이름 또는 액션 그룹 이름을 나열하여 정의할 수 있으며, 순차 실행이 필요한 경우 유용하게 사용할 수 있습니다.

액션 그룹 기능

여러 액션을 하나의 그룹으로 묶어 논리적 단위를 구성할 수 있습니다.

Actions:
  <action-group-name>:
    Actions:
      <action-name-1>:
        ....
        DependsOn:
	      - <action-name-2>
      <action-name-2>:
        ....
    DependsOn:
      - <other-action-name>

액션 이름 하위로 Actions 속성을 추가하면 해당 영역은 액션 그룹으로 사용됩니다.
액션 그룹 하위 속성의 설명은 아래와 같습니다.

워크플로 유효성 검사

워크플로 파일은 다음 조건을 충족해야만 유효한 워크플로로 판정됩니다.

• YAML 문법 오류가 없어야 함
• 필수 속성 누락 없이 스키마를 준수해야 함
• 액션 이름, 그룹 이름이 중복되지 않아야 함
• DependsOn에서 정의되지 않은 이름을 참조하지 않아야 함

이를 만족하지 않을시 invalid 상태로 분류되어, 실행이 불가능하게 됩니다.

전체 예시

Name: example-workflow
Version: v1
Triggers:
  - Type: PUSH
    Branches:
      - main
Actions:
  build:
    Identifier: ncp/sourcebuild@v1.0.0
    Config:
      Resource:
        ProjectName: example
  deploy:
    Identifier: ncp/sourcedeploy-server@v1.0.0
    Config:
      Resource:
        ProjectName: example
        StageName: example-stage
        ScenarioName: example-scenario
    DependsOn:
      - build