ワークフロー YAML 定義

ワークフロー定義ファイルのリファレンスドキュメントを次に示します。

ワークフロー定義ファイルは、ワークフローを記述する YAML ファイルです。ファイルは、ソースリポジトリのルートにある~/.codecatalyst/workflows/フォルダに保存されます。ファイルには、.yml または .yaml 拡張子を付けることができます。

ワークフロー定義ファイルを作成および編集するには、vim などのエディタを使用するか、 CodeCatalyst コンソールのビジュアルエディタまたは YAML エディタを使用できます。詳細については、「 CodeCatalyst コンソールのビジュアルエディタと YAML エディタの使用」を参照してください。

注記

後続の YAML プロパティのほとんどには、対応する UI 要素がビジュアルエディタにあります。UI 要素を検索するには、Ctrl+F を使用します。要素は、関連付けられた YAML プロパティとともに一覧表示されます。

ワークフロー定義ファイルの例

以下は、シンプルなワークフロー定義ファイルの例です。これには、いくつかの最上位プロパティ、 Triggersセクション、および Buildとの 2 つのアクションを含む Actionsセクションが含まれますTest。詳細については、「ワークフロー定義ファイルについて」を参照してください。


Name: MyWorkflow
SchemaVersion: 1.0
RunMode: QUEUED
Triggers:
  - Type: PUSH
    Branches:
      - main
Actions:
  Build:
    Identifier: aws/build@v1
    Inputs:
      Sources:
        - WorkflowSource
    Configuration:     
      Steps:
        - Run: docker build -t MyApp:latest .
  Test:
    Identifier: aws/managed-test@v1
    DependsOn: 
      - Build
    Inputs:
      Sources:
        - WorkflowSource
    Configuration:
      Steps:
        - Run: npm install
        - Run: npm run test

構文のガイドラインと規則

このセクションでは、ワークフロー定義ファイルの構文ルールと、このリファレンスドキュメントで使用される命名規則について説明します。

YAML 構文ガイドライン

ワークフロー定義ファイルは YAML で記述され、YAML 1.1 仕様に従っているため、その仕様で許可されているものはワークフロー YAML でも許可されます。YAML を初めて使用する場合は、有効な YAML コードを提供していることを確認するための簡単なガイドラインをいくつか紹介します。

大文字と小文字の区別: ワークフロー定義ファイルは大文字と小文字が区別されるため、このドキュメントに示されている大文字と小文字を使用してください。
特殊文字 : プロパティ値には、、{、、}、、、[]、、、、、?|-< * 、＞#、、=、!、%@、:、 ` のいずれかの特殊文字を含む引用符または二重引用符を使用することをお勧めします。 ,

引用符を含めない場合、前述の特殊文字が予期しない解釈される可能性があります。
プロパティ名 : プロパティ名 (プロパティ値ではなく) は、英数字 (a～z、A～Z、0～9)、ハイフン (-)、アンダースコア (_) に制限されます。スペースは使用できません。プロパティ名で特殊文字やスペースを有効にするために、引用符や二重引用符を使用することはできません。

許可されていません：

'My#Build@action'

My#Build@action

My Build Action

許可：

My-Build-Action_1
エスケープコード : プロパティ値にエスケープコード ( \nやなど\t) が含まれている場合は、次のガイドラインに従ってください。
- 一重引用符を使用してエスケープコードを文字列として返します。例えば、は文字列 'my string \n my string'を返しますmy string \n my string。
- 二重引用符を使用してエスケープコードを解析します。例えば、は"my string \n my new line"以下を返します。
```
my string
my new line
```
コメント： コメントの前にを付けます#。

