Skip to main content

Add a review stage to a playbook

A playbook that builds a change can end with a second pair of eyes. A review stage runs as the Reviewer: it reads what the earlier stages did, writes its review, and can't change code itself. Add one when your team wants every change a playbook makes checked before the work counts as done.

Who can do this: changing a playbook needs the Owner or Admin role in your organization. Built-in playbooks are read-only; duplicate one first, as in Create a playbook.

  1. In the sidebar, select Settings, then Playbooks under Customize.
  2. Under Your playbooks, select the playbook's ⋯, then Edit.
  3. Select the Stages tab, then Add stage below the last stage. The new stage is added at the end and waits for every stage above it, so it starts once the work it reviews is finished.
  4. Select ▸ to open the new card if it is closed. In Label, type a name such as Review, and in Key a short ID such as review.
  5. In Expert, pick Always this expert. Then in Which expert, pick Reviewer.
  6. In Deliverable, pick Review. Its line in the menu reads Read-only; may file follow-ups into the implement stage.
  7. Under May file, leave Follow-ups into the implement stage ticked if the reviewer may file follow-up work for the stage that builds the change. Untick it if the review should only report.
  8. Check the card's Set by the deliverable facts: Mode reads Read-only and Ends when reads Ends when its document is uploaded.
  9. Optional: in Extra instructions, add what your team checks in a review, as in Add instructions to a playbook stage. Select Preview prompt to read the instructions the Reviewer will get.
  10. Select Save. Save stays unavailable while the playbook has an error; each error shows on the field it belongs to.

The Chain on the Playbook tab now ends with the review stage. The next task that runs this playbook gets a review once its earlier stages finish. To review two things side by side, such as a security review and a code review of the same change, see Set what a stage waits for.