create-pull-request/README.md

225 lines
12 KiB
Markdown
Raw Normal View History

2020-01-25 08:29:22 +01:00
# <img width="24" height="24" src="docs/assets/logo.svg"> Create Pull Request
2020-05-05 07:24:35 +02:00
[![CI](https://github.com/peter-evans/create-pull-request/workflows/CI/badge.svg)](https://github.com/peter-evans/create-pull-request/actions?query=workflow%3ACI)
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-12-29 07:50:32 +01:00
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
2019-10-06 07:59:45 +02:00
2. Commit all changes to a new branch, or update an existing pull request branch.
2019-12-29 07:50:32 +01:00
3. Create a pull request to merge the new branch into the base&mdash;the branch checked out in the workflow.
2019-07-16 12:58:27 +02:00
2020-01-03 01:51:43 +01:00
## Documentation
2020-02-10 17:15:59 +01:00
- [Concepts, guidelines and advanced usage](docs/concepts-guidelines.md)
2020-01-03 01:51:43 +01:00
- [Examples](docs/examples.md)
- [Updating from v1](docs/updating.md)
2019-07-16 12:58:27 +02:00
2020-01-03 01:51:43 +01:00
## Usage
2019-11-03 09:37:39 +01:00
2019-08-13 11:14:43 +02:00
```yml
2019-09-30 11:58:24 +02:00
- name: Create Pull Request
2020-01-03 06:18:10 +01:00
uses: peter-evans/create-pull-request@v2
2019-09-25 02:42:45 +02:00
```
2019-12-29 07:50:32 +01:00
You can also pin to a [specific release](https://github.com/peter-evans/create-pull-request/releases) version in the format `@v2.x.x`
2019-11-13 15:52:28 +01:00
2019-11-09 10:22:57 +01:00
### Action inputs
2019-07-16 12:58:27 +02:00
2020-04-01 11:50:53 +02:00
All inputs are **optional**. If not set, sensible default values will be used.
2020-01-09 16:11:39 +01:00
2020-04-05 11:17:01 +02:00
**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](https://github.com/peter-evans/create-pull-request/blob/master/docs/concepts-guidelines.md#triggering-further-workflow-runs) for workarounds.
2019-10-06 07:59:45 +02:00
| Name | Description | Default |
| --- | --- | --- |
2020-04-01 11:50:53 +02:00
| `token` | `GITHUB_TOKEN` or a `repo` scoped [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). | `GITHUB_TOKEN` |
| `path` | Relative path under `GITHUB_WORKSPACE` to the repository. | `GITHUB_WORKSPACE` |
2019-12-29 07:50:32 +01:00
| `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](#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](#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` |
2019-11-24 01:28:14 +01:00
| `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. | |
2020-04-13 02:36:34 +02:00
| `team-reviewers` | A comma separated list of GitHub teams to request a review from. A `repo` scoped [PAT](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) may be required. See [this issue](https://github.com/peter-evans/create-pull-request/issues/155). | |
2019-11-24 01:28:14 +01:00
| `milestone` | The number of the milestone to associate this pull request with. | |
2020-05-10 12:02:35 +02:00
| `project` | *Deprecated*. See [Create a project card](#create-a-project-card) for details. | |
| `project-column` | *Deprecated*. See [Create a project card](#create-a-project-card) for details. | |
2020-04-04 02:47:11 +02:00
| `draft` | Create a [draft pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests). | `false` |
2020-05-27 04:43:25 +02:00
| `branch` | The branch name. See [Action behaviour](#action-behaviour) for details. | `create-pull-request/patch` |
2020-03-29 14:27:56 +02:00
| `request-to-parent` | Create the pull request in the parent repository of the checked out fork. See [push pull request branches to a fork](https://github.com/peter-evans/create-pull-request/blob/master/docs/concepts-guidelines.md#push-pull-request-branches-to-a-fork) for details. | `false` |
2019-12-29 07:50:32 +01:00
| `base` | Sets the pull request base branch. | Defaults to the branch checked out in the workflow. |
2020-05-27 04:43:25 +02:00
| `branch-suffix` | The branch suffix type. Valid values are `random`, `timestamp` and `short-commit-hash`. See [Action behaviour](#action-behaviour) for details. | |
2019-11-09 10:22:57 +01:00
2020-05-10 12:02:35 +02:00
### Action outputs
2019-11-09 10:22:57 +01:00
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.
2019-09-24 13:00:49 +02:00
2019-11-09 10:22:57 +01:00
```yml
- name: Create Pull Request
id: cpr
2020-01-03 06:18:10 +01:00
uses: peter-evans/create-pull-request@v2
2019-11-09 10:22:57 +01:00
- name: Check outputs
run: |
echo "Pull Request Number - ${{ env.PULL_REQUEST_NUMBER }}"
2020-05-10 11:06:32 +02:00
echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"
2019-11-09 10:22:57 +01:00
```
2019-07-16 12:58:27 +02:00
2019-12-30 03:10:22 +01:00
### 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.
```yml
- uses: actions/checkout@v1
- run: git checkout "${GITHUB_REF:11}"
```
2020-05-27 04:43:25 +02:00
### Action behaviour
2019-07-16 12:58:27 +02:00
2020-05-27 04:43:25 +02:00
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.
2019-07-16 12:58:27 +02:00
2020-05-27 04:43:25 +02:00
How the action behaves:
2019-07-16 12:58:27 +02:00
2020-05-27 04:43:25 +02:00
- 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.
2019-09-24 13:00:49 +02:00
2020-05-27 04:43:25 +02:00
For further details about how the action works and usage guidelines, see [Concepts, guidelines and advanced usage](docs/concepts-guidelines.md).
2019-09-30 11:58:24 +02:00
2020-05-27 04:43:25 +02:00
#### Alternative strategy - Always create a new pull request branch
2019-09-30 11:58:24 +02:00
2020-05-27 04:43:25 +02:00
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`
2019-09-30 11:58:24 +02:00
2019-12-29 07:50:32 +01: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
2019-12-29 07:50:32 +01:00
- `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`
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-12-29 07:50:32 +01:00
### Committer and author
2019-12-06 10:36:27 +01:00
2019-12-29 07:50:32 +01:00
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.
2019-12-06 10:36:27 +01:00
2020-04-10 10:10:02 +02:00
The following configuration can be used to have commits authored by the user who triggered the workflow event.
2019-12-06 10:36:27 +01:00
```yml
- name: Create Pull Request
2020-01-03 06:18:10 +01:00
uses: peter-evans/create-pull-request@v2
2019-12-06 10:36:27 +01:00
with:
2020-04-10 10:10:02 +02:00
committer: GitHub <noreply@github.com>
author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
2019-12-06 10:36:27 +01:00
```
2019-12-30 04:11:55 +01:00
### Controlling commits
As well as relying on the action to handle uncommitted changes, you can additionally make your own commits before the action runs.
```yml
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
2020-01-03 06:18:10 +01:00
uses: peter-evans/create-pull-request@v2
2019-12-30 04:11:55 +01:00
```
2020-05-10 12:02:35 +02:00
### 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](https://github.com/peter-evans/create-or-update-project-card) action.
```yml
- 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 }}
```
2019-11-03 09:37:39 +01:00
## Reference Example
2019-07-16 12:58:27 +02:00
2019-11-09 10:22:57 +01:00
The following workflow is a reference example that sets all the main inputs.
2019-11-03 09:44:22 +01:00
2020-01-03 01:51:43 +01:00
See [examples](docs/examples.md) for more realistic use cases.
2019-07-16 12:58:27 +02:00
2019-08-13 11:14:43 +02:00
```yml
2019-10-30 08:10:02 +01:00
name: Create Pull Request
on: push
2019-09-26 11:07:43 +02:00
jobs:
createPullRequest:
runs-on: ubuntu-latest
steps:
2019-12-29 07:50:32 +01:00
- uses: actions/checkout@v2
2019-09-30 11:58:24 +02:00
- name: Create report file
run: date +%s > report.txt
- name: Create Pull Request
2019-11-09 10:22:57 +01:00
id: cpr
2020-01-03 06:18:10 +01:00
uses: peter-evans/create-pull-request@v2
2019-11-09 10:22:57 +01:00
with:
token: ${{ secrets.GITHUB_TOKEN }}
commit-message: Add report file
2020-04-10 10:10:02 +02:00
committer: GitHub <noreply@github.com>
author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
2019-11-09 10:22:57 +01:00
title: '[Example] Add report file'
body: |
2019-10-21 11:42:39 +02:00
New report
- Contains *today's* date
- Auto-generated by [create-pull-request][1]
[1]: https://github.com/peter-evans/create-pull-request
2019-11-09 10:22:57 +01:00
labels: report, automated pr
assignees: peter-evans
reviewers: peter-evans
2020-03-03 01:49:52 +01:00
team-reviewers: owners, maintainers
2019-11-09 10:22:57 +01:00
milestone: 1
2020-04-04 02:47:11 +02:00
draft: false
2019-11-09 10:22:57 +01:00
branch: example-patches
2020-03-27 18:56:55 +01:00
request-to-parent: false
2019-11-09 10:22:57 +01:00
- name: Check outputs
run: |
echo "Pull Request Number - ${{ env.PULL_REQUEST_NUMBER }}"
2020-05-10 11:06:32 +02:00
echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"
2019-07-16 12:58:27 +02:00
```
2020-05-11 07:31:26 +02:00
An example based on the above reference configuration creates pull requests that look like this:
2019-07-16 13:43:33 +02:00
2020-01-25 08:29:22 +01:00
![Pull Request Example](docs/assets/pull-request-example.png)
2019-07-16 13:42:29 +02:00
2019-07-16 12:58:27 +02:00
## License
2019-09-30 11:58:24 +02:00
[MIT](LICENSE)