ワークフローフォーマット - 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は1つ以上のアクションを定義する必須項目です。
アクションは指定した手順または条件に従って実行され、リソースのビルドやリリースなどの定義されたアクションによって様々なタスクを行います。

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は実行するアクションを指定する固有 IDです。
無効なフォーマットの識別子は有効性検証でエラーが発生することがあります。

例: ncp/sourcebuild@v1.0.0

Config

Configは各アクションを実行するための設定値を指定する領域です。
当該プロパティのフォーマットは使用するアクションの Identifierによって異なるため、そのアクションに合ったフォーマットを確認する必要があります。

詳細な Configフォーマットは、ワークフローアクションリストドキュメントをご参照ください。

DependsOn

DependsOnは、当該アクションを実行する前に、必ず完了すべき先行アクションを指定できるプロパティです。
アクション名またはアクショングループ名を表示し定義でき、順次実行が必要な場合は有効に使用できます。

アクショングループ機能

複数のアクションを1つのグループにまとめて論理的単位を構成できます。

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