Review Guide

The idea of a review step, and how reviewers are chosen, are the same as in the SaaS edition (Review Guide, Human review). 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

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 “Mail Provider Settings” in the admin console. If no mail provider is set, no email is sent (Settings Guide).

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 or artifacts while it is awaiting review, the review content is replaced with the new version too (Case Guide). 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 MR 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 MR 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).

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 connection used for the external check is not set up for this project	Add a GitLab connector under the connectors in Settings
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

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.