Review

cdg task review reviews tasks, and cdg dag review reviews a whole workflow. Each gives a decision to accept, cancel, or defer. For a task, you can also give no decision and have work on it continue. For which action fits which assessment and how to check the result before you review, see Review Tasks and Workflows.

Actions and syntax

The actions of the review commands fall into three groups. accept, cancel, and defer are final actions: they give a decision, and the task or workflow enters reviewed. revise, request-changes, and rework are continuation actions: they apply only to tasks and give no decision, and work on the task continues. clear clears an existing review. For how final actions and continuation actions differ, see Review actions.

cdg task review <action> <task> [-w <workflow>] [options]
cdg dag review <action> [<workflow>...] [options]
cdg task review clear <task> -w <workflow>
cdg dag review clear <workflow>...

All six task-level actions can be written without review, for example cdg task request-changes 2 -w feature. The three workflow-level actions have the same shorthand, for example cdg dag accept feature. The two clear commands have no shorthand.

Review actions act on workflows that have been submitted and are still in the queue. A task-level action handles tasks in one of those workflows. Specify the workflow with -w. When -w is omitted, the command uses the workflow at the head of the queue. A workflow-level action can handle the running workflow at the head of the queue or a later workflow that hasn't started. If you run accept, cancel, or defer on a workflow that hasn't been submitted, the command still succeeds and records the result, but cdg dag submit then refuses to submit that workflow until you clear those review records. See Clear the review and resubmit.

Arguments and options

A review command's arguments come in two parts. The tasks and workflows say what to review, and the options decide how the code is handled, what happens downstream, and whether a target that's still running is stopped first.

For the general syntax for tasks and workflows, see Specify one or more tasks, Task selectors, and Specify a workflow. Selectors in review commands differ from those in control commands in one respect: every selector except --only takes only one task ID, whereas selectors in control commands such as pause and kill can take several. If you write --upto 2 3, the extra 3 is treated as a task ID written directly, and the command reports an error because task IDs and a selector are used together.

--code

--code decides how a review handles the changes a task left. It's available only in isolated-branches mode. In shared-workspace mode, using this option is an error. Here, "changes" means everything modified since the task started, including files in the workspace that aren't committed yet and commits the task agent made itself. When the task branch is rolled back, it returns to the clean baseline it had before the task started, and the results merged in from upstream tasks are kept. For what that means, see When a result isn't good enough.

When a task left no changes, none of these values has anything to handle, and no snapshot branch is created. For what a snapshot branch holds and how to find it and restore the parts you need, see Restore some of the changes from a snapshot. For each action's default and allowed values, see the task-level and workflow-level combination tables.

Workflow-level review accepts --code too, with the values commit, snapshot, and discard, but not none. It first handles each task in the workflow that has run but has no decision yet, as described in the table above, and then handles the integration branch. accept keeps the merged results on the integration branch. cancel and defer return the integration branch to this workflow's base: snapshot first saves the full set of results to a workflow snapshot branch, while commit and discard don't save the full set of results separately. A workflow that hasn't started running has no integration branch, so there's no code to handle.

--downstream

--downstream decides what happens, after a final decision, to the downstream tasks that depend on this task, or to the workflows behind this workflow in the queue. Only cancel and defer give you a choice. accept is fixed at proceed, and any other value is an error. The three continuation actions don't accept this option.

When you omit this option, defer defaults to cascade. cancel has no default: when there's anything downstream, the command asks you to choose in the terminal, and when there's nothing downstream, it uses proceed. In an environment without an interactive terminal, such as a script or an agent's shell tool, the question can't be answered. The command reports an error and exits with code 1 without changing anything, and it tells you to retry with --downstream set explicitly. For how downstream work continues after you release a hold, see Downstream tasks or workflows put on hold.

-m / --message

-m attaches a piece of text, and what it's used for depends on the action. Final actions and revise record it as a review note, and request-changes and rework pass it to the task agent.

Continuation actions may create commits too. For example, request-changes commits the current changes first by default. The message of such a commit is always CodeDAG review <action> task <task-id> and doesn't use the -m text. For how to write a clear change request, see Have it keep working on the existing result: request-changes.

