Runs and the approval gate

A run is one attempt by an agent at one ticket. It starts when someone assigns the ticket, the agent works on a branch of its own, and the run always stops at the approval gate. Only a person can move it past that point. Nothing an agent does reaches your repository's main line or your live site until someone approves it.

This page walks through a run from start to finish, explains every decision at the gate, and covers what to do when a run does not go to plan. It belongs to the Steer and Ship jobs in How we deliver.

#Starting a run

Press Assign to agent on a ticket. The dialog asks for:

• Agent. Defaults to the project's agent. See AI coding agents.
• Execution mode. How far the run may go (see below).
• Branch. Chosen for you by default, named after the ticket. You can also pick an existing branch or name a new one.
• Instruction (optional). Anything the ticket does not say.
• Run options. Run the test suite, run the formatter, capture screenshots, read the attachments.
• Allow shell commands. Lets the agent run commands such as installing packages, building or running tests. Off by default. Tick it only for repositories you trust.

Then press Queue the run. The project page's Run an agent does the same from a short prompt: you type what you want, and a ticket is filed for it first. Either way the run stops at the same gate.

#Execution modes

Mode	What it does
Analyse only	Reads the repository and reports. Changes nothing.
Prepare implementation plan	Writes the plan and lists the files it would change. Changes nothing.
Implement in branch	Makes the change on the ticket's branch, and stops for review.
Implement, test and capture preview	As above, then runs the tests and captures screenshots.

No mode can merge or deploy. That belongs to the gate.

#While it runs

The run screen shows progress live: the stage the run is in, what the agent is doing right now, and the files it has changed so far. You will see it move from Queued through stages such as Implementing, Testing and Screenshot capturing, to Awaiting approval.

If the agent needs something it was not given, it does not guess. It stops at Awaiting permission and says what it needs in one line, such as permission to install a package. Nothing is lost while it waits. Grant the request from the run screen and the same run carries on from where it stopped. It still ends at the gate.

You can Cancel a run at any point before the gate.

#At the gate

A run at Awaiting approval shows you:

• The changes, file by file, and one set per repository when the project works across several.
• A screenshot of the staging site, if one was captured.
• The agent's report: what it changed and why, what it could not check, and anything it is unsure of.
• The acceptance criteria, so you can check the work against them.
• Everything the agent was given, in case something in the result surprises you.

Read the changes against the criteria, not against the report. The report is the agent's own account and can be wrong.

#The three decisions

Decision	What happens
Approve	The change is saved to the ticket's branch and opened as a pull request. If your project deploys automatically, the deploy follows. Otherwise the run is marked Completed.
Request changes	Your comment is recorded, the attempt is set aside, and the ticket moves to Changes requested. Assign it again with your note as the instruction; the next run also sees what earlier attempts tried.
Reject	The attempt is thrown away, nothing is saved, and the ticket goes back to the board.

Every decision is recorded with a name and a time. A rejected run can still be approved later if its work is recoverable, but the approver has to say why.

#After approval

The pull request description is written by the agent in the voice of the change's author. The run details stay on the run screen, where reviewers in the workspace can read them.

If the pull request or the deploy fails for a reason unrelated to the change, try that step again from the run screen. The original approval stands.

#The review round trip

Teammates and review tools comment on the pull request as they would on any other. When there is feedback to act on, press Address review comments on the run screen. The new comments become the next run's instruction. That run works on the same branch and stops at the same gate. Repeat as often as the review needs.

#Who can approve

Deciding at the gate needs approval rights, which your administrator gives to a group or to the admins of a project. Approval is checked per project. Nobody can approve while signed in as someone else, and Jarvis voice will not approve anything at all.

#When a run does not go to plan

Situation	What you see	What to do
Failed	The reason on the run, and the ticket moved to Blocked.	Fix what it says and press Retry. A retry starts a fresh attempt.
Awaiting permission	The agent's request, in one line.	Grant it and the same run carries on, or continue without it and the agent finishes what it can.
Stuck	The run has gone quiet.	Continue it, send what it already changed to the gate, or close it.
Waiting to start for a long time	It stays at Queued.	Tell your administrator.
The agent cannot sign in	A message saying so, with a link.	Tell your administrator, then press Retry once they have fixed it.

A failed run is never retried behind your back. A person decides.

#After it ships

A finished run offers a client update, written once the change has shipped, and a task log entry for the day the work was done, which feeds the timesheet reports. What each run cost is added up on the usage report.

Next: AI coding agents.