Amazon CodeCatalyst は新規のお客様には提供されなくなりました。既存のお客様は、通常どおりサービスを引き続き使用できます。詳細については、「[CodeCatalyst から移行する方法](migration.md)」を参照してください。
翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# ワークフロー YAML 定義
ワークフロー定義ファイルのリファレンスドキュメントを次に示します。
*ワークフロー定義ファイル*は、ワークフローを記述する YAML ファイルです。デフォルトでは、ファイルは[ソースリポジトリ](source-repositories.md)のルートにある `~/.codecatalyst/workflows/` フォルダに保存されます。ファイルには .yml または .yaml 拡張子を使用でき、拡張子は小文字にする必要があります。
ワークフロー定義ファイルを作成および編集するには、vim などのエディタを使用するか、CodeCatalyst コンソールのビジュアルエディタまたは YAML エディタを使用できます。詳細については、「[CodeCatalyst コンソールのビジュアルエディタと YAML エディタの使用](workflow.md#workflow.editors)」を参照してください。
**注記**
後続の YAML プロパティのほとんどには、対応する UI 要素がビジュアルエディタにあります。UI 要素を検索するには、**Ctrl\$1F** を使用します。要素は、関連付けられた YAML プロパティと共に一覧表示されます。
**Topics**
+ [ワークフロー定義ファイルの例](#workflow.anatomy)
+ [構文ガイドラインと規則](#workflow.terms.syntax.conv)
+ [最上位プロパティ](#workflow.top.level)
## ワークフロー定義ファイルの例
単純なワークフロー定義ファイルの例を次に示します。これには、いくつかの最上位プロパティ、`Triggers` セクション、および `Build` と `Test` の 2 つのアクションを含む `Actions` セクションが含まれます。詳細については、「[ワークフロー定義ファイルについて](workflow.md#workflow.example)」を参照してください。
```
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 仕様](https://yaml.org/spec/)に準拠しているため、その仕様で許可されているものはすべてワークフロー YAML でも許可されます。YAML を初めて使うユーザーのために、有効な YAML コードを提供するための簡単なガイドラインをいくつか紹介します。
+ **大文字と小文字の区別**: ワークフロー定義ファイルでは大文字と小文字が区別されるため、このドキュメントに示す大文字と小文字の区別を使用してください。
+ **特殊文字**: 次のいずれかの特殊文字を含むプロパティ値を引用符または二重引用符で囲むことをお勧めします。`{`、`}`、`[`、`]`、&、`*`、`#`、`?`、`|`、`-`、<、>、`=`、`!`、`%`、`@`、`:`、```、および `,`
引用符を含めない場合、前述の特殊文字が予期しない方法で解釈されることがあります。
+ **プロパティ名**: プロパティ*名* (プロパティ*値*ではない) に使用できるのは、英数字 (a～z、A～Z、0～9)、ハイフン (-)、アンダースコア (\$1) のみです。スペースは使用できません。引用符または二重引用符を使用して、プロパティ名の特殊文字とスペースを有効にすることはできません。
許可されないもの:
`'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 コードでは `---` を使用しないでください。CodeCatalyst は、`---` の後にくるものすべてを無視します。
### 命名規則
このガイドでは、ワークフロー定義ファイルの主な項目を指すために*プロパティ*と*セクション*という用語を使用します。
+ *プロパティ*は、コロン (`:`) を含む任意の項目です。例えば、次のコードスニペットでは、`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)、ハイフン (-)、アンダースコア (\$1) のみです。スペースは使用できません。引用符を使用して、ワークフロー名の特殊文字とスペースを有効にすることはできません。
対応する UI: ビジュアルエディタ/ワークフロープロパティ/**ワークフロー名**
### SchemaVersion
(必須)
ワークフロー定義のスキーマバージョン。現在、有効な値は `1.0` のみです。
対応する UI: *なし*
### RunMode
(オプション)
CodeCatalyst が複数の実行を処理する方法。次のいずれかの値を使用できます。
+ `QUEUED` – 複数の実行がキューに入れられ、順番に実行されます。キューには最大 50 個の実行を入れることができます。
+ `SUPERSEDED` – 複数の実行がキューに入れられ、順番に実行されます。キューには 1 つの実行しか入れられないため、2 つの実行が同じキューに一緒に存在する場合、後の実行が前の実行に取って代わり (引き継ぎ)、前の実行はキャンセルされます。
+ `PARALLEL` – 複数の実行が同時に行われます。
このプロパティが省略されている場合、デフォルトは `QUEUED` です。
詳細については、「[実行のキュー動作の構成](workflows-configure-runs.md)」を参照してください。
対応する UI: ビジュアルエディタ/ワークフロープロパティ/アドバンスト/**実行モード**
### Compute
(オプション)
ワークフローアクションの実行に使用されるコンピューティングエンジンです。コンピューティングはワークフローレベルまたはアクションレベルで指定できますが、両方を指定することはできません。ワークフローレベルで指定すると、コンピューティング設定はワークフローで定義されたすべてのアクションに適用されます。ワークフローレベルでは、同じインスタンスで複数のアクションを実行することもできます。詳細については、「[アクション間でのコンピューティングの共有する](compute-sharing.md)」を参照してください。
コンピューティングの詳細については、「[コンピューティングイメージとランタイムイメージの構成](workflows-working-compute.md)」を参照してください。
対応する 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 エディタ)
アクションの起動速度を最適化しました。
コンピューティングタイプの詳細については、「[コンピューティングタイプ](workflows-working-compute.md#compute.types)」を参照してください。
対応する UI: ビジュアルエディタ/ワークフロープロパティ/アドバンスト/**コンピューティングタイプ**
#### Fleet
(Compute/**Fleet**)
(オプション)
ワークフローまたはワークフローアクションを実行するマシンまたはフリートを指定します。オンデマンドフリートでは、アクションが開始すると、ワークフローは必要なリソースをプロビジョニングし、アクションが完了するとマシンは破棄されます。オンデマンドフリートの例: `Linux.x86-64.Large`、`Linux.x86-64.XLarge`。オンデマンドフリートの詳細については、「[オンデマンドフリートのプロパティ](workflows-working-compute.md#compute.on-demand)」を参照してください。
プロビジョニングされたフリートでは、ワークフローアクションを実行するように専用マシンのセットを設定します。これらのマシンはアイドル状態のままで、アクションをすぐに処理できます。プロビジョニングされたフリートの詳細については、「[プロビジョニングされたフリートのプロパティ](workflows-working-compute.md#compute.provisioned-fleets)」を参照してください。
`Fleet` を省略した場合、デフォルトは `Linux.x86-64.Large` です。
コンピューティングフリートの詳細については、「[コンピューティングフリート](workflows-working-compute.md#compute.fleets)」を参照してください。
対応する UI: ビジュアルエディタ/ワークフロープロパティ/アドバンスト/**コンピューティングフリート**
#### SharedInstance
(Compute/**SharedInstance**)
(オプション)
アクションのコンピューティング共有機能を指定します。コンピューティング共有では、ワークフロー内のアクションは同じインスタンス (ランタイム環境イメージ) で実行されます。次のいずれかの値を使用できます。
+ `TRUE` は、ランタイム環境イメージがワークフローアクション間で共有されることを意味します。
+ `FALSE` は、ワークフロー内のアクションごとに個別のランタイム環境イメージが開始および使用されるため、追加の設定なしではアーティファクトや変数などのリソースを共有できないことを意味します。
コンピューティング共有の詳細については、「[アクション間でのコンピューティングの共有する](compute-sharing.md)」を参照してください。
対応する UI: *なし*
### Triggers
(オプション)
このワークフローの 1 つ以上のトリガーのシーケンス。トリガーが指定されていない場合は、ワークフローを手動で開始する必要があります。
トリガーについての詳細は、「[トリガーを使用したワークフロー実行の自動的な開始](workflows-add-trigger.md)」を参照してください。
対応する 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 つにつきスケジュールトリガーを 1 つだけ使用してください。
+ CodeCatalyst スペース内で複数のワークフローを定義している場合は、同時に開始するようスケジュールするワークフローは 10 個までにすることをお勧めします。
+ トリガーの cron 式を設定する際は、実行間隔に十分な時間を確保してください。詳細については、「[Expression](#workflow.triggers.expression)」を参照してください。
例については「[例: ワークフローのトリガー](workflows-add-trigger-examples.md)」を参照してください。
対応する UI: ビジュアルエディタ/ワークフロー図/トリガー/**トリガータイプ**
#### Events
(Triggers/**Events**)
(トリガー `Type` が `PULLREQUEST` に設定されている場合は必須)
ワークフロー実行を開始するプルリクエストイベントのタイプを指定します。有効な値を次に示します。
+ **プルリクエストが作成されました** (ビジュアルエディタ) または `OPEN` (YAML エディタ）
プルリクエストが作成されるとワークフロー実行が開始されます。
+ **プルリクエストはクローズされました** (ビジュアルエディタ) または `CLOSED` (YAML エディタ）
プルリクエストがクローズされるとワークフロー実行が開始されます。`CLOSED` イベントの動作は理解が難しいため、例を見ることで最もよく理解できます。詳細については「[例: プル、ブランチ、および「CLOSED」イベントを含むトリガー](workflows-add-trigger-examples.md#workflows-add-trigger-examples-push-pull-close)」を参照してください。
+ **プルリクエストに対して新しいリビジョンが作成されます** (ビジュアルエディタ) または `REVISION` (YAML エディタ)
プルリクエストに対してリビジョンが作成されるとワークフロー実行が開始されます。プルリクエストが作成されると最初のリビジョンが作成されます。その後、プルリクエストで指定されたソースブランチに新しいコミットがプッシュされるたびに、新しいリビジョンが作成されます。プルリクエストトリガーに `REVISION` イベントを含める場合、`REVISION` は `OPEN` のスーパーセットであるため、`OPEN` イベントは省略しても構いません。
同じプルリクエストトリガー内で複数のイベントを指定できます。
例については「[例: ワークフローのトリガー](workflows-add-trigger-examples.md)」を参照してください。
対応する UI: ビジュアルエディタ/ワークフロー図/トリガー/**プルリクエストのイベント**
#### Branches
(Triggers/**Branches**)
(オプション)
ワークフロー実行を開始するタイミングを把握するために、トリガーがモニタリングするソースリポジトリ内のブランチを指定します。正規表現パターンを使用してブランチ名を定義できます。例えば、`main` で始まるすべてのブランチを照合するには `main.*` を使用します。
指定するブランチはトリガータイプによって異なります。
+ プッシュトリガーでは、プッシュ*先*するブランチ、つまり*送信先*ブランチを指定します。一致するブランチ内のファイルを使用して、一致するブランチごとに 1 つのワークフロー実行が開始されます。
例: `main.*`、`mainline`
+ プルリクエストトリガーでは、プッシュ*先*のブランチ、つまり*送信先*ブランチを指定します。ワークフロー定義ファイルと**ソース**ブランチ内のソースファイル (一致するブランチ*ではない*) を使用して、一致するブランチごとに 1 つのワークフロー実行が開始されます。
例: `main.*`、`mainline`、`v1\-.*` (`v1-` で始まるブランチと一致)
+ スケジュールトリガーでは、スケジュールされた実行で使用するファイルを含むブランチを指定します。ワークフロー定義ファイルと一致するブランチ内のソースファイルを使用して、一致するブランチごとに 1 つのワークフロー実行が開始されます。
例: `main.*`、`version\-1\.0`
**注記**
ブランチを指定*しない*場合、トリガーはソースリポジトリ内のすべてのブランチをモニタリングし、次の場所にあるワークフロー定義ファイルとソースファイルを使用してワークフロー実行を開始します。
プッシュ*先*のブランチ (プッシュトリガーの場合)。詳細については、「[例: シンプルなコードプッシュトリガー](workflows-add-trigger-examples.md#workflows-add-trigger-examples-push-simple)」を参照してください。
プル*元*のブランチ (プルリクエストトリガーの場合)。詳細については、「[例: シンプルなプルリクエストトリガー](workflows-add-trigger-examples.md#workflows-add-trigger-examples-pull-simple)」を参照してください。
すべてのブランチ (スケジュールトリガーの場合)。ソースリポジトリ内のブランチごとに 1 つのワークフロー実行が開始されます。詳細については、「[例: シンプルなスケジュールトリガー](workflows-add-trigger-examples.md#workflows-add-trigger-examples-schedule-simple)」を参照してください。
ブランチとトリガーの詳細については、「[トリガーとブランチの使用ガイドライン](workflows-add-trigger-considerations.md)」を参照してください。
その他の例については、「[例: ワークフローのトリガー](workflows-add-trigger-examples.md)」を参照してください。
対応する UI: ビジュアルエディタ/ワークフロー図/トリガー/**ブランチ**
#### FilesChanged
(Triggers/**FilesChanged**)
(トリガー `Type` が `PUSH` または `PULLREQUEST` に設定されている場合はオプションです。トリガー `Type` が `SCHEDULE` に設定されている場合はサポートされません)
ワークフロー実行を開始するタイミングを把握するために、トリガーがモニタリングするソースリポジトリ内のファイルかフォルダを指定します。正規表現を使用して、ファイルの名前またはパスを照合できます。
例については「[例: ワークフローのトリガー](workflows-add-trigger-examples.md)」を参照してください。
対応する UI: ビジュアルエディタ/ワークフロー図/トリガー/**ファイルの変更**
#### Expression
(Triggers/**Expression**)
(トリガー `Type` が `SCHEDULE` に設定されている場合は必須)
スケジュールされたワークフローの実行を行うタイミングを記述する cron 式を指定します。
CodeCatalyst の cron 式では次の 6 フィールド構文を使用します。各フィールドはスペースで区切られます。
*分* *時間* *日* *月* *曜日* *年*
**cron 式の例**
| 分 | 時間 | 日 | 月 | 曜日 | 年 | 意味 |
| --- | --- | --- | --- | --- | --- | --- |
| 0 | 0 | ? | \$1 | MON-FRI | \$1 | 毎週月曜日から金曜日の午前 0 時 (UTC\$10) にワークフローを実行します。 |
| 0 | 2 | \$1 | \$1 | ? | \$1 | 毎日午前 2 時 (UTC\$10) にワークフローを実行します。 |
| 15 | 22 | \$1 | \$1 | ? | \$1 | 毎日午後 10:15 (UTC\$10) にワークフローを実行します。 |
| 0/30 | 22-2 | ? | \$1 | 土 - 日 | \$1 | 土曜日から日曜日まで開始日の午後 10 時から翌日の午前 2 時 (UTC\$10) の間、30 分間隔でワークフローを実行します。 |
| 45 | 13 | L | \$1 | ? | 2023-2027 | 2023 年から 2027 年まで、月末日の午後 1:45 (UTC\$10) にワークフローを実行します。 |
CodeCatalyst で cron 式を指定する場合は、次のガイドラインに従ってください。
+ `SCHEDULE` トリガー 1 つにつき cron 式を 1 つ指定してください。
+ YAML エディタでは cron 式を二重引用符 (`"`) で囲んでください。
+ 協定世界時 (UTC) で時間を指定します。他のタイムゾーンはサポートされていません。
+ 実行間隔を 30 分以上に設定します。これより短い間隔はサポートされていません。
+ *[日]* フィールドと *[曜日]* フィールドのいずれかを指定します。両方を指定することはできません。一方のフィールドに値または アスタリスク (`*`) を指定する場合、もう一方のフィールドでは 疑問符 (`?`) を使用する必要があります。アスタリスクは「すべて」を意味し、疑問符は「いずれか」を意味します。
cron 式のその他の例、および `?`、`*`、`L` などのワイルドカードの情報については、「*Amazon EventBridge ユーザーガイド*」の「[Cron expressions reference](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-cron-expressions.html)」を参照してください。EventBridge と CodeCatalyst で cron 式はまったく同じように動作します。
スケジュールトリガーの例については、「[例: ワークフローのトリガー](workflows-add-trigger-examples.md)」を参照してください。
対応する UI: ビジュアルエディタ/ワークフロー図/トリガー/**スケジュール**
### アクション
このワークフローの 1 つ以上のアクションのシーケンス。CodeCatalyst は、ビルドアクションやテストアクションなど、さまざまなタイプの機能を提供する複数のアクションタイプをサポートしています。各アクションタイプには、次が含まれています。
+ アクションの一意のハードコードされた ID を示す `Identifier` プロパティ。例えば、`aws/build@v1` はビルドアクションを識別します。
+ アクションに固有のプロパティを含む `Configuration` セクション。
各アクションタイプの詳細については、「[アクションタイプ](workflows-actions.md#workflows-actions-types)」を参照してください。[アクションタイプ](workflows-actions.md#workflows-actions-types) トピックには、各アクションのドキュメントへのリンクがあります。
ワークフロー定義ファイル内のアクションとアクショングループの 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 構文ガイドライン](#workflow.syntax.conv)」を参照してください。
制限など、アクションの命名方法の詳細については、「[action-or-gate-name](#workflow.actions.name)」を参照してください。
対応する UI: ビジュアルエディタ/*action-name*/[設定] タブ/**[アクション名]** または **[アクション表示名]**
#### action-group-name
(Actions/*action-group-name*)
(オプション)
*アクショングループ*には 1 つ以上のアクションが含まれています。アクションをアクショングループにグループ化すると、ワークフローを整理するのに役立ち、異なるグループ間の依存関係を設定できるようになります。
*action-group-name* を、アクショングループに付ける名前に置き換えます。アクショングループ名はワークフロー内で一意のものであり、英数字、ハイフン、アンダースコアのみを使用する必要があります。構文ルールの詳細については、「[YAML 構文ガイドライン](#workflow.syntax.conv)」を参照してください。
アクショングループの詳細については、「[アクショングループへのアクションのグループ化](workflows-group-actions.md)」を参照してください。
対応する UI: *なし*