例：
```
Name: MyWorkflow
# This is a comment.
SchemaVersion: 1.0
```
トリプルダッシュ (---）: YAML code. CodeCatalyst ignores ---では、の後にすべてを無視します---。

命名規則

このガイドでは、 プロパティと セクションという用語を使用して、ワークフロー定義ファイルの主な項目を参照します。

プロパティは、コロン () を含むすべての項目です:。例えば、次のコードスニペットでは、、Name、、SchemaVersion、RunMode、およびのプロパティはすべて Triggers TypeですBranches。
セクションは、サブプロパティを持つ任意のプロパティです。次のコードスニペットには、1 つのTriggersセクションがあります。

注記
このガイドでは、「セクション」は「プロパティ」と呼ばれることがあり、コンテキストに応じてその逆を可視化します。
```
Name: MyWorkflow
SchemaVersion: 1.0
RunMode: QUEUED
Triggers:
  - Type: PUSH
    Branches:
      - main
```

最上位のプロパティ

以下は、ワークフロー定義ファイルの最上位プロパティのリファレンスドキュメントです。


# Name
Name: workflow-name
        
# Schema version
SchemaVersion: 1.0
        
# Run mode
RunMode: QUEUED|SUPERSEDED|PARALLEL

# Compute
Compute:  
...
            
# Triggers
Triggers:
...

# Actions
Actions:
...

Name

(必須)

ワークフローの名前。ワークフロー名はワークフローリストに表示され、通知とログに記載されています。ワークフロー名とワークフロー定義ファイル名は一致することも、異なる名前を付けることもできます。ワークフロー名は一意である必要はありません。ワークフロー名は、英数字 (a～z、A～Z、0～9)、ハイフン (-)、アンダースコア (_) に制限されています。スペースは使用できません。引用符を使用してワークフロー名の特殊文字やスペースを有効にすることはできません。

対応する UI: ビジュアルエディタ/ワークフロープロパティ/ワークフロー名

SchemaVersion

(必須)

ワークフロー定義のスキーマバージョン。現在、有効な値は 1.0 のみです。

対応する UI: なし

RunMode

(オプション)

が複数の実行 CodeCatalyst を処理する方法。次のいずれかの値を使用できます。

QUEUED – 複数の実行がキューに入れられ、順番に実行されます。キューには最大 50 回実行できます。
SUPERSEDED – 複数の実行がキューに入れられ、順番に実行されます。キューは 1 つの実行しかできないため、2 つの実行が同じキューにまとめられた場合、後の実行は以前の実行よりも優先され (引き継がれます）、以前の実行はキャンセルされます。
PARALLEL – 複数の実行が同時に実行されます。

このプロパティを省略した場合、デフォルトはですQUEUED。

詳細については、「実行のキューイング動作の設定」を参照してください。

対応する UI: ビジュアルエディタ/ワークフロープロパティ/アドバンスト/実行モード

Compute

(オプション)

ワークフローアクションを実行するために使用されるコンピューティングエンジン。コンピューティングはワークフローレベルまたはアクションレベルで指定できますが、両方を指定することはできません。ワークフローレベルで指定すると、コンピューティング設定はワークフローで定義されたすべてのアクションに適用されます。ワークフローレベルでは、同じインスタンスで複数のアクションを実行することもできます。詳細については、「アクション間でのコンピューティングの共有」を参照してください。

コンピューティングの詳細については、「」を参照してくださいワークフローのコンピューティング環境とランタイム環境の Docker イメージの設定。

対応する UI: なし


Name: MyWorkflow
SchemaVersion: 1.0
...
Compute:  
  Type: EC2 | Lambda
  Fleet: fleet-name
  SharedInstance: true | false

Type

(Compute/Type)

( Computeが設定されている場合は必須です）

コンピューティングエンジンのタイプ。次のいずれかの値を使用できます。

EC2 (ビジュアルエディタ) または EC2 (YAML エディタ）

アクション実行中の柔軟性のために最適化されました。
Lambda (ビジュアルエディタ) または Lambda (YAML エディタ）

アクションの起動速度を最適化しました。

コンピューティングタイプの詳細については、「コンピューティングタイプ」を参照してください。

対応する UI: ビジュアルエディタ/ワークフロープロパティ/アドバンスト/コンピューティングタイプ

Fleet

(Compute/Fleet)

(オプション)

ワークフローまたはワークフローアクションを実行するマシンまたはフリートを指定します。オンデマンドフリートでは、アクションが開始されると、ワークフローは必要なリソースをプロビジョニングし、アクションが終了するとマシンは破棄されます。オンデマンドフリートの例: Linux.x86-64.Large、Linux.x86-64.XLarge。オンデマンドフリートの詳細については、「」を参照してくださいオンデマンドフリートのプロパティ。

プロビジョニングされたフリートでは、ワークフローアクションを実行するように一連の専用マシンを設定します。これらのマシンはアイドル状態のままで、すぐにアクションを処理できます。プロビジョニングされたフリートの詳細については、「」を参照してくださいプロビジョニングされたフリートのプロパティ。

Fleet を省略した場合、デフォルトはですLinux.x86-64.Large。

コンピューティングフリートの詳細については、「」を参照してくださいコンピューティングフリート。

対応する UI: ビジュアルエディタ/ワークフロープロパティ/アドバンスト/コンピューティングフリート

SharedInstance

(Compute/SharedInstance)

(オプション)

アクションのコンピューティング共有機能を指定します。コンピューティング共有では、ワークフロー内のアクションは同じインスタンス (ランタイム環境イメージ) で実行されます。次のいずれかの値を使用できます。

TRUE は、ランタイム環境イメージがワークフローアクション間で共有されることを意味します。
FALSE は、ワークフロー内のアクションごとに個別のランタイム環境イメージが開始されて使用されるため、追加の設定なしでアーティファクトや変数などのリソースを共有することはできません。

コンピューティング共有の詳細については、「」を参照してくださいアクション間でのコンピューティングの共有。

対応する UI: なし

Triggers

(オプション)

このワークフローの 1 つ以上のトリガーのシーケンス。トリガーが指定されていない場合は、ワークフローを手動で開始する必要があります。

トリガーについての詳細は、「トリガーを使用したワークフローの自動実行の開始」を参照してください。

対応する UI: ビジュアルエディタ/ワークフロー図/トリガー


Name: MyWorkflow
SchemaVersion: 1.0
...
Triggers:
  - Type: PUSH
    Branches:
      - branch-name
    FilesChanged:
      - folder1/file
      - folder2/
 
  - Type: PULLREQUEST
    Events:
      - OPEN
      - CLOSED
      - REVISION
    Branches:
      - branch-name
    FilesChanged:
      - file1.txt
      
  - Type: SCHEDULE
    # Run the workflow at 10:15 am (UTC+0) every Saturday
    Expression: "15 10 ? * 7 *"
    Branches:
      - branch-name

Type

(Triggers/Type)

( が設定されている場合Triggersは必須です）

トリガーのタイプを指定します。次のいずれかの値を使用できます。

プッシュ (ビジュアルエディタ) または PUSH (YAML エディタ）

プッシュトリガーは、変更がソースリポジトリにプッシュされたときにワークフロー実行を開始します。ワークフローの実行では、プッシュ先のブランチ (つまり、送信先ブランチ) 内のファイルを使用します。
プルリクエスト (ビジュアルエディタ) または PULLREQUEST (YAML エディタ）

プルリクエストトリガーは、ソースリポジトリでプルリクエストがオープン、更新、またはクローズされたときにワークフロー実行を開始します。ワークフローの実行では、プル元のブランチ (ソースブランチ) 内のファイルを使用します。
スケジュール (ビジュアルエディタ) または SCHEDULE (YAML エディタ）

スケジュールトリガーは、指定した cron 式で定義されたスケジュールでワークフロー実行を開始します。ブランチのファイルを使用して、ソースリポジトリ内のブランチごとに個別のワークフロー実行が開始されます。（トリガーがアクティブ化されるブランチを制限するには、ブランチフィールド (ビジュアルエディタ) またはBranchesプロパティ (YAML エディタ) を使用します。）

スケジュールトリガーを設定するときは、次のガイドラインに従ってください。
- ワークフローごとに 1 つのスケジュールトリガーのみを使用します。
- CodeCatalyst スペースに複数のワークフローを定義している場合は、同時に開始するように 10 個までスケジュールすることをお勧めします。
- トリガーの cron 式は、実行間隔を十分に設定してください。詳細については、「Expression」を参照してください。

例については、「トリガーの例」を参照してください。

対応する UI: ビジュアルエディタ/ワークフロー図/トリガー/トリガータイプ

Events

(Triggers/Events)

（トリガーが Typeに設定されている場合は必須ですPULLREQUEST）

ワークフロー実行を開始するプルリクエストイベントのタイプを指定します。有効な値は次のとおりです。

プルリクエストが作成される (ビジュアルエディタ) または OPEN (YAML エディタ）

ワークフローの実行は、プルリクエストの作成時に開始されます。
プルリクエストがクローズされている (ビジュアルエディタ) または CLOSED (YAML エディタ）

ワークフロー実行は、プルリクエストがクローズされたときに開始されます。CLOSED イベントの動作はトリッキーで、例から最もよく理解できます。詳細については、「例: プル、ブランチ、および「CLOSED」イベントを含むトリガー」を参照してください。
プルリクエスト (ビジュアルエディタ) または (YAML エディタ) に新しいリビジョンが加えられました REVISION

ワークフロー実行は、プルリクエストのリビジョンが作成されると開始されます。最初のリビジョンは、プルリクエストの作成時に作成されます。その後、プルリクエストで指定されたソースブランチに誰かが新しいコミットをプッシュするたびに、新しいリビジョンが作成されます。プルリクエストトリガーREVISIONにイベントを含めると、がのスーパーセットであるため、OPENイベントREVISIONを省略できますOPEN。

同じプルリクエストトリガーで複数のイベントを指定できます。

例については、「トリガーの例」を参照してください。

対応する UI: プルリクエストのビジュアルエディタ/ワークフロー図/トリガー/イベント

Branches

(Triggers/Branches)

(オプション)

ワークフロー実行を開始するタイミングを知るために、トリガーがモニタリングするソースリポジトリ内のブランチを指定します。正規表現パターンを使用してブランチ名を定義できます。例えば、 main.*を使用して、で始まるすべてのブランチを照合しますmain。

指定するブランチは、トリガータイプによって異なります。

プッシュトリガーでは、にプッシュするブランチ、つまり送信先ブランチを指定します。一致するブランチ内のファイルを使用して、一致するブランチごとに 1 つのワークフロー実行が開始されます。

例: main.*、mainline
プルリクエストトリガーでは、にプッシュするブランチ、つまり送信先ブランチを指定します。ワークフロー定義ファイルとソースブランチ内のソースファイル (一致したブランチではない) を使用して、一致したブランチごとに 1 回のワークフロー実行が開始されます。

例: main.*、mainline、 v1\-.* ( で始まるブランチに一致v1-）
スケジュールトリガーには、スケジュールされた実行で使用するファイルを含むブランチを指定します。一致するブランチごとに 1 つのワークフロー実行が開始され、一致するブランチのワークフロー定義ファイルとソースファイルが使用されます。

例: main.*、version\-1\.0

注記

ブランチを指定しない場合、トリガーはソースリポジトリ内のすべてのブランチをモニタリングし、ワークフロー定義ファイルとソースファイルを使用してワークフロー実行を開始します。

プッシュ先のブランチ (プッシュトリガーの場合）。詳細については、「例: シンプルなコードプッシュトリガー」を参照してください。
プル元のブランチ (プルリクエストトリガーの場合）。詳細については、「例: シンプルなプルリクエストトリガー」を参照してください。
すべてのブランチ (スケジュールトリガー用）。ソースリポジトリのブランチごとに 1 回のワークフロー実行が開始されます。詳細については、「例: シンプルなスケジュールトリガー」を参照してください。

ブランチとトリガーの詳細については、「」を参照してください分岐時のトリガーに関する考慮事項。

その他の例については、「トリガーの例」を参照してください。

対応する UI: ビジュアルエディタ/ワークフロー図/トリガー/ブランチ

FilesChanged

(Triggers/FilesChanged)

（トリガーが PUSH、、またはに設定されている場合TypeはオプションPULLREQUESTです。トリガーがに設定されている場合Type、サポートされていませんSCHEDULE。）

ワークフロー実行を開始するタイミングを知るために、トリガーがモニタリングするソースリポジトリ内のファイルまたはフォルダを指定します。正規表現を使用して、ファイル名またはパスを一致させることができます。

例については、「トリガーの例」を参照してください。

対応する UI: ビジュアルエディタ/ワークフロー図/トリガー/ファイルの変更

Expression

(Triggers/Expression)

（トリガーが Typeに設定されている場合は必須ですSCHEDULE）

スケジュールされたワークフロー実行をいつ実行するかを記述する cron 式を指定します。

の Cron 式では、次の 6 つのフィールド構文 CodeCatalyst を使用します。各フィールドはスペースで区切られます。

分 時間 days-of-month 月 days-of-week年

cron 式の例

分	時間	曜日	月	曜日	年	意味
0	0	?	*	MON-FRI	*	毎週月曜日から金曜日の午前 0 時 (UTC+0) にワークフローを実行します。
0	2	*	*	?	*	ワークフローを毎日午前 2 時 (UTC+0) に実行します。
15	22	*	*	?	*	ワークフローを毎日午後 10:15 (UTC+0) に実行します。
0/30	22-2	?	*	土 - 日	*	ワークフローは、土曜日から日曜日の開始日の午後 10 時から翌日の午前 2 時 (UTC+0) の間、30 分ごとに実行されます。
45	13	L	*	?	2023-2027	2023 年から 2027 年までの月の最終日の午後 1 時 45 分 (UTC+0) にワークフローを実行します。

で cron 式を指定するときは CodeCatalyst、次のガイドラインに従ってください。

SCHEDULE トリガーごとに 1 つの cron 式を指定します。
YAML エディタで cron 式を二重引用符 (") で囲みます。
協定世界時 (UTC) で時刻を指定します。その他のタイムゾーンはサポートされていません。
実行の合間に 30 分以上を設定します。より高速なケイデンスはサポートされていません。
days-of-month または days-of-weekフィールドを指定しますが、両方を指定することはできません。いずれかのフィールドに値またはアスタリスク (*) を指定する場合は、もう一方のフィールドで疑問符 (?) を使用する必要があります。アスタリスクは「all」、疑問符は「any」を意味します。

cron 式のその他の例と、?、、 *などのワイルドカードに関する情報についてはL、Amazon EventBridge ユーザーガイドの「Cron 式のリファレンス」を参照してください。 EventBridge との Cron 式はまったく同じように CodeCatalyst 動作します。

スケジュールトリガーの例については、「」を参照してくださいトリガーの例。

対応する UI: ビジュアルエディタ/ワークフロー図/トリガー/スケジュール

アクション

このワークフローの一連の 1 つ以上のアクション。は、ビルドアクションやテストアクションなど、さまざまなタイプの機能を提供する複数のアクションタイプ CodeCatalyst をサポートしています。各アクションタイプには次のものがあります。

アクションの一意のハードコードされた ID を示す Identifierプロパティ。例えば、はビルドアクションaws/build@v1を識別します。
アクションに固有のプロパティを含むConfigurationセクション。

各アクションタイプの詳細については、「」を参照してくださいアクションタイプ。アクションタイプトピックには、各アクションのドキュメントへのリンクがあります。

以下は、ワークフロー定義ファイル内のアクションとアクショングループの YAML リファレンスです。


Name: MyWorkflow
SchemaVersion: 1.0
...
Actions:
  action-or-gate-name:
    Identifier: identifier
    Configuration:
    ...
  #Action groups
  action-group-name:
    Actions:
      ...

action-or-gate-name

(Actions/action-or-gate-name)

(必須)

action-name を、アクションに付ける名前に置き換えます。アクション名はワークフロー内で一意である必要があり、英数字、ハイフン、アンダースコアのみを含める必要があります。構文ルールの詳細については、「」を参照してくださいYAML 構文ガイドライン。

制限を含むアクションの命名方法の詳細については、「」を参照してくださいaction-or-gate-name。

対応する UI: ビジュアルエディタ/アクション名/設定タブ/アクション名またはアクション表示名

action-group-name

(Actions/action-group-name)

(オプション)

アクショングループには、1 つ以上のアクションが含まれます。アクションをアクショングループにグループ化すると、ワークフローを整理しやすくなり、異なるグループ間の依存関係を設定することもできます。

をアクショングループに付ける名前action-group-nameに置き換えます。アクショングループ名はワークフロー内で一意である必要があり、英数字、ハイフン、アンダースコアのみを含める必要があります。構文ルールの詳細については、「」を参照してくださいYAML 構文ガイドライン。

アクショングループの詳細については、「」を参照してくださいアクションをアクショングループにグループ化する。

対応する UI: なし

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

ワークフローの状態

問題のある作業を追跡して整理する