--- title: "워크플로 포맷 - YAML" slug: "sourceband-workflow-use-format" updated: 2026-09-17T09:07:44Z published: 2026-09-17T09:07:44Z canonical: "guide.ncloud-docs.com/sourceband-workflow-use-format" stale: true --- > ## Documentation Index > Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # 워크플로 포맷 - YAML VPC 환경에서 이용 가능합니다. 워크플로 파일은 정해진 포맷에 맞게 작성되어야만 유효한 워크플로로 인식되며 실행이 가능합니다. 이 문서에서는 워크플로 정의에 필요한 YAML 포맷과 각 속성의 의미에 대해 설명합니다. ## 워크플로 기본 구조 ``` Name: Version: v1 Triggers: - Type: PUSH Branches: - main Actions: : # Identifies the action. Do not modify this value. Identifier: ncp/sourcebuild@v1.0.0 # Defines the action's properties. Config: .... ``` | 속성 이름 | 설명 | 필수 여부 | | --- | --- | --- | | Name | 워크플로 이름 | O | | Version | 워크플로 스키마 버전 | O | | Triggers | 워크플로 트리거 설정 | X | | Actions | 워크플로 액션 정의 | O | ### 워크플로 이름 워크플로 이름을 지정합니다. 이름은 다음과 같은 조건을 만족해야 합니다 - 최소 1자 이상이어야 합니다. - 최대 100자 이하여야 합니다. - 영문 대소문자(A-Z, a-z), 숫자(0-9), 하이픈(-), 언더스코어(_)만 사용할 수 있습니다. 주의 - 워크플로 이름은 콘솔 내 워크플로 목록에서 확인할 수 있는 항목이며, 저장되는 파일 이름과는 무관합니다. ### 워크플로 스키마 버전 워크플로 스키마에 대한 버전정보를 명시적으로 지정합니다. 참고 - 현재 지원되는 워크플로 스키마 버전은 `v1`입니다. ### 워크플로 트리거 설정 워크플로 트리거는 특정 이벤트가 발생했을 때 워크플로를 자동으로 실행하도록 설정하는 영역입니다. 트리거는 리스트 형태로 정의되며, 여러 개의 트리거를 병렬로 설정할 수 있습니다. 현재는 `PUSH` 트리거만 지원되며, 추후 `PR`, `SCHEDULE` 등 다양한 트리거 타입이 추가될 예정입니다. 트리거 설정은 아래와 같은 포맷을 따릅니다. | 속성 이름 | 설명 | 필수 여부 | | --- | --- | --- | | Type | 이벤트 타입 (예: PUSH, PR, SCHEDULE 등) | O | | Branches | 이벤트를 감지할 브랜치 목록 (Type이 PUSH일 경우) | X | #### 푸시 트리거 (Type: PUSH) 푸시 트리거는 리포지토리에 Push 이벤트가 발생했을 때 워크플로를 실행하도록 설정합니다. ``` Triggers: - Type: PUSH Branches: - main - dev ``` 위 예시에서는 `main`, `dev` 브랜치로의 Push 이벤트가 발생할 경우 워크플로가 실행됩니다. 주의 - `Branches` 속성에 명시된 브랜치에 워크플로 파일이 존재해야만 해당 브랜치에서 Push 이벤트 발생 시 워크플로가 실행됩니다. - 예를 들어, 위와 같은 설정의 워크플로 파일이 `main` 브랜치에만 존재하고 `dev` 브랜치에는 존재하지 않는다면, `dev` 브랜치에서 Push가 발생해도 워크플로는 실행되지 않습니다. 브랜치를 제한하지 않고 모든 브랜치에서 Push 이벤트를 감지하려면 `Branches` 속성을 생략할 수 있습니다. ``` Triggers: - Type: PUSH ``` ## 워크플로 액션 기본구조 워크플로에서 실제로 실행되는 작업 단위를 "액션"이라고 하며, `Actions`는 하나 이상의 액션을 정의하는 필수 항목입니다. 액션은 지정한 순서 또는 조건에 따라 실행되며, 리소스를 빌드하거나 배포하는 등 정의된 액션에 따라 다양한 작업을 수행합니다. ``` Actions: : # 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: - ``` 액션 이름은 `Actions` 하위 객체의 키(Key)로 사용되며, 고유해야 합니다. 각 액션은 다음과 같은 속성을 가집니다: | 속성 이름 | 설명 | 필수 여부 | | --- | --- | --- | | Identifier | 실행할 액션의 고유 식별자입니다. "액션명@버전" 포맷으로 지정합니다. | O | | Config | 해당 액션의 세부 설정 항목입니다. 액션 유형에 따라 구성 항목이 달라집니다. | O | | DependsOn | 다른 액션 실행이 선행되어야 할 경우, 의존 관계를 명시합니다. | X | ### Identifier `Identifier`는 실행할 액션을 지정하는 고유 식별자입니다. 올바르지 않은 포맷의 식별자는 유효성 검사에서 오류가 발생할 수 있습니다. 예: `ncp/sourcebuild@v1.0.0` ### Config `Config`는 각 액션의 실행을 위한 설정 값을 지정하는 영역입니다. 해당 속성의 포맷은 사용하는 액션의 Identifier에 따라 달라지므로, 해당 액션에 맞는 포맷을 확인해야 합니다. 자세한 Config 포맷은 [워크플로 액션 목록](/docs/sourceband-workflow-use-actions) 문서를 참고해 주십시오. ### DependsOn `DependsOn`은 해당 액션이 실행되기 전에 반드시 완료되어야 하는 선행 액션을 지정할 수 있는 속성입니다. 액션 이름 또는 액션 그룹 이름을 나열하여 정의할 수 있으며, 순차 실행이 필요한 경우 유용하게 사용할 수 있습니다. 주의 - `DependsOn` 설정 시 워크플로 내에서 순환 의존(Cycle)이 발생하지 않도록 주의해야 합니다. - 예: 액션 `A`의 `DependsOn` 설정에 액션 `B`를 지정하고, 액션 `B`의 `DependsOn` 설정에 액션 `A`를 지정한 경우, 순환 의존(Cycle)이 발생하므로 올바르지 않은 워크플로에 해당합니다. ### 액션 그룹 기능 여러 액션을 하나의 그룹으로 묶어 논리적 단위를 구성할 수 있습니다. ``` Actions: : Actions: : .... DependsOn: - : .... DependsOn: - ``` 액션 이름 하위로 Actions 속성을 추가하면 해당 영역은 액션 그룹으로 사용됩니다. 액션 그룹 하위 속성의 설명은 아래와 같습니다. | 속성 이름 | 설명 | 필수 여부 | | --- | --- | --- | | Actions | 액션 그룹에 포함될 액션들을 표현하는 영역 | O | | DependsOn | 액션간의 의존관계를 설정하는 영역 | X | 참고 - 액션 그룹도 일반 액션처럼 외부의 액션그룹 또는 액션에 대해 `DependsOn` 을 설정할 수 있습니다. - 액션 그룹 내 액션은 그룹 내부의 액션에 대해서만 `DependsOn`을 설정할 수 있습니다. - 액션 그룹 외부의 액션은 그룹 내부 액션에 `DependsOn`을 지정할 수 없습니다. 주의 - 액션 그룹 안에 액션 그룹을 중첩해서 정의할 수 없습니다. - 시각적 편집기(Visual Editor)에서는 액션 그룹 구성이 지원되지 않으며, YAML을 통해서만 구성할 수 있습니다. ## 워크플로 유효성 검사 워크플로 파일은 다음 조건을 충족해야만 유효한 워크플로로 판정됩니다. - YAML 문법 오류가 없어야 함 - 필수 속성 누락 없이 스키마를 준수해야 함 - 액션 이름, 그룹 이름이 중복되지 않아야 함 - `DependsOn`에서 정의되지 않은 이름을 참조하지 않아야 함 이를 만족하지 않을시 `invalid` 상태로 분류되어, 실행이 불가능하게 됩니다. 주의 - 외부 서비스에 존재하는 리소스 관련 설정은 유효성 검사에서 확인되지 않습니다. - 예: `ncp/sourcebuild@v1.0.0` 액션의 `Config > Resource > ProjectName` 설정 값이 실제 존재하는지는 유효성 검사 시에 확인되지 않으며, 워크플로 실행 중 해당 액션의 실패를 통해 리소스 존재 유무를 간접적으로 확인할 수 있습니다. ### 전체 예시 ``` 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 ```