# Review Guide

The idea of a review step, and how reviewers are chosen, are the same as in the SaaS edition ([Review Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/guide/review-guide.md), [Human review](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/project/concepts/human-review.md)). This page sets out what differs in the Marketplace edition.

|                          | SaaS edition                                                                    | Marketplace edition                                           |
| ------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Review method            | Stop and wait for a decision / Notify and proceed after the deadline            | Stop and wait for a decision / **External wait**              |
| When the deadline passes | Choose from notify and keep waiting, proceed, send back or reject automatically | **Not decided automatically** (it notifies and keeps waiting) |
| Destination options      | 2 to 5                                                                          | None                                                          |
| What is reviewed         | The output of the preceding step                                                | The case's **settings version and artifact versions**         |

## What a review decides is “whether to proceed”

A review step is where **a person decides whether a case may move on.** **When a case reaches a review step, it stops for the time being.** After that it moves on by the reviewer's decision (or when an external condition is met).

**It does not stop the agent's operations themselves.** Prevent operations you do not want through how the agent is built and through the limits on outbound traffic, not through review ([Execution rules and network access guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/control-guide.md)).

**A review step belongs to workflows.** It cannot be placed in a cycle.

The review request screen shows the “version being reviewed”, the “agent that runs next”, and the artifacts. You can see what will be passed to the next step before you decide ([Case Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/case-guide.md)).

Where in the UI Edit > select the review step in the middle diagram, and “Review settings” appears on the right

## Review or manual work

A review step has **two kinds**, and **what the person does differs between them.**

