検証と投入

cdg dag validate は、ワークフローファイルをローカルでチェックします。cdg dag submit は、ワークフローをプロジェクトのキューに入れます。ワークフローは、順番が来るとバックグラウンドで実行されます。投入時に何がチェックされるか、投入後に進み具合をどう確認するかは、投入、監視、ログを参照してください。

cdg dag validate

cdg dag validate <ワークフロー...>

cdg dag validate は、ワークフローファイルの形式、フィールド、依存関係をローカルでチェックします。ファイルを読み取るだけで、何も変更しません。ログインは不要で、クレジットも消費しません。--help のほかに、オプションはありません。結果の読み方とよくある警告は、「ワークフローファイルを書く」の検証するの節を参照してください。

ワークフローは少なくとも 1 つ書く必要があり、複数書く場合はスペースで区切ります。どれも、名前でもパスでも書けます。書き方はワークフローを指定するを参照してください。

cdg dag validate feature
# 3 つのワークフローを一度に検証する。そのうち 1 つはサブディレクトリにある
cdg dag validate feature docs .codedag/dags/team/release.yaml

コマンドは、プロジェクトの中、つまりプライマリリポジトリか登録済みのいずれかのワークスペースの中で実行する必要があります。検証では、ファイルそのものをチェックするだけでなく、プロジェクトの設定や登録済みのワークスペースとも照らし合わせるからです。たとえば、タスクが使うエージェントがプロジェクトで使えるエージェントのリストにあるか、このコンピューターにインストールされているか、指定したタスクブランチ名が既存のブランチと重複していないか、登録済みのワークスペースのディレクトリがまだ存在するか、といった点です。そのため、同じファイルでも、別のコンピューターで検証したり、時間をおいて検証したりすると、結果が変わることがあります。

複数のワークフローを一度に検証する場合、ファイルはそれぞれ個別にチェックされ、結果も個別に表示されます。1 つのファイルにエラーがあっても、ほかのファイルのチェックには影響しません。エラーのあるファイルが 1 つでもあれば、コマンドは 0 以外の終了コードで終了します。警告だけの場合、終了コードは 0 のままです。スクリプトでは、これをもとに、すべて通ったかどうかを判定できます。

検証に通っても、投入が必ず成功するとは限りません。投入時にはさらに、ワークフローがキューに入っていないこと、アカウントにログインしていること、クレジットが足りていることが確認され、サーバー側でもファイルサイズとタスク数がチェックされます。これらは、どれも cdg dag validate ではチェックされません。投入時にチェックされることを参照してください。

cdg dag submit

cdg dag submit [オプション] <ワークフロー...>

cdg dag submit は、ワークフローをこのプロジェクトのキューに入れます。まずワークフローファイルをもう一度検証し、続いてワークフローをキューに入れられるかどうかを確認して、すべて通った場合にだけ投入します。ワークフローがキューに入ると、コマンドはすぐに戻り、ワークフローはバックグラウンドで実行を待ちます。ワークフローの指定方法は cdg dag validate と同じで、少なくとも 1 つ書く必要があり、省略はできません。一度に複数書く場合は、複数のワークフローを一度に投入するを参照してください。

投入するには、CodeDAG アカウントにログインしている必要があります。まだログインしていない場合は、コマンドが先にログインの手順を案内します。ログインが必要な理由を参照してください。投入時には、クレジットが足りるかどうかを確認するだけで、差し引きはしません。クレジットは、ワークフローがキューの先頭に来て、実行が始まる前に、タスク数に応じて差し引かれます。1 タスクにつき 1 クレジットです。クレジットが差し引かれるタイミングを参照してください。投入が拒否された場合は、トラブルシューティングの投入が拒否されたの節で、該当するメッセージの対処方法に従ってください。

ワークフローを投入できるかどうかは、そのワークフローが現在どのフェーズにあるかで決まります。投入できるのは、計画中（planning）のワークフローだけです。

オプション

-y が影響するのは、警告の確認だけです。対話型ターミナルでは、検証で警告が出ると、コマンドはまず警告を一覧表示し、それでも投入するかどうかを尋ねます。デフォルトでは投入しません。パイプで渡した回答も、同じように有効です。たとえば printf 'y\n' | cdg dag submit feature です。スクリプト、CI、エージェントのシェルツールのような、対話型ターミナルのない環境では、-y を付けなかった場合の結果は stdin によって決まります。

• stdin がすでに閉じている、または /dev/null を指している場合： コマンドは尋ねません。通常の警告だけであれば、そのまま投入します。警告の中に branchName の競合の警告が含まれている場合は、投入を取りやめ、⚠ Submission cancelled. Workflow was not submitted. と出力します。終了コードは 1 です。
• stdin がデータのないパイプの場合： コマンドは質問を表示して、回答を待ちます。パイプが閉じるとエラーになり、回答できる対話型ターミナルがないことと、ワークフローが投入されなかったことを知らせます。終了コードは 1 です。

