Configuration

Outcomes

When an agent finishes, it reports a named outcome. ub-agents checks the result on GitHub, removes the agent's trigger labels and applies the labels you declared.

outcomes:
  approved: {add: [ready-to-merge]}
  changes-requested: {add: [needs-changes]}

Add labels

Labels to add. When the agent hands off a pull request, they go on that pull request.

handed-off: {add: [needs-review]}

Remove labels

Extra labels to take off. The agent's own trigger labels are always removed.

handed-off: {add: [needs-review], remove: [in-progress]}

End of the workflow

An empty mapping changes nothing else.

merged: {}

Ask a person

Add a stop label to park the item for a human decision.

maintainer-merge: {add: [needs-human]}

Reporting

The agent reports with one command. Your instructions say which outcome to use when.

$ ub-agents report --outcome approved --summary "Checks pass"
$ ub-agents report --outcome handed-off --summary "Ready for review" --handoff 219

Stop reports

A report that parks the item needs one --action per decision: who acts, the choices and a recommendation, in one sentence.

$ ub-agents report --outcome needs-human --summary "Storage policy unclear" \
  --action "Owner: choose local or cloud storage; recommend local."

Retry and blocked

--status retry and --status blocked change no labels. Retry runs again after a backoff. Blocked parks the item and also needs --action.

$ ub-agents report --status retry --summary "GitHub returned 502"