- **Review (a person judges the Agent's result)** — Look at the case's artifacts and settings, and decide to **proceed, send back, or reject**
- **Manual work (AI does not run; a person does the work, then proceeds)** — No agent runs in this step. **A person finishes the work themselves, then moves on.** Use it to build work you do not hand to an agent into the flow

**With either kind, no agent runs in that step.** Place the work you want an agent to do in a step before or after it.

**To correct what is under review,** the owner makes the case's settings or artifacts a new version while the case awaits review ([Reviews pinned to a version](#reviews-pinned-to-a-version)).

Where in the UI Edit > select the review step > “Review settings” > “Kind of review”

## Only the people named, and their delegates, can decide

**Only the people named as reviewers, and delegates they have handed it to for a period, can decide.** This is separate from roles: **even an owner cannot decide unless named as a reviewer of that step (or a delegate).** The reviewer field also says that an owner can respond only if named as a reviewer.

Candidates are **the project's members.** **Add the people you want to decide as members first.** **Removing someone from the members also removes them as a reviewer.**

**You can name several people.** But **the first answer settles it.** It is not a mechanism that waits for everyone to agree; if you need a joint decision, decide beforehand and have one person answer on behalf of everyone.

**A reviewer can hand decisions to one person in the same organization while away.** Set it in personal settings under “Projects”, “Delegate for review requests”. The delegate is notified too, and a delegate cannot hand it on to someone else.

**Owners, operations staff, and people with the organization operations role can reassign the reviewers of an undecided review request.** Use “Reassign” on the case screen, or “Reassign approvers” in “Action needed”, to replace them with the members you choose ([Case Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/case-guide.md), [Record Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/record-guide.md#acting-on-several-rows)). The step's reviewer setting does not change.

**A case cannot be started if an enabled review step has no reviewer.** “Check settings” checks this before you apply.

Where in the UI Edit > select the review step > “Review settings” > “Basic settings” > “Reviewers”. Add members under Settings > “Members”. The delegate is set in personal settings under “Projects”

## The deadline does not decide

**In a case run by registered agents, a review is not decided automatically even after the deadline passes.** Once the deadline passes, the reviewers (and the escalation contact when overdue, if set) are notified, and it keeps waiting for a decision.

For work you want moved on at the deadline, run it so that the reviewers decide within the deadline.

Review request and overdue emails reach the reviewers, as in the SaaS edition. They are sent with the sending method and sender set under “Announcements and Notifications” > “Notification Settings” > the “Mail Provider Settings” tab in the admin console. **If no mail provider is set, no email is sent** ([Settings Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/build/guide/settings-guide.md)).

## Reviews pinned to a version

A review request shows the “**Review content version**”, the “**Next Agent**” and the artifacts. **The reviewer decides on the settings and artifacts of that version.**

If an owner makes a new version of the case settings while it is awaiting review, the review content is replaced with the new version too. An artifact switches to the new version when the version passed to the next step was the one that was edited (otherwise, choose the version to pass again in the case settings) ([Case Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/case-guide.md#fixing-things-while-awaiting-review-then-proceeding)). The reviewer looks at the replaced content and decides again.

**Even when named as a reviewer, someone who is not an owner cannot fix the case settings or artifacts.** If you want them fixed, send it back or ask an owner.

## External wait

An “**External wait**” is a review method that moves on to the next step according to the state of an external service rather than a person. **It can be used only in workflows with registered agents placed.** The one external condition available now is “**GitLab merge request merged**”. When the MR created by the agent on the previous step is merged at the expected version, it moves on to the next step.

### Setting it up

Choose “Wait for an external condition” as the review method of the review step, and fill in three fields.

| Field                                 | What to enter                                                                                                                                  |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **External condition**                | “GitLab merge request merged”                                                                                                                  |
| **Connection used to check it**       | The GitLab connector for reading the MR. Choose it from this project's connectors                                                              |
| **Output that identifies the target** | A JSON output of the registered agent on the previous step. Its contents are `{"gitlab_project_id": …, "mr_iid": …, "expected_head_sha": "…"}` |

`expected_head_sha` is 40 hexadecimal digits (a commit SHA). Producing this output is the agent's job. Place on the previous step an agent whose contract declares a JSON output in this format ([Workflow Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/workflow-guide.md)).

### How it proceeds

- When the target MR is merged at the `expected_head_sha` version, **it moves on to the next step automatically.** The decision is recorded as “Advanced on an external condition”, distinct from a person's approval
- **Reviewers cannot advance it.** All they can do is send it back or reject it (“This review proceeds when the external condition is met; a person cannot approve it (send back or reject is possible)”)
- While it is not yet merged, or when it is merged at a version other than the expected one, the condition is not met and it keeps waiting
- The state is read again every 300 seconds. “Progress” on the case screen shows the target, the last observation, the observed version and the next observation

### When it cannot be checked

When the condition cannot be checked — because the connector or the output that identifies the target is not set, or the output's format cannot be read, for example — **it reverts to a review that waits for the reviewers' decision.** The case screen shows the hold reason.

| Hold reason                                                                                             | What to fix                                                |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| The connector used for the external check has not been added to this project. Add it under "Connectors" | Add a GitLab connector under the connectors in Settings    |
| This external check method is not supported                                                             | Review the external condition settings of the review step  |
| The step does not specify which output identifies the external check target                             | Set “Output that identifies the target” on the review step |
| The Agent in the previous step did not produce the output that identifies the check target              | Check the agent's output                                   |
| The output that identifies the check target could not be read                                           | Check the JSON of the agent's output                       |
| The external condition could not be checked, so this is waiting for the reviewers' decision             | The reviewers check the details and decide                 |

When the connection cannot be authenticated, the target cannot be found or the connector cannot be used, it reads again after 30 minutes. It notifies only the first time. For temporary failures, such as the external service being unreachable or slow to respond, it reads again at intervals that widen from 1 minute up to 60 minutes (without notifying).

### Proceeding sooner with a webhook from GitLab

To move on without waiting for the read every 300 seconds, use a GitLab webhook.

1. An owner enters a value of 16 to 255 characters in “**External-wait webhook secret**” under the connectors in the project's Settings, and saves it. The saved value is not shown

2. Register the following as a webhook on the GitLab project

   <!-- -->

   - URL: `https://<environment domain>/api/connect/<project ID>/<connector ID>`
   - Secret token: the value entered in 1
   - Trigger: Merge request events

3. When the MR is merged, the state is read again as soon as the webhook is received

The project ID is in the URL of the project screen (`/p/projects/<project ID>`). The connector ID is the ID of the OAuth provider of the connector used to check it. Confirm it with an administrator. If any of the URL, the IDs or the secret does not match, the webhook is refused with `404`.

**The webhook's contents alone do not move it on.** The webhook is a trigger to read again; whether to move on is decided by reading the MR through the connector.

**Clear** the secret and webhooks are not accepted until a new secret is saved (the read every 300 seconds carries on). **Replace** it and webhooks with the old secret stop being accepted at once, so update the Secret token on the GitLab side to the same value as well.

## What happens after the decision

- **Proceed** — The case moves to the next step. After the last step, the case completes
- **Send back** — With a reason, work restarts from the step it returns to. The review request that was sent back stays in “Action needed” as “Awaiting rework” until that step starts
- **Reject** — The case is closed as rejected

**To redo a closed case, start a new case.**

A review decision is made on the **version** that was reviewed. If the content was replaced by a new version during the review, a decision made while looking at the old version is not accepted. Look at the replaced content and decide again.

## Easy to get wrong

- **Thinking an owner can decide a review.** Only the people named as reviewers, and their delegates, can decide
- **Thinking the review moves on automatically after the deadline.** It does not. It keeps waiting for the reviewer even after the deadline
- **Thinking you need not look again at what the owner corrected during the review.** The content is replaced, so check it before you decide
- **Thinking a person can advance a review that waits on an external condition.** A person can only send it back or reject it

## What to read next

- [Case Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/case-guide.md) — Correct settings and artifacts while awaiting review
- [Record Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/record-guide.md#clearing-what-needs-a-person) — Clear review requests in “Action needed”
- [Trigger Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/project/guide/trigger-guide.md) — Start and stop cases
