create-pull-request

The create-pull-request GitHub Action automates the process of creating a pull request for changes made within a GitHub Actions workspace. It is intended to be used after other workflow steps have modified or added files to the repository.

When executed, the action:

1. Detects changes in the workspace, including untracked (new) files, modified tracked files, and unpushed commits made during the workflow.
2. Commits these changes to a new branch (or updates an existing pull request branch).
3. Creates or updates a pull request to merge that branch into the base branch (the branch checked out in the workflow).

In the context of this action, a pull request involves two branches:

• base: The branch you intend to change once the proposed changes are merged (the target branch).
• branch: The branch representing the proposed changes. It contains the base branch plus the new changes.

The action's default behavior is to maintain a single pull request that is updated as new changes are made.

• If changes exist: A new branch is pushed and a pull request is created.
• If no changes exist: The action exits silently.
• If a PR already exists: The action updates the existing pull request if new changes are detected.
• If a PR becomes unnecessary: If the base branch is updated such that there is no longer a diff between the PR branch and the base, the action automatically closes the pull request. If delete-branch is set to true, the branch will also be deleted.

For this action to work, you must explicitly allow GitHub Actions to create pull requests.

Navigate to your repository's settings under Actions > General > Workflow permissions to enable this. For organization-owned repositories, admins can manage this in the organization settings.

You can use SSH deploy keys as an alternative to a Personal Access Token (PAT) to allow the action to push changes. This is useful for triggering on: push workflows.

Limitations:

• Cannot be used alone to create pull requests in a remote repository (a PAT is still required for the PR creation).
• Cannot be used with sign-commits: true.

Setup Steps:

1. Create an SSH key pair (no passphrase).
2. Add the public key as a deploy key in the target repository with "Allow write access" enabled.
3. Add the private key as a repository secret.
4. Configure actions/checkout to use the ssh-key.

    steps:
      - uses: actions/checkout@v6
        with:
          ssh-key: ${{ secrets.SSH_PRIVATE_KEY }}

      # Make changes to pull request here

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

When upgrading to v4, note the following requirements and changes:

Breaking Changes

• add-paths Input: The value -A is no longer supported. To commit all new and modified files, omit the add-paths input entirely.

Requirements

• Runtime: Updated to Node.js 16. Requires Actions runner v2.285.0 or later.
• GHES: If using GitHub Enterprise Server, version GHES 3.4 or later is required.

To use this action, include it in your GitHub Actions workflow after checking out your repository. You can pin to a specific release version using the @v8.x.x format.

      - uses: actions/checkout@v6

      # Make changes to pull request here

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

Some GitHub events (like release or pull_request) check out a specific commit rather than a branch, resulting in a "detached HEAD" state. In these cases, you must provide the base input so the action can correctly rebase your changes.

• For pull_request events: Use ${{ github.head_ref }} to base the new PR on the current pull request's branch.
• For release events: Specify the branch name of the tagged commit (e.g., main).

      # For pull_request events
      - uses: peter-evans/create-pull-request@v8
        with:
          base: ${{ github.head_ref }}

      # For release events
      - uses: peter-evans/create-pull-request@v8
        with:
          base: main

To follow the principle of least privilege, you can push pull request branches to a fork instead of the main repository. This is typically done using a dedicated machine account.

Requirements:

• The machine account needs read access to the parent repository.
• The machine account needs write access to its own fork.
• If the machine account lacks write access to the parent, you cannot use labels, assignees, reviewers, team-reviewers, or milestone.

Configuration: Set the push-to-fork input to the full repository name of the fork (e.g., machine-user/fork-of-repository).

      - uses: actions/checkout@v6

      # Make changes to pull request here

      - uses: peter-evans/create-pull-request@v8
        with:
          token: ${{ secrets.MACHINE_USER_PAT }}
          push-to-fork: machine-user/fork-of-repository