Creating pull requests in GitHub

Pull requests allow you to propose changes to a repository that can be reviewed, discussed, and, upon approval, merged by other team members. This guide will cover the process of creating pull requests in GitHub through various methods, including the GitHub web interface, command line, and the GitHub API.

What is a pull request?

A pull request is a mechanism employed by GitHub (and other version control systems) to request that changes you've made in a branch be merged into another branch in the repository, typically the main branch. PRs serve as a platform for code review, discussion, and integration of new changes.

Creating a pull request via the GitHub web interface

1. Commit to a branch:

   • Ensure your changes are committed to a feature branch in your GitHub repository. It's best practice to isolate changes to specific features or fixes per branch.

2. Navigate to the repository:

   • Go to the GitHub page for the repository where your branch resides.

3. Initiate the pull request:

   • Click on the 'Pull requests' tab and then click 'New pull request'.
   • Select the base branch (the one you want your changes to be merged into) and the compare branch (the branch that contains your changes).

4. Create the pull request:

   • Once you've reviewed the changes and are ready to propose them, click 'Create pull request'.
   • Provide a descriptive title and a detailed description that includes what changes have been made and why.
   • If the repository has templates for pull requests, fill out the required fields. (For further details on pull request templates see this guide on pull request templates in GitHub)

5. Review and merge:

   • After creating the pull request, other developers have the opportunity to review the changes, and leave feedback. Upon approval the pull request can then be merged into the base branch.

Creating a pull request via command line

Creating a pull request directly from the command line isn't supported by Git commands out of the box. However, you can use the GitHub CLI tool (gh) to manage pull requests.

1. Install GitHub CLI:

   • First, install the GitHub CLI from GitHub's official site.

2. Authenticate GitHub CLI:

   • Run gh auth login and follow the prompts to authenticate.

3. Create the pull request:

   • Navigate to your local repository and use the command:
     Terminal

     gh pr create --base main --head your-feature-branch
     
     

   • You will be prompted to enter the title and the body for the pull request. You can also specify reviewers, labels, and other options as needed.

Creating a pull request via GitHub API

For automated systems or custom integration, you might want to create pull requests programmatically using the GitHub API.

1. Obtain authentication token:

   • You need a personal access token with the appropriate scopes (like repo). Create one from your GitHub settings under 'Developer settings'. For further instructions see this guide on creating a GitHub personal access token.

2. Use the GitHub API to create pull request:

   • Send a POST request to the GitHub API to create a pull request. You can send requests to the API using curl:
     Terminal

     curl -X POST \
       -H "Authorization: token YOUR_ACCESS_TOKEN" \
       -H "Accept: application/vnd.github.v3+json" \
       -d '{"title":"Amazing new feature","body":"Please pull this in!","head":"your-feature-branch","base":"main"}' \
       https://api.github.com/repos/your-username/your-repository/pulls
     
     

For further reading see the official GitHub documentation.