-k / --kill and -p / --pause

When the target of a review is still running, use -k or -p to stop it first and then apply the review action. The two options work with the six task-level actions and the three workflow-level actions, and you give only one of them per command. When the target isn't running, they have no effect. On a workflow-level command, they apply to every running task in the workflow.

• -k, --kill: Kills immediately, with the same effect as cdg task kill or cdg dag kill. Whatever the task agent is doing is interrupted, and the session is kept. The changes it leaves may be only half done, so check them before you accept or commit.
• -p, --pause: Pauses first, with the same effect as cdg task pause or cdg dag pause. The command waits for the task agent to finish what it's doing and stop, and then applies the review. It waits at most 60 seconds. If the agent hasn't stopped by then, the command exits with an error and the review isn't applied. The task is still draining (finishing its current step). Run the review again once it has stopped, and you don't need -p that time.

Without either option, if the target is running (working or draining), accept, defer, and the three continuation actions fail right away without changing anything. cancel asks you in the terminal whether to kill first, pause first, or abandon the review. Without an interactive terminal, it reports an error, exits with code 1, and tells you to specify -k or -p. To cancel without anyone having to choose, specify both how to stop the target and what happens downstream:

# Kill task 3 first, then cancel it; the downstream tasks that depend on it run as usual
cdg task review cancel 3 -w feature -k --downstream proceed
# Kill the whole workflow first, then cancel it; later workflows in the queue start as usual
cdg dag review cancel feature -k --downstream proceed

For how to use a continuation action on a running task, see Use request-changes on a running task.

Action and option combinations

Task level

In isolated-branches mode, each of the six task-level actions has its own default and allowed values for --code and --downstream, and the continuation actions also require the task to have stopped. -m is optional for all six actions. For what it's used for, see -m / --message. For how shared-workspace mode differs, see Shared-workspace mode.

A final action can be used on any task that doesn't have a decision yet, including tasks that are waiting for upstream or on hold, tasks that have been paused or killed, and tasks that have finished running. A task that hasn't started doesn't run once it's canceled or deferred. It has no changes, so --code has no effect on it. When a task is running, add -k or -p.

cancel and defer can end a task directly when it stopped because its startup preparation failed. You don't have to clean anything up or run cdg task recover first. Such a task is stopped at on-hold, or was killed after stopping there and is now killed, for a reason such as a workspace that isn't clean or a fixed branch name that's already taken. It has never run, so the review doesn't check its workspace or touch the uncommitted changes there, and neither the default nor an explicit --code value has any effect on it. If the workspace it holds is also the integration workspace (typically the primary repository of a single-workspace project), you still have to clean up that workspace before you end the whole workflow with cdg dag review. accept and the three continuation actions still fail on a task stopped this way, and the error gives two ways out: deal with the cause and then recover the task, or use cancel or defer instead. For the steps for each reason, see A task or workflow is on hold.

accept works only with commit and proceed, because an accepted result is always committed to the task branch and passed downstream. By default, request-changes commits the current changes to the task branch before it hands the request to the agent, so that you can see what the new round changed on its own.

Continuation actions require the task to have stopped: it must be done, paused, or killed. If you run revise on a paused or killed task, the task returns to done and waits for you to finish your edits and give a decision. request-changes hands the request to the original session. When the agent finishes that round, the task returns to done and, according to its workflow's review settings, waits for your review or is auto-accepted. rework switches to a fresh session that redoes the task from the clean baseline. The task no longer refers to the original session, and from then on cdg task view enters the new one. Continuation actions can't be used directly on an on-hold task. Deal with the cause and recover the task with cdg task recover first, or end it with a final action.

Workflow level

The three workflow-level actions have the same defaults as the task-level actions of the same names. They differ in that --code has no none and --downstream applies to the later workflows in the queue. -m is optional here too.

A workflow-level review doesn't have to wait for the workflow-level gate. You can give a decision on the whole workflow at any time. Tasks that already have a decision keep it. Tasks that have run but have no decision yet get the same decision as the workflow, and their changes are handled one by one according to --code. Tasks that haven't started don't run and get no review result. The workflow then enters reviewed and leaves the queue. If you run cancel or defer on a later workflow that hasn't started, it never runs.

