create-pull-request

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 or update a pull request to merge the branch into the base—the branch checked out in the workflow.

Documentation

• Concepts, guidelines and advanced usage
• Examples
• Updating between versions
• Common issues

Usage

      - uses: actions/checkout@v6

      # Make changes to pull request here

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

You can also pin to a specific release version in the format @v8.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.

Name Description Default token The token that the action will use to create and update the pull request. See token. GITHUB_TOKEN branch-token The token that the action will use to create and update the branch. See branch-token. Defaults to the value of token path Relative path under GITHUB_WORKSPACE to the repository. GITHUB_WORKSPACE add-paths A comma or newline-separated list of file paths to commit. Paths should follow git's pathspec syntax. See Add specific paths. If no paths are specified, all new and modified files are added. commit-message The message to use when committing changes. See commit-message. [create-pull-request] automated change committer The committer name and email address in the format Display Name <[email protected]>. Defaults to the GitHub Actions bot user on github.com. github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> author The author name and email address in the format Display Name <[email protected]>. Defaults to the user who triggered the workflow run. ${{ github.actor }} <${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com> signoff Add Signed-off-by line by the committer at the end of the commit log message. false branch The pull request branch name. create-pull-request/patch delete-branch Delete the branch if it doesn't have an active pull request associated with it. See delete-branch. false branch-suffix The branch suffix type when using the alternative branching strategy. Valid values are random, timestamp and short-commit-hash. See Alternative strategy for details. base Sets the pull request base branch. Defaults to the branch checked out in the workflow. push-to-fork A fork of the checked-out parent repository to which the pull request branch will be pushed. e.g. owner/repo-fork. The pull request will be created to merge the fork's branch into the parent's base. See push pull request branches to a fork for details. sign-commits Sign commits as github-actions[bot] when using GITHUB_TOKEN, or your own bot when using GitHub App tokens. See commit signing for details. false title The title of the pull request. Changes by create-pull-request action body The body of the pull request. Automated changes by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub action body-path The path to a file containing the pull request body. Takes precedence over body. labels A comma or newline-separated list of labels. assignees A comma or newline-separated list of assignees (GitHub usernames). reviewers A comma or newline-separated list of reviewers (GitHub usernames) to request a review from. team-reviewers A comma or newline-separated list of GitHub teams to request a review from. Note that a repo scoped PAT, or equivalent GitHub App permissions, are required. milestone The number of the milestone to associate this pull request with. draft Create a draft pull request. Valid values are true (only on create), always-true (on create and update), and false. false maintainer-can-modify Indicates whether maintainers can modify the pull request. true

token

The token input defaults to the repository's GITHUB_TOKEN.

[!IMPORTANT]

• 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 further details.
• If using the repository's GITHUB_TOKEN and your repository was created after 2nd February 2023, the default permission is read-only. Elevate the permissions in your workflow.

  permissions:
    contents: write
    pull-requests: write
  

Other token options:

• Classic Personal Access Token (PAT) with repo scope.
• Fine-grained Personal Access Token (PAT) with contents: write and pull-requests: write scopes.
• GitHub App tokens with contents: write and pull-requests: write scopes.

[!TIP]
If pull requests could contain changes to Actions workflows you may also need the workflows scope.

branch-token

The action first creates a branch, and then creates a pull request for the branch. For some rare use cases it can be useful, or even necessary, to use different tokens for these operations. It is not advisable to use this input unless you know you need to.

commit-message

In addition to a message, the commit-message input can also be used to populate the commit description. Leave a single blank line between the message and description.

          commit-message: |
            the first line is the commit message

            the commit description starts
            after a blank line and can be
            multiple lines

delete-branch

The delete-branch feature doesn't delete branches immediately on merge. (It can't do that because it would require the merge to somehow trigger the action.) The intention of the feature is that when the action next runs it will delete the branch if there is no diff.

Enabling this feature leads to the following behaviour:

1. If a pull request was merged and the branch is left undeleted, when the action next runs it will delete the branch if there is no further diff.
2. If a pull request is open, but there is now no longer a diff and the PR is unnecessary, the action will delete the branch causing the PR to close.

If you want branches to be deleted immediately on merge then you should use GitHub's Automatically delete head branches feature in your repository settings.

Proxy support

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

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v8
        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, closed or none.
• pull-request-head-sha - The commit SHA of the pull request branch.
• pull-request-branch - The branch name of the pull request.
• pull-request-commits-verified - Whether GitHub considers the signature of the branch's commits to be verified; true or false.

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@v8
      - 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 usa