8.6 KiB

Raw Blame History

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:

Check for repository changes in the Actions workspace. This includes untracked (new) files as well as modified files.
Commit all changes to a new branch, or update an existing pull request branch.
Create a pull request to merge the new branch into the currently active branch executing the workflow.

Usage

See examples for detailed use cases.

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

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

Note: If you want pull requests created by this action to trigger an on: pull_request workflow then you must use a Personal Access Token instead of the default GITHUB_TOKEN. See this issue for further details.

Action inputs

These inputs are all optional. If not set, sensible default values will be used.

Name	Description	Default
`commit-message`	The message to use when committing changes.	`Auto-committed changes by create-pull-request action`
`author-name`	The name of the commit author.	For `push` events, the HEAD commit author. Otherwise, <GITHUB_ACTOR>, the GitHub user that initiated the event.
`author-email`	The email address of the commit author.	For `push` events, the HEAD commit author. Otherwise, <GITHUB_ACTOR>@users.noreply.github.com, where `GITHUB_ACTOR` is the GitHub user that initiated the event.
`committer-name`	The name of the committer.	Defaults to match `author-name`
`committer-email`	The email address of the committer.	Defaults to match `author-email`
`title`	The title of the pull request.	`Auto-generated by create-pull-request action`
`body`	The body of the pull request.	`Auto-generated pull request 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.
`milestone`	The number of the milestone to associate this pull request with.
`project`	The name of the project for which a card should be created. Requires `project-column`.
`project-column`	The name of the project column under which a card should be created. Requires `project`.
`branch`	The branch name. See Branch naming below for details.	`create-pull-request/patch`
`base`	Sets the pull request base branch.	Defaults to the currently checked out branch, `GITHUB_REF`. For `pull_request` events, `GITHUB_HEAD_REF`
`branch-suffix`	The branch suffix type. Valid values are `short-commit-hash`, `timestamp`, `random` and `none`. See Branch naming below for details.	`short-commit-hash`

Outputs

The pull request number is output as both an environment variable and 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@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
      - name: Check outputs
        run: |
          echo "Pull Request Number - ${{ env.PULL_REQUEST_NUMBER }}"
          echo "Pull Request Number - ${{ steps.cpr.outputs.pr_number }}"

Branch naming

For branch naming there are two strategies. Always create a new branch each time there are changes to be committed, OR, create a fixed-name pull request branch that will be updated with any new commits until it is merged or closed.

Strategy A - Always create a new pull request branch (default)

For this strategy there are three options to suffix the branch name. The branch name is defined by the input branch and defaults to create-pull-request/patch. The following options are values for branch-suffix.

short-commit-hash (default) - 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
timestamp - Commits will be made to a branch suffixed by a timestamp. e.g. create-pull-request/patch-1569322532, create-pull-request/patch-1569322552
random - Commits will be made to a branch suffixed with a random alpha-numeric string. This option should be used if multiple pull requests will be created during the execution of a workflow. e.g. create-pull-request/patch-6qj97jr, create-pull-request/patch-5jrjhvd

Strategy B - Create and update a pull request branch

To use this strategy, set branch-suffix to the value none. The input branch defaults to create-pull-request/patch. Commits will be made to this branch and a pull request created. Any subsequent changes will be committed to the same branch and reflected in the open pull request. If the pull request is merged or closed a new one will be created.

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.

Commit as github-actions[bot]

You can make commits that appear to be made by the GitHub Actions bot as follows.

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          author-name: github-actions[bot]
          author-email: 41898282+github-actions[bot]@users.noreply.github.com
          committer-name: GitHub
          committer-email: noreply@github.com

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@v1
      - name: Create report file
        run: date +%s > report.txt
      - name: Create Pull Request
        id: cpr
        uses: peter-evans/create-pull-request@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          commit-message: Add report file
          author-email: peter-evans@users.noreply.github.com
          author-name: Peter Evans
          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
          milestone: 1
          project: Example Project
          project-column: To do
          branch: example-patches
          branch-suffix: short-commit-hash
      - name: Check outputs
        run: |
          echo "Pull Request Number - ${{ env.PULL_REQUEST_NUMBER }}"
          echo "Pull Request Number - ${{ steps.cpr.outputs.pr_number }}"

This reference configuration will create pull requests that look like this:

License

MIT

8.6 KiB Raw Blame History