Shared-workspace mode

Shared-workspace mode has no task branches and no integration branch, so a review only decides how the process continues and doesn't handle files. At the task level, you can use accept, cancel, defer, revise, and request-changes. At the workflow level, you can use accept, cancel, and defer. rework isn't available, and no action can take --code: using it is an error. That error depends only on the workflows the command names. When a workflow-level review of a workflow in isolated-branches mode cascades with --downstream cascade to workflows in shared-workspace mode, those workflows end with that action as usual, just without any code handling. The usage and defaults of --downstream, -m, -k, and -p are unchanged.

The files a task writes all stay in the workspace the workflow runs in, which is the primary repository by default. Canceling or deferring doesn't take those files back, and downstream tasks still see them. To keep or undo them, commit or revert them yourself with Git in that workspace. For how to check such changes before a review, see How does review differ in shared-workspace mode?.

Recipes

Cancel a task but let downstream tasks proceed

When you cancel a task with --downstream proceed set explicitly, the downstream tasks skip it and run as usual on top of its upstream results. In the example below, task 2 of the feature workflow depends on task 1, and task 4 depends on task 2:

# Cancel task 2 and save its changes to a snapshot branch; task 4 runs as usual
cdg task review cancel 2 -w feature --downstream proceed
# Cancel task 2 and discard its changes outright; task 4 runs as usual
cdg task review cancel 2 -w feature --downstream proceed --code discard

After either command, task 4 starts with task 1's results and without task 2's changes. You can later restore changes from the snapshot branch that the first command leaves. See Restore some of the changes from a snapshot. You can cancel task 2 the same way before it has started, and it then doesn't run. If it's running, add -k.

Defer a result and keep the code to restore later

defer means you're not using this step's result this time. By default it already uses --code snapshot to save the changes to a snapshot branch. The commands below spell the option out to make the intent clearer:

# Defer task 2 and save its changes to a snapshot branch; the downstream tasks that depend on it are deferred along with it
cdg task review defer 2 -w feature --code snapshot
# Defer only task 2; the downstream tasks that depend on it run as usual
cdg task review defer 2 -w feature --code snapshot --downstream proceed
# Defer the whole workflow and save the full set of results to a workflow snapshot branch; later workflows in the queue start as usual
cdg dag review defer feature --code snapshot --downstream proceed

Both task-level and workflow-level defer cascade by default. For what counts as downstream, see --downstream. For how to restore from a snapshot branch, see Restore some of the changes from a snapshot. To pick up the deferred work later, write it into a new workflow. See Run only a few of the tasks.

Use request-changes on a running task

While a task is still running, you can add -k or -p to stop it first and then use request-changes to hand a new request to its original session. No interactive terminal is needed:

# Kill task 2 immediately, then hand the requested changes to its original session
cdg task review request-changes 2 -w feature -k -m "<requested-changes>"
# Wait for task 2 to finish what it's doing and stop, then hand it the requested changes
cdg task review request-changes 2 -w feature -p -m "<requested-changes>"

When -m is omitted, the built-in request is sent. For how the two ways of stopping differ, see -k and -p. By default, the current changes are committed before the agent starts on the request. For the default and the other allowed values, see the task-level combination table. For when to use this approach and when to enter the session and talk to the agent directly, see Choose how to observe and make changes.

With -k, the command waits briefly to confirm that the request has been delivered to the session, and it exits once delivery is confirmed. If the wait runs out while it's still confirming, the command exits anyway, and delivery continues in the background. If the request can't be delivered in the end, the task stops at on-hold with the reason continuation-dispatch-failed, and running cdg task recover 2 -w feature delivers the same request again.

Until the request is delivered, the task doesn't accept new review commands, and the same is true while CodeDAG is recovering the task. The command tells you that an operation is already in progress. Wait for it to finish, and then review. If the task is stopped at on-hold, run cdg task recover first.

Review several tasks at once

