A beginner’s guide to pull requests in Bitbucket

A beginner’s guide to pull requests in Bitbucket

Are you trying to get up to speed with pull requests in Bitbucket? Then you’ve come to the right place! This beginner’s guide explains what a pull request is, how to create one, and what happens during review and merge—so you can start collaborating with confidence.

A pull request (PR) lets you propose merging changes from one branch into another, give teammates a chance to review the changes, and discuss or resolve issues before the merge happens. It is a review and collaboration step—not the same thing as pushing code, merging code or deploying it.

We’ll use Bitbucket Cloud for the steps and screenshots below. The same basic Git concepts apply to Bitbucket Data Center, although its menus, settings and review controls can differ.

What is a pull request in Bitbucket?

A pull request compares a source branch containing proposed changes with a destination branch that should receive those changes, often main. It brings the diff, commits, discussion, reviewers and relevant checks together in one place.

For example, if you update your project’s README on a branch called feature/update-readme, you can open a PR asking to merge those changes into main. Your teammates can inspect the proposed changes before they become part of main.

Creating a PR doesn’t automatically approve it or merge the branches. The pull request stays open while people review it, make changes and complete any checks your repository requires.

Setting up a Bitbucket repository

Before creating a pull request, you’ll need access to a Bitbucket repository and a branch containing a change. If you’re joining an existing team, you may already have both and can skip the repository-creation step.

If you’re starting a new project, sign in to Bitbucket Cloud, select Create → Repository, choose your workspace and project, enter the repository name and choose its visibility. Atlassian’s repository setup guide covers the full process. You can then clone the repository to your computer to start making changes.

Understanding Git branches before you create a PR

Branches let developers work on a feature, bug fix or documentation change without directly changing the destination branch. Many repositories use a default branch called main, but some use master, develop or another name. The actual destination depends on your team’s workflow.

Here’s the basic relationship:

feature/update-readme (source branch) → pull request → main (destination branch)

You typically make and commit your changes on the source branch, then push that branch to Bitbucket so the changes are available for review.

For example, in a repository you’ve already cloned, create your feature branch first, update its existing README file, then commit and push the change:

git switch -c feature/update-readme
git add README.md
git commit -m "Improve README introduction"
git push -u origin feature/update-readme

The first command creates and switches to the feature branch; make your README edit after that command and before running git add. The example assumes the README file already exists.

You can also create the branch through Bitbucket’s interface—see Atlassian’s create and push a branch guide.

How to create a pull request in Bitbucket Cloud

Once your feature branch has changes pushed to Bitbucket, creating the PR is straightforward:

1. Open your repository in Bitbucket Cloud, select Create, then Pull request. You can also use the repository’s Pull requests area where the option is available.
2. Check the source and destination branches. The source contains your changes; the destination is where you want them merged. For our example, that’s feature/update-readme → main.
3. Review the diff and commits so you know exactly what you’re proposing to change.
4. Write a clear title and description. Explain what changed, why it changed and anything reviewers should test. Add a Jira work-item link where relevant.
5. Add reviewers if your team requires them. They need appropriate repository access; Bitbucket may also populate default reviewers or code owners.
6. Select Create pull request. If the work isn’t ready, you can instead create it as a draft to get the discussion started without allowing it to merge yet.

Atlassian’s current pull-request instructions show the form and its fields in more detail.

What should you put in the PR description?

A good description can be short. For a README update, something like this is enough:

Summary: Clarified the setup instructions for new developers.

Why: The old steps were missing a prerequisite.

Testing: Checked the instructions against a fresh setup.

Related work: Link to the relevant Jira issue, if there is one.

The aim is to help someone review the change without guessing at its purpose.

Reviewing and merging pull requests

After the PR is created, reviewers can inspect the changed files, leave general or line-by-line comments, create tasks for changes that need attention, and approve or request changes. See Atlassian’s code-review guide for the current review controls.

If a reviewer spots a problem, you do not need to create a new pull request. Make the fix on the same source branch, commit it and push again. Bitbucket updates the existing PR with those new commits. Review approvals may need to be renewed depending on your repository’s settings.

Before clicking Merge, check that the appropriate reviewers have approved and that the relevant builds, tasks and merge checks have been completed. Bitbucket Cloud has native merge checks for these workflows; on Premium, supported checks can be enforced to prevent a merge while requirements remain unresolved. Other plans can show warnings without making those checks blocking. See Atlassian’s merge-check documentation.

When you merge a PR, Bitbucket integrates the proposed changes into the destination branch using the selected merge strategy. It doesn’t automatically deploy your application to production: deployment is a separate process, if your team uses one. You may also be offered the option to delete the source branch after merging.

Tips for effective Bitbucket pull requests

Good pull requests are easier to understand and review when you:

• Keep changes focused. A smaller PR generally makes it easier to spot problems and give useful feedback.
• Use descriptive titles. Explain the change, not just “updates” or “fixes”.
• Describe the reason for the change. Include relevant Jira links, testing notes or screenshots when useful.
• Choose relevant reviewers. Ask people who understand the affected code rather than notifying everyone.
• Respond to feedback in the same PR. Keep the discussion and revised commits together.
• Treat a passing build as one signal, not a guarantee. Automated checks support human review; they don’t replace it.

For more advanced ideas, read our Bitbucket code review workflow guide.

Frequently asked questions

What is a pull request in Bitbucket?

A pull request proposes merging code from a source branch into a destination branch. It gives teammates a place to review the changes, discuss them and check requirements before the merge.

How do I create a pull request in Bitbucket?

Push your changes to a feature branch, open the repository in Bitbucket Cloud, select Create → Pull request, choose the source and destination, fill in the title and description, add reviewers as needed and select Create pull request.

Can I update a pull request after creating it?

Yes. Push additional commits to the same source branch and the existing pull request updates. You don’t need to start over when a reviewer requests a change.

Does opening a pull request merge or deploy my code?

No. Creating a pull request starts a review process. The changes reach the destination branch when the PR is merged, and any deployment happens separately according to your team’s setup.

Conclusion

We hope this beginner’s guide helps you create your first pull request in Bitbucket with confidence. The core workflow is simple: create a branch, commit and push changes, open a PR, review the changes, then merge when the requirements are met.

As your team grows, you can improve the process with native reviewer settings, code owners and merge checks. If you need more detailed rules—such as file-specific reviewer groups, approval quotas or conditional reviewer assignment—Workzone can add those controls to your Bitbucket workflow. Read the Workzone reviewer and approval configuration guide to understand the differences.

Ready to make Bitbucket pull requests easier to manage?

Once your team has the basics down, explore Workzone for Bitbucket on the Atlassian Marketplace to see how automated reviewer assignment, approval requirements and merge controls can help when a simple manual PR process is no longer enough.

By Sean Manwarring, Head of Marketing at Izymes
Published 13 February 2023 · Updated 26 October 2026