Pull request flow
What the repository's webhook does to an item when a pull request naming it opens, turns into a draft, merges or closes: the moves the project's two switches allow, the statuses they start from, the kinds that finish on a merge, the gates that can refuse a move, and what is announced.
By the end of this page you will know what happens to an item when a pull request that names its key opens, merges or closes, which of those moves your project makes on its own, where they start from and where they stop, and what to do when one did not happen. Linking itself is on the Git linking page; the switches are on the project's settings page.
The two switches
A project decides, under its settings, whether the host's word moves its items:
- An opened pull request moves the item to review. When on, a pull request that opens for review and names an item in Backlog, Ready or In progress moves it to In review.
- A merged pull request moves the item on. When on, a merged pull request that names an item in Ready, In progress or In review moves it on: a story or a bug goes to In QA, where the testers verify it against its criteria; a task, a sub-task, a spike or an improvement goes to Done, because nothing waits to verify it.
Both switches are on when a project is created. Switch either off and the links still land; only the moves stop, and the team moves the items by hand on the board.
What each event does
| The host says | The reference | The item |
|---|---|---|
| A pull request opens for review, or reopens | Linked, Open | To In review, when the first switch is on and it was before |
| A draft pull request opens | Linked, Draft | Nothing |
| A draft is marked ready for review | Open | To In review, as for an opening |
| A pull request is pushed to, edited or relabelled | Its state refreshed | Nothing |
| A pull request merges | Merged, with when | To In QA or Done by kind, when the second switch is on |
| A pull request closes without merging | Closed | Nothing; the work is not done |
| A branch naming the item is deleted | The branch Closed | Nothing |
A move is made once, the first time the host reports the opening or the merge; a redelivery of the same event changes nothing. A pull request naming two items moves both.
What can stop a move
A move the webhook makes obeys the same rules as a move by hand, and when a rule refuses it the item stays where it is, the link still lands, and the refusal is noted for the operators:
- The lifecycle. An item moves only along the paths its status allows; a pull request opened on an item already In QA or Done moves nothing.
- The column limit. A board column at its limit takes no new card, from the webhook as from a hand.
- The Definition of Done. A task moving to Done waits for its required entries when the project asks for the Definition of Done; an unticked list leaves the task In review with its merged pull request, and a person ticks the list and moves it.
Links by hand never move an item
A pull request linked from the item's flyout, over the API or through
link_pull_request carries the state you give it and moves nothing; the moves
follow the host's own word. Linking a merged pull request after the fact, move
the item yourself.
What is announced
- The link itself, as
code.pull_request_linked, the first time the pull request is seen, andcode.pull_request_mergedwhen it merges; see thecode.*events. - The move, as
work_item.transitionedwith the status it came from and went to, exactly as a move by hand is announced; see thework_item.*events. - The item's assignee, reporter and reviewer hear of a pull request opening for review and of one merging, under the Code alert class, through the channels they chose.
- The item's history records the move as the system's, with the reason that it was a transition, so a person can see that the webhook moved it and when.
Related
- Git linking: how the key in a branch, a commit or a pull request links it.
- Board: the columns the moves land in and the limits they keep.
- Definition of Ready and Done: the gate a merge into done waits for.
- Project settings: the two switches.
- GitHub: registering the webhook that sends the events.
How is this guide?
Last updated on
Git linking
Put an item's key in a branch name, a commit message or a pull request and the repository's webhook links the code to the item; read an item's code in its flyout and the project's on the Branches & PRs tab, link by hand what the key missed, and take a wrong link off.
Documents
The documents a project generates from the record its team wrote once: the business requirements document the client signs and the software requirements specification the team builds against, each rendered, reviewed, approved and shared from one page.