A single review command can handle several tasks in the same workflow, and all of them get the same action and the same options. You can write several task IDs directly, or use a task selector to pick tasks by their dependencies:

# Accept tasks 2 and 3
cdg task accept 2 3 -w feature
# Defer task 4 and every task that depends on it
cdg task defer --downfrom 4 -w feature

Selectors pick tasks by their dependencies alone and don't look at their state, and final actions also apply to tasks that haven't started. So when you use accept with a range selector such as --upto or --downfrom and the selection includes tasks that haven't started, the command lists them first and then asks whether to accept them without running them. The default is not to accept. With -y, they're accepted without asking. Without an interactive terminal and without -y, the command reports an error and exits with code 1. The question doesn't come up when you write task IDs directly or name tasks one by one with --only. For the full selector syntax, see Task selectors.

If some of the selected tasks already have a decision, the command skips them and first asks whether to go ahead with the rest. Without an interactive terminal, it reports an error and exits with code 1. With -y, it handles the rest without asking.

A workflow-level command can also take several workflows at once, for example cdg dag review accept feature docs. They likewise get the same action and the same options, and those whose review is already finished are skipped under the same rule as above, with the same question. With cascade, the decision also goes to every workflow queued behind whichever of the named workflows is nearest the head of the queue.

Clear the review and resubmit

A workflow whose review is finished can be run again only as a whole. First clear its review with cdg dag review clear, which returns it to planning, and then submit it with cdg dag submit. Both commands require you to name the workflow:

cdg dag review clear feature
cdg dag submit feature

cdg dag review clear can take several workflows at once. It clears the review of each workflow and of every task in it. The task branches, integration branch, and snapshot branches all stay in the repository and aren't affected. A workflow that's still in the queue is skipped. When some of the workflows you name are still in the queue, the command first asks whether to go ahead and clear the rest. Without an interactive terminal, it reports an error and exits with code 1. With -y, it goes ahead without asking. To rerun a workflow that hasn't finished yet, first end the current run with cdg dag review accept, cancel, or defer, and then clear the review. For the full steps, see Modify a submitted workflow.

Resubmitting starts a new run, which uses CodeDAG credits again, by task count, when it starts running. For where the new run starts and how its branches are named, see Run the workflow again. If you only want to run a few tasks that were left undone, or redo a few, see Run only a few of the tasks.

Clear the review of individual tasks

cdg task review clear <task> -w <workflow>

cdg task review clear clears the review of the selected tasks only. The tasks return to planning and don't run again. On a workflow whose review is finished, it doesn't make the workflow submittable again either, and the workflow stays at reviewed. The command's output says so and tells you to run cdg dag review clear and then cdg dag submit, that is, to clear the whole workflow as described above. So you can't use it to rerun a single task.

It handles only workflows that aren't in the queue. -w has no default and is required: when it's omitted, the command reports Missing required option '--workflow-file/--dag/-w' and doesn't read or change any workflow. Selected tasks that have no decision yet are skipped. Tasks are specified the same way as in the other review commands, and every selector except --only takes only one task ID.

Task review records in a workflow that hasn't been submitted

After you use accept, cancel, or defer with cdg task review on tasks in a workflow that hasn't been submitted, cdg dag submit refuses to submit the workflow as long as any reviewed task remains in it. The error reads Workflow has review snapshot state. To submit, clear those tasks' review records first. Either clear command works:

• cdg dag review clear <workflow>: Clears the review of every task in the workflow, after which you can submit it right away.
• cdg task review clear <task> -w <workflow>: Clears the review of the selected tasks. If no reviewed task is left in the workflow afterward, the workflow can be submitted. If other reviewed tasks remain, it still can't be submitted, and the command's output lists those tasks and tells you to clear every task's review with cdg dag review clear <workflow>.

Related

• Review Tasks and Workflows: Which of the six actions fits which assessment, and how to check the result before you review.
• Finish, Merge, and Clean Up: After a workflow's review is finished, how to check the integration branch, merge into the main branch, and run the workflow again.
• Auto-accept values: Decide in the workflow file which tasks and workflows stop and wait for your review.