そのため、こうした環境で投入する場合は、先に cdg dag validate で警告を読み、実行に影響しないことを確認してから、-y を付けて投入してください。そうして初めて、結果を予測できます。

警告の中に、特に注意が必要なものが 1 つあります。タスクの branchName が既存のブランチと同じ名前の場合、検証で branch-name-conflict の警告が出ます。対処せずに投入すると（-y を付けた場合、または質問で続行を選んだ場合）、ワークフローは通常どおりキューに入りますが、実行がこのタスクまで進んだところで、タスクは on-hold（branch-name-conflict）で止まります。警告には、同じ名前のブランチがどこにあるかと、その対処方法が書かれています。ワークスペースにあるローカルブランチは、自分で削除するか名前を変更します。CodeDAG の同期リポジトリが占有している名前は、cdg branch release で解放します。方法の全体は、指定したタスクブランチ名を使うを参照してください。

今回の投入に限ってレビュー設定を調整する

--task-auto-accepted と --dag-auto-accepted は、ワークフローファイルとプロジェクト設定のレビューポリシーを、投入時に上書きします。作用するのは今回の投入だけで、ファイルは一切変更されません。一時的に人の確認を 1 つ増やしたいときに使います。たとえば、新しいワークフローを初めて実行するときに、タスクの結果を 1 つずつ確認したい場合です。止まってレビューを待っているタスクの扱い方は、タスクとワークフローをレビューするを参照してください。

--task-auto-accepted は、各タスクを完了後に自動承認するかどうかを決めます。今回の投入に含まれるすべてのタスクのレビューポリシーを上書きし、タスク自身に書かれた autoAccepted、ワークフローの taskAutoAccepted、プロジェクト設定のいずれも上書きの対象になります。一部のタスクだけに適用することはできません。--dag-auto-accepted は、すべてのタスクのレビューが終了したあと、ワークフロー全体を自動承認するかどうかを決めます。ワークフローの dagAutoAccepted とプロジェクト設定を上書きします。どちらか一方のオプションを省略した場合、対応するレビューポリシーは、元の設定に従って決まります。順序の全体は、デフォルト値と優先順位を参照してください。

2 つのオプションに指定できる値は、ワークフローファイルの同名のフィールドと同じです。none は、止まってレビューを待つことを表します。always と done は、0.1.0 では効果が同じで、どちらも自動承認を表します。それぞれの値をタスクに使う場合とワークフロー全体に使う場合の具体的な意味、および自動承認の例外は、自動承認に指定できる値を参照してください。

# 各タスクが完了するたびに止まり、レビューを待つ
cdg dag submit feature --task-auto-accepted none
# タスクは通常どおり自動承認され、すべて終わったあとで、ワークフロー全体への結論を待つ
cdg dag submit feature --dag-auto-accepted none
# どちらでも止まり、レビューを待つ
cdg dag submit feature --task-auto-accepted none --dag-auto-accepted none

逆に、ワークフローファイルやプロジェクト設定に none と書いてあり、今回は自動承認させたい場合は、対応するオプションを always にします。--task-auto-accepted always も、同じようにすべてのタスクに作用します。ファイルで個別に autoAccepted: none を設定したタスクも、自動承認されます。

複数のワークフローを一度に投入する

1 つのコマンドで、複数のワークフローを投入できます。ワークフローは書いた順にキューに入り、前のワークフローが終了してから、次のワークフローが始まります。

cdg dag submit api-docs release-notes

これらのワークフローは、すべて投入されるか、1 つも投入されないかのどちらかです。そのうち 1 つでも、検証でエラーになる、すでにキューにある、レビューが終了している、のいずれかに当てはまる場合や、これらのワークフローのタスクの総数が残りのクレジットを超える場合、コマンドはどのワークフローも投入しません。警告だけの場合、コマンドはすべてのワークフローの警告をまとめて一覧表示し、尋ねるのは 1 回だけです。-y は、すべてのワークフローに効きます。

--task-auto-accepted と --dag-auto-accepted も、同じように、このコマンドに書いたすべてのワークフローに作用します。ワークフローごとに異なるレビュー設定にしたい場合は、コマンドを分けて投入します。

1 つのコマンドで投入できるワークフローは、最大 100 個です。投入時には、クレジットを確認するために、これらのワークフローファイルの内容がまとめて CodeDAG サービスに送信されます（サービスが受け取るデータは、送信されるデータの範囲を参照）。このリクエストは 1 MiB を超えられないため、各ファイルのサイズの合計も 1 MiB 以内に収める必要があります。どちらかの制限を超えると、全体がまとめて拒否されます。その場合は、いくつかのコマンドに分けて投入してください。1 つのワークフローファイルのサイズとタスク数の制限は、ファイルの置き場所と形式を参照してください。

投入済みのワークフローを変更する

