Update documentation
This commit is contained in:
Peter Evans
parent
216b3681c3
commit
809468fcd7
79
README.md
79
README.md
|
|
@ -21,44 +21,41 @@ Create Pull Request action will:
|
|||
|
||||
- [Concepts, guidelines and advanced usage](docs/concepts-guidelines.md)
|
||||
- [Examples](docs/examples.md)
|
||||
- [Updating from v1](docs/updating.md)
|
||||
- [Updating to v3](docs/updating.md)
|
||||
|
||||
## Usage
|
||||
|
||||
```yml
|
||||
- name: Create Pull Request
|
||||
uses: peter-evans/create-pull-request@v2
|
||||
uses: peter-evans/create-pull-request@v3
|
||||
```
|
||||
|
||||
You can also pin to a [specific release](https://github.com/peter-evans/create-pull-request/releases) version in the format `@v2.x.x`
|
||||
You can also pin to a [specific release](https://github.com/peter-evans/create-pull-request/releases) version in the format `@v3.x.x`
|
||||
|
||||
### Action inputs
|
||||
|
||||
All inputs are **optional**. If not set, sensible default values will be used.
|
||||
All inputs are **optional**. If not set, sensible defaults 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](https://github.com/peter-evans/create-pull-request/blob/master/docs/concepts-guidelines.md#triggering-further-workflow-runs) for workarounds.
|
||||
|
||||
| Name | Description | Default |
|
||||
| --- | --- | --- |
|
||||
| `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` |
|
||||
| `token` | `GITHUB_TOKEN` or a `repo` scoped [Personal Access Token (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` |
|
||||
| `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. |
|
||||
| `committer` | The committer name and email address in the format `Display Name <email@address.com>`. | Defaults to the GitHub Actions bot user if an identity is not found in git config. 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 if an identity is not found in git config. See [Committer and author](#committer-and-author) for details. |
|
||||
| `branch` | The pull request branch name. | `create-pull-request/patch` |
|
||||
| `base` | Sets the pull request base branch. | Defaults to the branch checked out in the workflow. |
|
||||
| `push-to-fork` | A fork of the checked out parent repository to which the pull request branch will be pushed. e.g. `owner/repo-fork`. The pull request will be created to merge the fork's branch into the parent's base. 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. | |
|
||||
| `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](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). | |
|
||||
| `labels` | A comma or newline separated list of labels. | |
|
||||
| `assignees` | A comma or newline separated list of assignees (GitHub usernames). | |
|
||||
| `reviewers` | A comma or newline separated list of reviewers (GitHub usernames) to request a review from. | |
|
||||
| `team-reviewers` | A comma or newline separated list of GitHub teams to request a review from. Note that 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). | |
|
||||
| `milestone` | The number of the milestone to associate this pull request with. | |
|
||||
| `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. | |
|
||||
| `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` |
|
||||
| `branch` | The branch name. See [Action behaviour](#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](https://github.com/peter-evans/create-pull-request/blob/master/docs/concepts-guidelines.md#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](#action-behaviour) for details. | |
|
||||
|
||||
### Action outputs
|
||||
|
||||
|
|
@ -87,7 +84,7 @@ If there is some reason you need to use `actions/checkout@v1` the following step
|
|||
|
||||
### 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.
|
||||
The action creates 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.
|
||||
|
||||
|
|
@ -100,26 +97,9 @@ How the action behaves:
|
|||
|
||||
For further details about how the action works and usage guidelines, see [Concepts, guidelines and advanced usage](docs/concepts-guidelines.md).
|
||||
|
||||
#### 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.
|
||||
If neither `committer` or `author` inputs are supplied the action will look for an existing identity in git config. If found, that identity will be used. If not found, the action will default to making commits by the GitHub Actions bot user.
|
||||
|
||||
The following configuration can be used to have commits authored by the user who triggered the workflow event.
|
||||
```yml
|
||||
|
|
@ -152,6 +132,10 @@ As well as relying on the action to handle uncommitted changes, you can addition
|
|||
uses: peter-evans/create-pull-request@v2
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
### 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.
|
||||
|
|
@ -189,27 +173,30 @@ jobs:
|
|||
|
||||
- name: Create Pull Request
|
||||
id: cpr
|
||||
uses: peter-evans/create-pull-request@v2
|
||||
uses: peter-evans/create-pull-request@v3
|
||||
with:
|
||||
token: ${{ secrets.GITHUB_TOKEN }}
|
||||
commit-message: Add report file
|
||||
token: ${{ secrets.PAT }}
|
||||
commit-message: Update report
|
||||
committer: GitHub <noreply@github.com>
|
||||
author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
|
||||
title: '[Example] Add report file'
|
||||
branch: example-patches
|
||||
title: '[Example] Update report'
|
||||
body: |
|
||||
New report
|
||||
- Contains *today's* date
|
||||
Update report
|
||||
- Updated with *today's* date
|
||||
- Auto-generated by [create-pull-request][1]
|
||||
|
||||
[1]: https://github.com/peter-evans/create-pull-request
|
||||
labels: report, automated pr
|
||||
labels: |
|
||||
report
|
||||
automated pr
|
||||
assignees: peter-evans
|
||||
reviewers: peter-evans
|
||||
team-reviewers: owners, maintainers
|
||||
team-reviewers: |
|
||||
owners
|
||||
maintainers
|
||||
milestone: 1
|
||||
draft: false
|
||||
branch: example-patches
|
||||
request-to-parent: false
|
||||
|
||||
- name: Check output
|
||||
run: |
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ inputs:
|
|||
push-to-fork:
|
||||
description: >
|
||||
A fork of the checked out parent repository to which the pull request branch will be pushed.
|
||||
e.g. 'owner/repo-fork'
|
||||
e.g. `owner/repo-fork`.
|
||||
The pull request will be created to merge the fork's branch into the parent's base.
|
||||
title:
|
||||
description: 'The title of the pull request.'
|
||||
|
|
@ -44,7 +44,9 @@ inputs:
|
|||
reviewers:
|
||||
description: 'A comma or newline separated list of reviewers (GitHub usernames) to request a review from.'
|
||||
team-reviewers:
|
||||
description: 'A comma or newline separated list of GitHub teams to request a review from.'
|
||||
description: >
|
||||
A comma or newline separated list of GitHub teams to request a review from.
|
||||
Note that a `repo` scoped Personal Access Token (PAT) may be required.
|
||||
milestone:
|
||||
description: 'The number of the milestone to associate the pull request with.'
|
||||
draft:
|
||||
|
|
|
|||
|
|
@ -138,20 +138,12 @@ There are a number of workarounds with different pros and cons.
|
|||
From a security perspective it's good practice to fork third-party actions, review the code, and use your fork of the action in workflows.
|
||||
By using third-party actions directly the risk exists that it could be modified to do something malicious, such as capturing secrets.
|
||||
|
||||
This action uses [ncc](https://github.com/zeit/ncc) to compile the Node.js code and dependencies into a single file.
|
||||
Python dependencies are vendored and committed to the repository [here](https://github.com/peter-evans/create-pull-request/tree/master/dist/vendor).
|
||||
No dependencies are downloaded during the action execution.
|
||||
|
||||
Vendored Python dependencies can be reviewed by rebuilding the [dist](https://github.com/peter-evans/create-pull-request/tree/master/dist) directory and redownloading dependencies.
|
||||
The following commands require Node and Python 3.
|
||||
|
||||
Alternatively, use the action directly and reference the commit hash for the version you want to target.
|
||||
```
|
||||
npm install
|
||||
npm run clean
|
||||
npm run package
|
||||
- uses: thirdparty/foo-action@172ec762f2ac8e050062398456fccd30444f8f30
|
||||
```
|
||||
|
||||
The `dist` directory should be rebuilt leaving no git diff.
|
||||
This action uses [ncc](https://github.com/zeit/ncc) to compile the Node.js code and dependencies into a single Javascript file under the [dist](https://github.com/peter-evans/create-pull-request/tree/master/dist) directory.
|
||||
|
||||
## Advanced usage
|
||||
|
||||
|
|
@ -208,24 +200,17 @@ It will use their own fork to push code and create the pull request.
|
|||
3. Create a [Personal Access Token (PAT)](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line).
|
||||
4. Logout and log back in to your main user account.
|
||||
5. Add a secret to your repository containing the above PAT.
|
||||
6. As shown in the following example workflow, switch the git remote to the fork's URL after checkout and update the fork to match the checked out branch. Then set the action input `request-to-parent` to `true`.
|
||||
6. As shown in the following example workflow, set the `push-to-fork` input to the full repository name of the fork.
|
||||
|
||||
```yaml
|
||||
- uses: actions/checkout@v2
|
||||
with:
|
||||
persist-credentials: false
|
||||
|
||||
- run: |
|
||||
git remote set-url origin https://${{ secrets.MACHINE_USER_PAT }}:x-oauth-basic@github.com/machine-user/fork-of-repository
|
||||
git fetch --unshallow -p origin
|
||||
git push --force
|
||||
|
||||
# Make changes to pull request here
|
||||
|
||||
- uses: peter-evans/create-pull-request@v2
|
||||
with:
|
||||
token: ${{ secrets.MACHINE_USER_PAT }}
|
||||
request-to-parent: true
|
||||
push-to-fork: machine-user/fork-of-repository
|
||||
```
|
||||
|
||||
### Authenticating with GitHub App generated tokens
|
||||
|
|
@ -272,7 +257,7 @@ GitHub App generated tokens are more secure than using a PAT because GitHub App
|
|||
|
||||
This action can be run inside a container by installing the action's dependencies either in the Docker image itself, or during the workflow.
|
||||
|
||||
The action requires `python3`, `pip3` and `git` to be installed and on the `PATH`.
|
||||
The action requires `git` to be installed and on the `PATH`.
|
||||
|
||||
Note that `actions/checkout` requires Git 2.18 or higher to be installed, otherwise it will just download the source of the repository instead of cloning it.
|
||||
|
||||
|
|
@ -285,9 +270,7 @@ jobs:
|
|||
image: alpine
|
||||
steps:
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
apk --no-cache add git python3
|
||||
python3 -m ensurepip
|
||||
run: apk --no-cache add git
|
||||
|
||||
- uses: actions/checkout@v2
|
||||
|
||||
|
|
@ -310,7 +293,7 @@ jobs:
|
|||
apt-get update
|
||||
apt-get install -y software-properties-common
|
||||
add-apt-repository -y ppa:git-core/ppa
|
||||
apt-get install -y python3 python3-pip git
|
||||
apt-get install -y git
|
||||
|
||||
- uses: actions/checkout@v2
|
||||
|
||||
|
|
|
|||
|
|
@ -1,11 +1,64 @@
|
|||
# Updating from `v1` to `v2`
|
||||
## Updating from `v2` to `v3`
|
||||
|
||||
## Breaking changes
|
||||
### Breaking changes
|
||||
|
||||
- Deprecated inputs `project` and `project-column` have been removed in favour of an additional action step. See [Create a project card](https://github.com/peter-evans/create-pull-request#create-a-project-card) for details.
|
||||
|
||||
- Deprecated output `pr_number` has been removed in favour of `pull-request-number`.
|
||||
|
||||
- Input `request-to-parent` has been removed in favour of `push-to-fork`. This greatly simplifies pushing the pull request branch to a fork of the parent repository. See [Push pull request branches to a fork](concepts-guidelines.md#push-pull-request-branches-to-a-fork) for details.
|
||||
|
||||
e.g.
|
||||
```yaml
|
||||
- uses: actions/checkout@v2
|
||||
|
||||
# Make changes to pull request here
|
||||
|
||||
- uses: peter-evans/create-pull-request@v3
|
||||
with:
|
||||
token: ${{ secrets.MACHINE_USER_PAT }}
|
||||
push-to-fork: machine-user/fork-of-repository
|
||||
```
|
||||
|
||||
- Input `branch-suffix` has been removed to simplify the action and make it easier to understand its behaviour. The same functionality can be achieved by modifying the `branch` name before the action runs. See the following example. If you were using `branch-suffix` and need help to update to `v3`, please create an issue.
|
||||
|
||||
e.g.
|
||||
```yaml
|
||||
- name: Return a 7 character random string
|
||||
uses: actions/github-script@v2
|
||||
id: random-string
|
||||
with:
|
||||
result-encoding: string
|
||||
script: return Math.random().toString(36).substr(2, 7)
|
||||
|
||||
- uses: peter-evans/create-pull-request@v3
|
||||
with:
|
||||
branch: my-branch-${{ steps.random-string.outputs.result }}
|
||||
```
|
||||
|
||||
### New features
|
||||
|
||||
- The action has been converted to Typescript and is much faster than `v2`.
|
||||
|
||||
- If you run this action in a container, `python` and `pip` are no longer required dependencies. See [Running in a container](concepts-guidelines.md#running-in-a-container) for details.
|
||||
|
||||
- Inputs `labels`, `assignees`, `reviewers` and `team-reviewers` can now be newline separated, or comma separated.
|
||||
e.g.
|
||||
```yml
|
||||
labels: |
|
||||
chore
|
||||
dependencies
|
||||
automated
|
||||
```
|
||||
|
||||
## Updating from `v1` to `v2`
|
||||
|
||||
### Breaking changes
|
||||
|
||||
- `v2` now expects repositories to be checked out with `actions/checkout@v2`
|
||||
|
||||
To use `actions/checkout@v1` the following step to checkout the branch is necessary.
|
||||
```
|
||||
```yml
|
||||
- uses: actions/checkout@v1
|
||||
- name: Checkout branch
|
||||
run: git checkout "${GITHUB_REF:11}"
|
||||
|
|
@ -18,7 +71,7 @@
|
|||
|
||||
If neither `author` or `committer` are set the action will default to making commits as the GitHub Actions bot user.
|
||||
|
||||
## New features
|
||||
### New features
|
||||
|
||||
- Unpushed commits made during the workflow before the action runs will now be considered as changes to be raised in the pull request. See [Controlling commits](https://github.com/peter-evans/create-pull-request#controlling-commits) for details.
|
||||
- New commits made to the pull request base will now be taken into account when pull requests are updated.
|
||||
|
|
|
|||
Loading…
Reference in a new issue