[Other doc versions]
[Doc downloads (PDF, HTML, XML)]
Pull requests in Stash provide the team with a quick and easy way to review changes made on a branch, discuss those changes, and make further modifications before the branch is merged to master or your main development branch.
On this page:
When you are ready to start a discussion about your code changes, simply create a pull request.
To create a pull request:
You will receive email notifications when your reviewers and other participants comment on the pull request, or commit changes to it.
After creating a pull request, you can modify it by clicking Edit on the pull request's page. You can edit details such as the Title, Description and the Reviewers. In particular, you can change the Destination branch for the pull request – you'll need Read permission on the branch you want to set.
The most important thing about a pull request is the discussion that it generates. With Stash, you can comment on the pull request as a whole, a particular file, and on specific lines of code in a file. Comment likes are a quick way of amplifying review feedback – effectively saying "also consider this person's feedback". Furthermore, you can attach a task to any comment, so actions identified during the review can be easily tracked and resolved. Read more about pull request tasks below.
To see all the pull requests for a repository, simply click Pull requests in the left-hand navigation panel (when viewing the repository).
The Overview tab captures all of the team's activity on the pull request in one place, right from the initial creation, through to when it is finally merged (or declined), with all the comments, replies and commits that happen along the way.
You can add a comment on the Overview tab (just under 'Activity'), or reply to a previous comment. Use mentions to alert another Stash user to your comment, and use markdown to add formatting, for example headings or lists.
Diffs for Stash pull requests provide the following advantages:
The search looks at the diff and surrounding code lines to provide context. The file tree on the left displays only the files returned by the search.
Use the F keyboard shortcut to quickly access code search when viewing a diff in a pull request. The usual J (next) and K (previous) Stash shortcuts let you move between files in the search results. 'Esc' cancels the search.
The Commits tab lists all the commits that will get merged (those that are greyed out have already been merged). Clicking through to a commit takes you out of the pull request context.
When viewing a commit you can comment on the whole file, or a particular line of code, just as for a diff, for any file in the commit.
Participants can commit new changes to the branch. Stash auto-updates the Commits tab of the pull request, so you can see exactly which commits will be merged. Stash is smart about comments, moving them along when lines are added or removed. If a line with a comment gets removed, you can still view the comment in the activity, but Stash marks the diff as outdated to let you know that this piece of code has been changed in recent commits.
You can attach one or more tasks to any pull request comment, to track required work identified during a review.
Try highlighting some text in the comment, then clicking Create task – the task is automatically created and saved with that text.
When that task is done, simply check the box for the task.
To see all the unresolved tasks for a pull request, use Shift+T when viewing the pull request:
Click the 'link' icon for a task to see the task in the context of the comment and source code.
When Stash is integrated with JIRA you can see the related JIRA issues right in the pull request. You'll see either the JIRA issue key, when there is just one, or the number of related issues:
Click an issue key to see details of the issue, such as the description, status and assignee, without having to leave Stash:
Click the issue key to see the issue in JIRA. This allows reviewers to gain important insight into the task that is being worked on, by seeing the comments and attachments on the issue. This also gives access into JIRA, so you can easily keep issues updated.
See JIRA integration for a description of all the integrations you get when Stash is linked with JIRA.
Once you are ready to merge a pull request, and when the reviewers have approved it, simply click Merge at the top right of the pull request view. You can merge a pull request if you have write (or admin) permission on the project.
Stash does not enforce particular review workflows, so, for example, anyone with write permission on the repository can merge a pull request, including the person who opened it. This flexibilty allows different teams to have different approaches to using Stash. If your team requires stricter control, consider using branch permissions to restrict who can merge a pull request to particular users or groups. You might also want to consider using a plugin to enforce a particular workflow, for example to ensure that only approvals from members of your review team allow merging. See Checks for merging pull requests.
In the 'Merge Pull Request' dialog, you can check Delete branch if you no longer need that branch in the repository. Stash checks on a few things before allowing the deletion – the branch being merged will not be deleted if:
Once accepted, the pull request is marked as merged on the Pull requests tab.
If Stash detects a conflict that prevents the merge, notifications are displayed on the Overview and Diff tabs of the pull request. Click More information to see instructions for how to resolve the conflict in your local repository.
You automatically get added as a watcher of a pull request when you are added to the pull request as a reviewer, or when you perform an action related to the pull request (such as adding a comment):
|Action||You are added as a watcher|
|You are added as a reviewer|
|You comment on a pull request|
|You reply to a comment|
|You push to the source branch|
|You approve the pull request|
You can manually add yourself as a watcher by clicking the Watch button on the pull request screen.
You can always stop watching a pull request by clicking the link in the email notification, or the Unwatch button on the pull request screen. If you stop watching a pull request you will not automatically be added as a watcher again if you subsequently perform an action that would otherwise have added you.
Stash sends email notifications to watchers when certain pull request events occur. By default, email notifications are batched, but you can change your personal account settings (on the Notification settings tab) so that you get notifications immediately. Note that notifications are always sent immediately:
See Notifications for details.