create-pull-request/README.md

161 lines
8.3 KiB
Markdown
Raw Normal View History

2019-09-30 16:24:16 +02:00
# <img width="24" height="24" src="logo.svg"> Create Pull Request
2019-07-16 12:58:27 +02:00
[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-Create%20Pull%20Request-blue.svg?colorA=24292e&colorB=0366d6&style=flat&longCache=true&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAM6wAADOsB5dZE0gAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAAERSURBVCiRhZG/SsMxFEZPfsVJ61jbxaF0cRQRcRJ9hlYn30IHN/+9iquDCOIsblIrOjqKgy5aKoJQj4O3EEtbPwhJbr6Te28CmdSKeqzeqr0YbfVIrTBKakvtOl5dtTkK+v4HfA9PEyBFCY9AGVgCBLaBp1jPAyfAJ/AAdIEG0dNAiyP7+K1qIfMdonZic6+WJoBJvQlvuwDqcXadUuqPA1NKAlexbRTAIMvMOCjTbMwl1LtI/6KWJ5Q6rT6Ht1MA58AX8Apcqqt5r2qhrgAXQC3CZ6i1+KMd9TRu3MvA3aH/fFPnBodb6oe6HM8+lYHrGdRXW8M9bMZtPXUji69lmf5Cmamq7quNLFZXD9Rq7v0Bpc1o/tp0fisAAAAASUVORK5CYII=)](https://github.com/marketplace/actions/create-pull-request)
2019-07-16 12:53:24 +02:00
A GitHub action to create a pull request for changes to your repository in the actions workspace.
2019-07-16 12:58:27 +02:00
2019-09-25 16:58:47 +02:00
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.
2019-07-16 12:58:27 +02:00
The changes will be automatically committed to a new branch and a pull request created.
Create Pull Request action will:
2019-09-25 16:58:47 +02:00
1. Check for repository changes in the Actions workspace. This includes untracked (new) files as well as modified files.
2019-09-30 11:58:24 +02:00
2. Commit all changes to a new branch, or update an existing pull request branch. The commit will be made using the name and email of the `HEAD` commit author.
2019-07-16 12:58:27 +02:00
3. Create a pull request to merge the new branch into the currently active branch executing the workflow.
## Usage
2019-09-25 02:42:45 +02:00
Linux
2019-08-13 11:14:43 +02:00
```yml
2019-09-30 11:58:24 +02:00
- name: Create Pull Request
2019-10-04 07:46:26 +02:00
uses: peter-evans/create-pull-request@v1.5.0
2019-09-30 11:58:24 +02:00
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
2019-07-16 12:58:27 +02:00
```
2019-09-25 02:42:45 +02:00
Multi platform - Linux, MacOS, Windows (beta)
```yml
2019-09-30 11:58:24 +02:00
- name: Create Pull Request
2019-10-04 07:46:26 +02:00
uses: peter-evans/create-pull-request@v1.5.0-multi
2019-09-30 11:58:24 +02:00
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
2019-09-25 02:42:45 +02:00
```
2019-10-02 15:38:58 +02:00
**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](https://github.com/peter-evans/create-pull-request/issues/48) for further details.
### Environment variables
2019-07-16 12:58:27 +02:00
These variables are all optional. If not set, a default value will be used.
- `COMMIT_MESSAGE` - The message to use when committing changes.
- `PULL_REQUEST_TITLE` - The title of the pull request.
- `PULL_REQUEST_BODY` - The body of the pull request.
2019-09-26 11:07:43 +02:00
- `PULL_REQUEST_LABELS` - A comma separated list of labels.
- `PULL_REQUEST_ASSIGNEES` - A comma separated list of assignees (GitHub usernames).
- `PULL_REQUEST_REVIEWERS` - A comma separated list of reviewers (GitHub usernames) to request a review from.
- `PULL_REQUEST_TEAM_REVIEWERS` - A comma separated list of GitHub teams to request a review from.
- `PULL_REQUEST_MILESTONE` - The number of the milestone to associate this pull request with.
- `PULL_REQUEST_BRANCH` - The branch name. See **Branch naming** below for details.
2019-09-30 11:58:24 +02:00
- `BRANCH_SUFFIX` - The branch suffix type. Valid values are `short-commit-hash` (default), `timestamp`, `random` and `none`. See **Branch naming** below for details.
Output environment variables
- `PULL_REQUEST_NUMBER` - The number of the pull request created.
2019-09-24 13:00:49 +02:00
The following parameters are available for debugging and troubleshooting.
- `DEBUG_EVENT` - If present, outputs the event data that triggered the workflow.
- `SKIP_IGNORE` - If present, the `ignore_event` function will be skipped.
2019-07-16 12:58:27 +02:00
### Branch naming
2019-07-16 12:58:27 +02:00
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.
2019-07-16 12:58:27 +02:00
#### Strategy A - Always create a new pull request branch (default)
2019-07-16 12:58:27 +02:00
2019-09-30 11:58:24 +02:00
For this strategy there are three options to suffix the branch name.
The branch name is defined by the variable `PULL_REQUEST_BRANCH` and defaults to `create-pull-request/patch`. The following options are values for `BRANCH_SUFFIX`.
2019-09-24 13:00:49 +02:00
- `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`
2019-09-30 11:58:24 +02:00
- `timestamp` - Commits will be made to a branch suffixed by a timestamp. e.g. `create-pull-request/patch-1569322532`, `create-pull-request/patch-1569322552`
2019-09-30 11:58:24 +02:00
- `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`
2019-09-30 11:58:24 +02:00
#### Strategy B - Create and update a pull request branch
2019-09-30 11:58:24 +02:00
To use this strategy, set `BRANCH_SUFFIX` to the value `none`. The variable `PULL_REQUEST_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 existing pull request.
2019-09-30 11:58:24 +02:00
### Ignoring files
2019-07-16 12:58:27 +02:00
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.
2019-10-05 02:22:43 +02:00
## Examples
2019-07-16 12:58:27 +02:00
2019-09-24 13:00:49 +02:00
Here is an example that sets all the main environment variables.
2019-07-16 12:58:27 +02:00
2019-08-13 11:14:43 +02:00
```yml
2019-09-26 11:07:43 +02:00
on:
repository_dispatch:
types: [create-pull-request]
name: create-pull-request workflow
jobs:
createPullRequest:
runs-on: ubuntu-latest
steps:
2019-09-30 11:58:24 +02:00
- uses: actions/checkout@v1
- name: Create report file
run: date +%s > report.txt
- name: Create Pull Request
2019-10-04 07:46:26 +02:00
uses: peter-evans/create-pull-request@v1.5.0
2019-09-30 11:58:24 +02:00
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
COMMIT_MESSAGE: Add report file
2019-10-05 02:22:43 +02:00
PULL_REQUEST_TITLE: '[Example] Add report file'
2019-09-30 11:58:24 +02:00
PULL_REQUEST_BODY: >
This PR is auto-generated by
[create-pull-request](https://github.com/peter-evans/create-pull-request).
PULL_REQUEST_LABELS: report, automated pr
PULL_REQUEST_ASSIGNEES: peter-evans
PULL_REQUEST_REVIEWERS: peter-evans
PULL_REQUEST_MILESTONE: 1
PULL_REQUEST_BRANCH: example-patches
BRANCH_SUFFIX: short-commit-hash
- name: Check output environment variable
run: echo "Pull Request Number - $PULL_REQUEST_NUMBER"
2019-07-16 12:58:27 +02:00
```
2019-07-16 13:42:29 +02:00
This configuration will create pull requests that look like this:
2019-07-16 13:43:33 +02:00
2019-10-04 07:53:58 +02:00
![Pull Request Example](https://github.com/peter-evans/create-pull-request/blob/master/pull-request-example.png?raw=true)
2019-07-16 13:42:29 +02:00
2019-10-05 02:22:43 +02:00
### Dynamic configuration using variables
The following examples show how configuration for the action can be dynamically defined in a previous workflow step.
The recommended method is to use `set-output`. Note that the step where output variables are defined must have an id.
```yml
- name: Set output variables
id: vars
run: |
echo ::set-output name=pr_title::"[Test] Add report file $(date +%d-%m-%Y)"
echo ::set-output name=pr_body::"This PR was auto-generated on $(date +%d-%m-%Y) \
by [create-pull-request](https://github.com/peter-evans/create-pull-request)."
- name: Create Pull Request
uses: peter-evans/create-pull-request@v1.5.0
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
PULL_REQUEST_TITLE: ${{ steps.vars.outputs.pr_title }}
PULL_REQUEST_BODY: ${{ steps.vars.outputs.pr_body }}
```
Since the action reads environment variables from the system, it's technically not necessary to explicitly pass them as long as they exist in the environment. So the following method using `set-env` *also* works, but explicitly passing the configuration parameters using the previous method is perferred for its clarity.
```yml
- name: Set environment variables
run: |
echo ::set-env name=PULL_REQUEST_TITLE::"[Test] Add report file $(date +%d-%m-%Y)"
echo ::set-env name=PULL_REQUEST_BODY::"This PR was auto-generated on $(date +%d-%m-%Y) \
by [create-pull-request](https://github.com/peter-evans/create-pull-request)."
- name: Create Pull Request
uses: peter-evans/create-pull-request@v1.5.0
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
2019-07-16 12:58:27 +02:00
## License
2019-09-30 11:58:24 +02:00
[MIT](LICENSE)