Update README
This commit is contained in:
Peter Evans
parent
b11cb71e96
commit
673922cfd2
1 changed files with 33 additions and 35 deletions
68
README.md
68
README.md
|
|
@ -9,9 +9,12 @@ The changes will be automatically committed to a new branch and a pull request c
|
|||
|
||||
Create Pull Request action will:
|
||||
|
||||
1. Check for repository changes in the Actions workspace. This includes untracked (new) files as well as modified files.
|
||||
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 currently active branch executing the workflow.
|
||||
3. Create a pull request to merge the new branch into the base—the branch checked out in the workflow.
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
@ -19,12 +22,12 @@ See [examples](examples.md) for detailed use cases.
|
|||
|
||||
```yml
|
||||
- name: Create Pull Request
|
||||
uses: peter-evans/create-pull-request@v1
|
||||
uses: peter-evans/create-pull-request@v2-beta
|
||||
with:
|
||||
token: ${{ secrets.GITHUB_TOKEN }}
|
||||
```
|
||||
|
||||
You can also pin to a [specific release](https://github.com/peter-evans/create-pull-request/releases) version in the format `@v1.x.x`
|
||||
You can also pin to a [specific release](https://github.com/peter-evans/create-pull-request/releases) version in the format `@v2.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](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) instead of the default `GITHUB_TOKEN`.
|
||||
See [this issue](https://github.com/peter-evans/create-pull-request/issues/48) for further details.
|
||||
|
|
@ -35,13 +38,11 @@ These inputs are *all optional*. If not set, sensible default values will be use
|
|||
|
||||
| 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` |
|
||||
| `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` |
|
||||
| `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. | |
|
||||
|
|
@ -49,9 +50,9 @@ These inputs are *all optional*. If not set, sensible default values will be use
|
|||
| `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` |
|
||||
| `branch` | The branch name. See [Branch naming](#branch-naming) for details. | `create-pull-request/patch` |
|
||||
| `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 [Branch naming](#branch-naming) for details. | |
|
||||
|
||||
**Outputs**
|
||||
|
||||
|
|
@ -61,7 +62,7 @@ Note that in order to read the step output the action step must have an id.
|
|||
```yml
|
||||
- name: Create Pull Request
|
||||
id: cpr
|
||||
uses: peter-evans/create-pull-request@v1
|
||||
uses: peter-evans/create-pull-request@v2-beta
|
||||
with:
|
||||
token: ${{ secrets.GITHUB_TOKEN }}
|
||||
- name: Check outputs
|
||||
|
|
@ -72,40 +73,38 @@ Note that in order to read the step output the action step must have an id.
|
|||
|
||||
### 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.
|
||||
For branch naming there are two strategies. Create a fixed-name pull request branch that will be updated with new changes until it is merged or closed, OR, always create a new unique branch each time there are changes to be committed.
|
||||
|
||||
#### Strategy A - Always create a new pull request branch (default)
|
||||
#### Strategy A - Create and update a pull request branch (default)
|
||||
|
||||
This strategy is the default behaviour of the action. The input `branch` defaults to `create-pull-request/patch`. Changes will be committed 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. If subsequent changes cause the branch to no longer differ from the base the pull request will be automatically closed and the branch deleted.
|
||||
|
||||
#### Strategy B - Always create a new pull request branch
|
||||
|
||||
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`
|
||||
- `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`
|
||||
|
||||
- `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.
|
||||
- `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.
|
||||
|
||||
### Commit as github-actions[bot]
|
||||
### Committer and author
|
||||
|
||||
You can make commits that appear to be made by the GitHub Actions bot as follows.
|
||||
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.
|
||||
|
||||
In most cases, where the committer and author are the same, just the committer can be set.
|
||||
```yml
|
||||
- name: Create Pull Request
|
||||
uses: peter-evans/create-pull-request@v1
|
||||
uses: peter-evans/create-pull-request@v2-beta
|
||||
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
|
||||
committer: Peter Evans <peter-evans@users.noreply.github.com>
|
||||
```
|
||||
|
||||
## Reference Example
|
||||
|
|
@ -121,17 +120,17 @@ jobs:
|
|||
createPullRequest:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v1
|
||||
- uses: actions/checkout@v2
|
||||
- name: Create report file
|
||||
run: date +%s > report.txt
|
||||
- name: Create Pull Request
|
||||
id: cpr
|
||||
uses: peter-evans/create-pull-request@v1
|
||||
uses: peter-evans/create-pull-request@v2-beta
|
||||
with:
|
||||
token: ${{ secrets.GITHUB_TOKEN }}
|
||||
commit-message: Add report file
|
||||
author-email: peter-evans@users.noreply.github.com
|
||||
author-name: Peter Evans
|
||||
committer: Peter Evans <peter-evans@users.noreply.github.com>
|
||||
author: Peter Evans <peter-evans@users.noreply.github.com>
|
||||
title: '[Example] Add report file'
|
||||
body: |
|
||||
New report
|
||||
|
|
@ -146,7 +145,6 @@ jobs:
|
|||
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 }}"
|
||||
|
|
|
|||
Loading…
Reference in a new issue