ワークフローを投入すると、CodeDAG はその時点のワークフロー定義を保存し、今回の実行は最初から最後までその定義に従って進みます。そのあとでワークフローファイルやプロジェクト設定を変更しても、実行には影響しません。変更を反映させるには、先に元の実行を終わらせてから、変更後のファイルで再投入する必要があります。

特定のタスクの進め方を調整したいだけであれば、ファイルを変更してやり直す必要はありません。実行中のタスクなら、セッションに入って、タスクエージェントと直接やり取りできます。実行が終わったタスクなら、レビューのときに修正を依頼できます。監視と修正の方法を選ぶを参照してください。再投入が必要になるのは、タスクの分割、依存関係、プロンプト、エージェントといった定義そのものを変更した場合だけです。

再投入は、3 つのステップで行います。まず、元の実行にワークフローレベルのレビューの結論を出して、ワークフローをキューから外します。次に、レビュー記録をクリアして、ワークフローを planning に戻します。最後に、再投入します。ワークフローのレビューがすでに終了している場合は、最初のステップを省きます。次の例では、元の実行を取りやめます。

# 1. 元の実行をキャンセルする。まだ実行中のタスクは先に強制停止し、キューの後ろのワークフローは通常どおり実行される
cdg dag review cancel feature -k --downstream proceed
# 2. レビュー記録をクリアする
cdg dag review clear feature
# 3. 変更後のファイルで再投入する
cdg dag submit feature

最初のステップで、元の結果をどう扱うかが決まります。分離ブランチモードでキャンセルすると、統合ブランチは今回のワークフローのベースに戻ります。元の結果は、デフォルトでは先にスナップショットブランチに保存されるので、あとでそこから取り出せます。必要ないとわかっている場合は、--code discard を付けて、そのまま破棄します。これらのオプションに指定できる値とデフォルト値、ワークフローを承認または見送りにする場合の書き方は、レビューを参照してください。

再投入では、必ずワークフロー全体が実行されます。これは新しい実行で、実行が始まるときに、全タスクの数の分の CodeDAG クレジットが改めて消費されます。新しい実行がどのコミットから始まるか、ブランチにどんな名前が付くかは、もう一度実行するを参照してください。まだ済んでいないタスクを実行したいだけの場合や、一部のタスクだけをやり直したい場合は、それらを新しいワークフローとして書き、別に投入します。一部のタスクだけをあとから実行するを参照してください。

投入後にログを追う

--attach を付けると、投入のあと、現在のターミナルにこのワークフローのログが続けて表示されます。表示は、ワークフローのレビューが終了してキューを離れるまで続きます。

cdg dag submit api-docs --attach

表示される内容は cdg dag logs <ワークフロー> -f と同じで、読み取り専用です。このターミナルに入力した内容が、タスクエージェントに渡ることはありません。タスクエージェントとやり取りする必要がある場合は、別のターミナルを開いて cdg task view を実行します。書き方は cdg task view を参照してください。Ctrl+C を押しても、ログを追うのが終わるだけで、ワークフローはバックグラウンドでそのまま実行を続けます。あとから cdg dag logs <ワークフロー> -f で、もう一度追えます。一方、Ctrl+\ を押すと、ワークフロー全体が強制停止されます。効果は cdg dag kill と同じです。

ログを追っている間に、タスクまたはワークフロー全体のレビューが必要になると、ターミナルのログが止まり、レビューメニューが表示されます。その場で結論を出せます。使い方は投入したターミナルでそのままログを追うを参照してください。

ワークフローそのものが保留になると、ログを追うのはその時点で終わります。ターミナルには Workflow entered on-hold: <ワークフローのパス> と出力され、それに続く Reason: 行に保留の理由が示されて、コマンドは終了コード 1 で終了します。ワークフローがまだキューで待っていて、実行が始まらないうちに保留になった場合も同じです。たとえば、前のワークフローをレビューするときに --downstream hold を使った場合です。理由ごとの対処手順は、タスクまたはワークフローが on-hold で止まっているを参照してください。

複数のワークフローを一度に投入して --attach を付けた場合、ターミナルはキューの順にワークフローのログを追い、1 つが終了すると、続けて次のワークフローを追います。そのうちのいずれかのワークフローが Ctrl+\ で強制停止された場合、on-hold で止まった場合、またはそのレビューメニューで Esc を押してレビューをスキップした場合、ログを追うのはそこで終わります。その後ろに並んだワークフローはキューに残ったままで、このワークフローが復旧されるか、レビューが終了してから開始されます。

関連ページ

• 投入、監視、ログ：投入時に何がチェックされるか、投入後にステータスを確認し、ログを読む方法。
• ワークフローファイルリファレンス：検証のもとになるフィールドのルールと、レビューポリシーに指定できる値と優先順位。
• レビュー：ワークフローやタスクに結論を出すコマンドと、レビュー記録をクリアするコマンドのすべての引数。