A GitHub action to create a pull request for changes to your repository in the actions workspace
Find a file
2020-07-19 13:58:50 +09:00
.github Keep env var output for backwards compat 2020-07-16 19:42:19 +09:00
__test__ Redesign from request-to-parent to push-to-fork 2020-07-18 15:35:30 +09:00
dist Remove branch-suffix input 2020-07-19 13:58:50 +09:00
docs Update documentation 2020-07-01 09:42:27 +09:00
src Remove branch-suffix input 2020-07-19 13:58:50 +09:00
.eslintignore Convert to typescript 2020-05-17 18:02:41 +09:00
.eslintrc.json Convert to typescript 2020-05-17 18:02:41 +09:00
.gitignore Remove python related code and artifacts 2020-07-16 18:18:58 +09:00
.prettierignore Convert to typescript 2020-05-17 18:02:41 +09:00
.prettierrc.json Convert to typescript 2020-05-17 18:02:41 +09:00
action.yml Remove branch-suffix input 2020-07-19 13:58:50 +09:00
jest.config.js Convert to typescript 2020-05-17 18:02:41 +09:00
LICENSE Initial commit 2019-07-16 19:53:24 +09:00
package-lock.json Remove python related code and artifacts 2020-07-16 18:18:58 +09:00
package.json Remove python related code and artifacts 2020-07-16 18:18:58 +09:00
README.md Keep env var output for backwards compat 2020-07-16 19:42:19 +09:00
tsconfig.json Convert to typescript 2020-05-17 18:02:41 +09:00

Create Pull Request

CI GitHub Marketplace

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

Usage

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

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

Action inputs

All inputs are optional. If not set, sensible default values 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.

Name Description Default
token GITHUB_TOKEN or a repo scoped PAT. GITHUB_TOKEN
path Relative path under GITHUB_WORKSPACE to the repository. GITHUB_WORKSPACE
commit-message The message to use when committing changes. [create-pull-request] automated change
committer The committer name and email address in the format Display Name <email@address.com>. Defaults to the GitHub Actions bot user. See Committer and author for details.
author The author name and email address in the format Display Name <email@address.com>. Defaults to the GitHub Actions bot user. See Committer and author for details.
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
labels A comma separated list of labels.
assignees A comma separated list of assignees (GitHub usernames).
reviewers A comma separated list of reviewers (GitHub usernames) to request a review from.
team-reviewers A comma separated list of GitHub teams to request a review from. A repo scoped PAT may be required. See this issue.
milestone The number of the milestone to associate this pull request with.
project Deprecated. See Create a project card for details.
project-column Deprecated. See Create a project card for details.
draft Create a draft pull request. false
branch The branch name. See Action behaviour for details. create-pull-request/patch
request-to-parent Create the pull request in the parent repository of the checked out fork. See push pull request branches to a fork for details. false
base Sets the pull request base branch. Defaults to the branch checked out in the workflow.
branch-suffix The branch suffix type. Valid values are random, timestamp and short-commit-hash. See Action behaviour for details.

Action outputs

The pull request number is output as a step output. Note that in order to read the step output the action step must have an id.

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

Checkout

This action expects repositories to be checked out with actions/checkout@v2.

If there is some reason you need to use actions/checkout@v1 the following step can be added to checkout the branch.

      - uses: actions/checkout@v1
      - run: git checkout "${GITHUB_REF:11}"

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 and there are no further changes (i.e. no diff with the current pull request branch) then 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 base and pull request branch), the pull request is automatically closed and the branch 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 and mainly kept for backwards compatibility.

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

Ignoring 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.

Committer and author

If neither committer or author inputs are supplied the action will default to making commits that appear to be made by the GitHub Actions bot user.

The following configuration can be used to have commits authored by the user who triggered the workflow event.

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v2
        with:
          committer: GitHub <noreply@github.com>
          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>

Controlling commits

As well as relying on the action to handle uncommitted changes, you can additionally make your own commits before the action runs.

    steps:
      - uses: actions/checkout@v2
      - name: Create commits
        run: |
          git config user.name 'Peter Evans'
          git config user.email 'peter-evans@users.noreply.github.com'
          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@v2

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@v2

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

Reference Example

The following workflow is a reference example that sets all the main inputs.

See examples for more realistic use cases.

name: Create Pull Request
on: push
jobs:
  createPullRequest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

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

      - name: Create Pull Request
        id: cpr
        uses: peter-evans/create-pull-request@v2
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          commit-message: Add report file
          committer: GitHub <noreply@github.com>
          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
          title: '[Example] Add report file'
          body: |
            New report
            - Contains *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: owners, maintainers
          milestone: 1
          draft: false
          branch: example-patches
          request-to-parent: false

      - name: Check output
        run: |
          echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"          

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

Pull Request Example

License

MIT