Create Pull Request

A GitHub action to create a pull request for changes to your repository in the actions workspace.

Changes to a repository in the Actions workspace persist between steps in a workflow. This action is designed to be used in conjunction with other steps that modify or add files to your repository. The changes will be automatically committed to a new branch and a pull request created.

Create Pull Request action will:

1. Check for repository changes in the Actions workspace. This includes:
   • untracked (new) files
   • tracked (modified) files
   • commits made during the workflow that have not been pushed
2. Commit all changes to a new branch, or update an existing pull request branch.
3. Create a pull request to merge the new branch into the base—the branch checked out in the workflow.

Documentation

• Concepts, guidelines and advanced usage
• Examples
• Updating to v5

Usage

      - uses: actions/checkout@v3

      # Make changes to pull request here

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v5

You can also pin to a specific release version in the format @v5.x.x

Workflow permissions

For this action to work you must explicitly allow GitHub Actions to create pull requests. This setting can be found in a repository's settings under Actions > General > Workflow permissions.

For repositories belonging to an organization, this setting can be managed by admins in organization settings under Actions > General > Workflow permissions.

Action inputs

All inputs are optional. If not set, sensible defaults will be used.

Note: If you want pull requests created by this action to trigger an on: push or on: pull_request workflow then you cannot use the default GITHUB_TOKEN. See the documentation here for workarounds.

For self-hosted runners behind a corporate proxy set the https_proxy environment variable.

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v5
        env:
          https_proxy: http://<proxy_address>:<port>

Action outputs

The following outputs can be used by subsequent workflow steps.

• pull-request-number - The pull request number.
• pull-request-url - The URL of the pull request.
• pull-request-operation - The pull request operation performed by the action, created, updated or closed.
• pull-request-head-sha - The commit SHA of the pull request branch.

Step outputs can be accessed as in the following example. Note that in order to read the step outputs the action step must have an id.

      - name: Create Pull Request
        id: cpr
        uses: peter-evans/create-pull-request@v5
      - name: Check outputs
        if: ${{ steps.cpr.outputs.pull-request-number }}
        run: |
          echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"
          echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}"

Action behaviour

The default behaviour of the action is to create a pull request that will be continually updated with new changes until it is merged or closed. Changes are committed and pushed to a fixed-name branch, the name of which can be configured with the branch input. Any subsequent changes will be committed to the same branch and reflected in the open pull request.

How the action behaves:

• If there are changes (i.e. a diff exists with the checked-out base branch), the changes will be pushed to a new branch and a pull request created.
• If there are no changes (i.e. no diff exists with the checked-out base branch), no pull request will be created and the action exits silently.
• If a pull request already exists it will be updated if necessary. Local changes in the Actions workspace, or changes on the base branch, can cause an update. If no update is required the action exits silently.
• If a pull request exists and new changes on the base branch make the pull request unnecessary (i.e. there is no longer a diff between the pull request branch and the base), the pull request is automatically closed. Additionally, if delete-branch is set to true the branch will be deleted.

For further details about how the action works and usage guidelines, see Concepts, guidelines and advanced usage.

Alternative strategy - Always create a new pull request branch

For some use cases it may be desirable to always create a new unique branch each time there are changes to be committed. This strategy is not recommended because if not used carefully it could result in multiple pull requests being created unnecessarily. If in doubt, use the default strategy of creating an updating a fixed-name branch.

To use this strategy, set input branch-suffix with one of the following options.

• random - Commits will be made to a branch suffixed with a random alpha-numeric string. e.g. create-pull-request/patch-6qj97jr, create-pull-request/patch-5jrjhvd

• timestamp - Commits will be made to a branch suffixed by a timestamp. e.g. create-pull-request/patch-1569322532, create-pull-request/patch-1569322552

• short-commit-hash - Commits will be made to a branch suffixed with the short SHA1 commit hash. e.g. create-pull-request/patch-fcdfb59, create-pull-request/patch-394710b

Controlling committed files

The action defaults to adding all new and modified files. If there are files that should not be included in the pull request, you can use the following methods to control the committed content.

Remove files

The most straightforward way to handle unwanted files is simply to remove them in a step before the action runs.

      - run: |
          rm -rf temp-dir
          rm temp-file.txt

Ignore files

If there are files or directories you want to ignore you can simply add them to a .gitignore file at the root of your repository. The action will respect this file.

Add specific paths

You can control which files are committed with the add-paths input. Paths should follow git's pathspec syntax. File changes that do not match one of the paths will be stashed and restored after the action has completed.

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v5
        with:
          add-paths: |
            *.java
            docs/*.md

Create your own commits

As well as relying on the action to handle uncommitted changes, you can additionally make your own commits before the action runs. Note that the repository must be checked out on a branch with a remote, it won't work for events which checkout a commit.

    steps:
      - uses: actions/checkout@v3
      - name: Create commits
        run: |
          git config user.name 'Peter Evans'
          git config user.email '[email protected]'
          date +%s > report.txt
          git commit -am "Modify tracked file during workflow"
          date +%s > new-report.txt
          git add -A
          git commit -m "Add untracked file during workflow"
      - name: Uncommitted change
        run: date +%s > report.txt
      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v5

Create a project card

To create a project card for the pull request, pass the pull-request-number step output to create-or-update-project-card action.

      - name: Create Pull Request
        id: cpr
        uses: peter-evans/create-pull-request@v5

      - name: Create or Update Project Card
        if: ${{ steps.cpr.outputs.pull-request-number }}
        uses: peter-evans/create-or-update-project-card@v2
        with:
          project-name: My project
          column-name: My column
          issue-number: ${{ steps.cpr.outputs.pull-request-number }}

Auto-merge

Auto-merge can be enabled on a pull request allowing it to be automatically merged once requirements have been satisfied. See enable-pull-request-automerge action for usage details.

Reference Example

The following workflow sets many of the action's inputs for reference purposes. Check the defaults to avoid setting inputs unnecessarily.

See examples for more realistic use cases.

jobs:
  createPullRequest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Make changes to pull request
        run: date +%s > report.txt

      - name: Create Pull Request
        id: cpr
        uses: peter-evans/create-pull-request@v5
        with:
          token: ${{ secrets.PAT }}
          commit-message: Update report
          committer: GitHub <[email protected]>
          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
          signoff: false
          branch: example-patches
          delete-branch: true
          title: '[Example] Update report'
          body: |
            Update report
            - Updated with *today's* date
            - Auto-generated by [create-pull-request][1]

            [1]: https://github.com/peter-evans/create-pull-request
          labels: |
            report
            automated pr
          assignees: peter-evans
          reviewers: peter-evans
          team-reviewers: |
            developers
            qa-team
          milestone: 1
          draft: false

An example based on the above reference configuration creates pull requests that look like this:

License

MIT