* feat: restore working base branch and uncommitted changes
* docs: uncommitted changes are stashed and restored
* docs: add major version notes
* fix: update package version
* fix: update package-lock
* feat: revise proxy implementation
* docs: add notes for the revised proxy implementation
* feat: set and remove git safe directory
* docs: add notes for the git safe directory feature
* fix: use base url for proxy check
* feat: determine the git dir with rev-parse
* build: update package lock
* fix: remove support for ghes alpha
* feat: revise handling of team reviewers
* docs: update notes
* feat: body-path
* docs: update to v5
* docs: update to v5
* build: fix package lock
* feat: support github server url for pushing to fork (#1315)
Co-authored-by: Kevin Zhu <kevin.zhu@sap.com>
* fix: code formatting
* test: fix tests for getRemoteUrl
Co-authored-by: MildC <kevin.xizhu@gmail.com>
Co-authored-by: Kevin Zhu <kevin.zhu@sap.com>
* Update GA quote/ref in concepts-guidelines.md
The current quote and reference link appear to be out of date
* Change "Triggering further workflow runs" excerpt
* Strip optional '.git' suffix from https server remote name.
* Revert "Strip optional '.git' suffix from https server remote name."
This reverts commit c2e9041213.
* Strip optional '.git' suffix from https server remote name.
- [Concepts, guidelines and advanced usage](docs/concepts-guidelines.md)
- [Examples](docs/examples.md)
- [Updating to v3](docs/updating.md)
- [Updating to v5](docs/updating.md)
## Usage
```yml
- uses:actions/checkout@v3
# Make changes to pull request here
- name:Create Pull Request
uses:peter-evans/create-pull-request@v3
uses:peter-evans/create-pull-request@v5
```
You can also pin to a [specific release](https://github.com/peter-evans/create-pull-request/releases) version in the format `@v3.x.x`
You can also pin to a [specific release](https://github.com/peter-evans/create-pull-request/releases) version in the format `@v5.x.x`
### Workflow permissions
For this action to work you must explicitly allow GitHub Actions to create pull requests.
This setting can be found in a repository's settings under Actions > General > Workflow permissions.
For repositories belonging to an organization, this setting can be managed by admins in organization settings under Actions > General > Workflow permissions.
### Action inputs
@ -40,48 +51,57 @@ All inputs are **optional**. If not set, sensible defaults will be used.
| Name | Description | Default |
| --- | --- | --- |
| `token` | `GITHUB_TOKEN` or a `repo` scoped [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). | `GITHUB_TOKEN` |
| `token` | `GITHUB_TOKEN` (permissions `contents: write` and `pull-requests: write`) or a `repo` scoped [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). | `GITHUB_TOKEN` |
| `path` | Relative path under `GITHUB_WORKSPACE` to the repository. | `GITHUB_WORKSPACE` |
| `add-paths` | A comma or newline-separated list of file paths to commit. Paths should follow git's [pathspec](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefpathspecapathspec) syntax. If no paths are specified, all new and modified files are added. See [Add specific paths](#add-specific-paths). | |
| `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. | `GitHub <noreply@github.com>` |
| `author` | The author name and email address in the format `Display Name <email@address.com>`. Defaults to the user who triggered the workflow run. | `${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>` |
| `signoff` | Add [`Signed-off-by`](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff) line by the committer at the end of the commit log message. | `false` |
| `delete-branch` | Delete the `branch` when closing pull requests, and when undeleted after merging. | `false` |
| `branch-suffix` | The branch suffix type when using the alternative branching strategy. Valid values are `random`, `timestamp` and `short-commit-hash`. See [Alternative strategy](#alternative-strategy---always-create-a-new-pull-request-branch) for details. | |
| `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](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` |
| `body-path` | The path to a file containing the pull request body. Takes precedence over `body`. | |
| `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://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) may be required. See [this issue](https://github.com/peter-evans/create-pull-request/issues/155). | |
| `team-reviewers` | A comma or newline-separated list of GitHub teams to request a review from. Note that a `repo` scoped [PAT](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token), or equivalent [GitHub App permissions](docs/concepts-guidelines.md#authenticating-with-github-app-generated-tokens), are required. | |
| `milestone` | The number of the milestone to associate this pull request with. | |
| `draft` | Create a [draft pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests#draft-pull-requests). It is not possible to change draft status after creation except through the web interface. | `false` |
For self-hosted runners behind a corporate proxy set the `https_proxy` environment variable.
```yml
- name:Create Pull Request
uses:peter-evans/create-pull-request@v5
env:
https_proxy:http://<proxy_address>:<port>
```
### Action outputs
The pull request number is output as a step output.
Note that in order to read the step output the action step must have an id.
The following outputs can be used by subsequent workflow steps.
-`pull-request-number` - The pull request number.
-`pull-request-url` - The URL of the pull request.
-`pull-request-operation` - The pull request operation performed by the action, `created`, `updated` or `closed`.
-`pull-request-head-sha` - The commit SHA of the pull request branch.
Step outputs can be accessed as in the following example.
Note that in order to read the step outputs the action step must have an id.
```yml
- name:Create Pull Request
id:cpr
uses:peter-evans/create-pull-request@v3
uses:peter-evans/create-pull-request@v5
- name:Check outputs
if:${{ steps.cpr.outputs.pull-request-number }}
run:|
echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"
```
### 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.
- 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.
- If a pull request already exists it will be updated if necessary. Local changes in the Actions workspace, or changes on the base branch, can cause an update. If no update is required 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 pull request branch and the base), the pull request is automatically closed. Additionally, if `delete-branch` is set to `true` the `branch` will be deleted.
For further details about how the action works and usage guidelines, see [Concepts, guidelines and advanced usage](docs/concepts-guidelines.md).
@ -112,13 +132,48 @@ To use this strategy, set input `branch-suffix` with one of the following option
-`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`
### Controlling commits
### Controlling committed files
The action defaults to adding all new and modified files.
If there are files that should not be included in the pull request, you can use the following methods to control the committed content.
#### Remove files
The most straightforward way to handle unwanted files is simply to remove them in a step before the action runs.
```yml
- run:|
rm -rf temp-dir
rm temp-file.txt
```
#### Ignore 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.
#### Add specific paths
You can control which files are committed with the `add-paths` input.
Paths should follow git's [pathspec](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefpathspecapathspec) syntax.
File changes that do not match one of the paths will be stashed and restored after the action has completed.
```yml
- name:Create Pull Request
uses:peter-evans/create-pull-request@v5
with:
add-paths:|
*.java
docs/*.md
```
#### Create your own commits
As well as relying on the action to handle uncommitted changes, you can additionally make your own commits before the action runs.
Note that the repository must be checked out on a branch with a remote, it won't work for [events which checkout a commit](docs/concepts-guidelines.md#events-which-checkout-a-commit).
```yml
steps:
- uses:actions/checkout@v2
- uses:actions/checkout@v3
- name:Create commits
run:|
git config user.name 'Peter Evans'
@ -131,13 +186,9 @@ As well as relying on the action to handle uncommitted changes, you can addition
- name:Uncommitted change
run:date +%s > report.txt
- name:Create Pull Request
uses:peter-evans/create-pull-request@v3
uses:peter-evans/create-pull-request@v5
```
### 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.
@ -145,37 +196,42 @@ To create a project card for the pull request, pass the `pull-request-number` st
- [Running in a container or on self-hosted runners](#running-in-a-container-or-on-self-hosted-runners)
- [Creating pull requests on tag push](#creating-pull-requests-on-tag-push)
## Terminology
@ -30,21 +30,20 @@ A pull request references two branches:
## Events and checkout
For each [event type](https://docs.github.com/en/actions/reference/events-that-trigger-workflows) there is a default `GITHUB_SHA` that will be checked out by the GitHub Actions [checkout](https://github.com/actions/checkout) action.
The majority of events will default to checking out the "last commit on default branch," which in most cases will be the latest commit on `master`.
This action expects repositories to be checked out with the official GitHub Actions [checkout](https://github.com/actions/checkout) action.
For each [event type](https://docs.github.com/en/actions/reference/events-that-trigger-workflows) there is a default `GITHUB_SHA` that will be checked out.
The default can be overridden by specifying a `ref` on checkout.
```yml
- uses:actions/checkout@v2
- uses:actions/checkout@v3
with:
ref:develop
```
## How the action works
By default, the action expects to be executed on the pull request `base`—the branch you intend to modify with the proposed changes.
Unless the `base` input is supplied, the action expects the target repository to be checked out on the pull request `base`—the branch you intend to modify with the proposed changes.
Workflow steps:
@ -60,11 +59,11 @@ The following git diagram shows how the action creates and updates a pull reques
### Providing a consistent base
For the action to work correctly it should be executed in a workflow that checks out a *consistent base* branch. This will be the base of the pull request unless overridden with the `base` input.
For the action to work correctly it should be executed in a workflow that checks out a *consistent* base branch. This will be the base of the pull request unless overridden with the `base` input.
This means your workflow should be consistently checking out the branch that you intend to modify once the PR is merged.
In the following example, the [`push`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#push) and [`create`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#create) events both trigger the same workflow. This will cause the checkout action to checkout commits from inconsistent branches. Do *not* do this. It will cause multiple pull requests to be created for each additional `base` the action is executed against.
In the following example, the [`push`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#push) and [`create`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#create) events both trigger the same workflow. This will cause the checkout action to checkout inconsistent branches and commits. Do *not* do this. It will cause multiple pull requests to be created for each additional `base` the action is executed against.
```yml
on:
@ -74,19 +73,32 @@ jobs:
example:
runs-on:ubuntu-latest
steps:
- uses:actions/checkout@v2
- uses:actions/checkout@v3
```
Although rare, there may be use cases where it makes sense to execute the workflow on a branch that is not the base of the pull request. In these cases, the base branch can be specified with the `base` action input. The action will attempt to rebase changes made during the workflow on to the actual base.
There may be use cases where it makes sense to execute the workflow on a branch that is not the base of the pull request. In these cases, the base branch can be specified with the `base` action input. The action will attempt to rebase changes made during the workflow on to the actual base.
### Pull request events
### Events which checkout a commit
Workflows triggered by `pull_request` events will by default checkout a [merge commit](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request). To prevent the merge commit being included in created pull requests it is necessary to checkout the `head_ref`.
The [default checkout](#events-and-checkout) for the majority of events will leave the repository checked out on a branch.
However, some events such as `release` and `pull_request` will leave the repository in a "detached HEAD" state.
This is because they checkout a commit, not a branch.
In these cases, you *must supply* the `base` input so the action can rebase changes made during the workflow for the pull request.
Workflows triggered by [`pull_request`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request) events will by default check out a merge commit. Set the `base` input as follows to base the new pull request on the current pull request's branch.
```yml
- uses:actions/checkout@v2
- uses:peter-evans/create-pull-request@v5
with:
ref:${{ github.head_ref }}
base:${{ github.head_ref }}
```
Workflows triggered by [`release`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#release) events will by default check out a tag. For most use cases, you will need to set the `base` input to the branch name of the tagged commit.
For further reading regarding the security of pull requests, see this GitHub blog post titled [Keeping your GitHub Actions and workflows secure: Preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/)
### Triggering further workflow runs
Pull requests created by the action using the default `GITHUB_TOKEN` cannot trigger other workflows. If you have `on: pull_request` or `on: push` workflows acting as checks on pull requests, they will not run.
> When you use the repository's GITHUB_TOKEN to perform tasks on behalf of the GitHub Actions app, events triggered by the GITHUB_TOKEN will not create a new workflow run.
> When you use the repository's `GITHUB_TOKEN` to perform tasks, events triggered by the `GITHUB_TOKEN` will not create a new workflow run. This prevents you from accidentally creating recursive workflow runs. For example, if a workflow run pushes code using the repository's `GITHUB_TOKEN`, a new workflow will not run even when the repository contains a workflow configured to run when `push` events occur.
[GitHub Actions: Events that trigger workflows](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#triggering-new-workflows-using-a-personal-access-token)
[GitHub Actions: Triggering a workflow from a workflow](https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#triggering-a-workflow-from-a-workflow)
#### Workarounds to trigger further workflow runs
There are a number of workarounds with different pros and cons.
- Use the default `GITHUB_TOKEN` and allow the action to create pull requests that have no checks enabled. Manually close pull requests and immediately reopen them. This will enable `on: pull_request` workflows to run and be added as checks.
- Use a `repo` scoped [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) created on an account that has write access to the repository that pull requests are being created in. This is the standard workaround and [recommended by GitHub](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#triggering-new-workflows-using-a-personal-access-token). However, the PAT cannot be scoped to a specific repository so the token becomes a very sensitive secret. If this is a concern, the PAT can instead be created for a dedicated [machine account](https://docs.github.com/en/github/site-policy/github-terms-of-service#3-account-requirements) that has collaborator access to the repository. Also note that because the account that owns the PAT will be the creator of pull requests, that user account will be unable to perform actions such as request changes or approve the pull request.
- Use the default `GITHUB_TOKEN` and allow the action to create pull requests that have no checks enabled. Manually close pull requests and immediately reopen them. This will enable `on: pull_request` workflows to run and be added as checks. To prevent merging of pull requests without checks erroneously, use [branch protection rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests).
- Use a `repo` scoped [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) created on an account that has write access to the repository that pull requests are being created in. This is the standard workaround and [recommended by GitHub](https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#triggering-a-workflow-from-a-workflow). However, the PAT cannot be scoped to a specific repository so the token becomes a very sensitive secret. If this is a concern, the PAT can instead be created for a dedicated [machine account](https://docs.github.com/en/github/site-policy/github-terms-of-service#3-account-requirements) that has collaborator access to the repository. Also note that because the account that owns the PAT will be the creator of pull requests, that user account will be unable to perform actions such as request changes or approve the pull request.
- Use [SSH (deploy keys)](#push-using-ssh-deploy-keys) to push the pull request branch. This is arguably more secure than using a PAT because deploy keys can be set per repository. However, this method will only trigger `on: push` workflows.
- Use a [machine account that creates pull requests from its own fork](#push-pull-request-branches-to-a-fork). This is the most secure because the PAT created only grants access to the machine account's fork, not the main repository. This method will trigger `on: pull_request` workflows to run. Workflows triggered `on: push` will not run because the push event is in the fork.
- Use a [GitHub App to generate a token](#authenticating-with-github-app-generated-tokens) that can be used with this action. GitHub App generated tokens are more secure than using a PAT because GitHub App access permissions can be set with finer granularity and are scoped to only repositories where the App is installed. This method will trigger both `on: push` and `on: pull_request` workflows.
### Security
@ -146,7 +164,7 @@ Alternatively, use the action directly and reference the commit hash for the ver
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.
This action uses [ncc](https://github.com/vercel/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/main/dist) directory.
## Advanced usage
@ -155,14 +173,14 @@ This action uses [ncc](https://github.com/zeit/ncc) to compile the Node.js code
Checking out a branch from a different repository from where the workflow is executing will make *that repository* the target for the created pull request. In this case, a `repo` scoped [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) is required.
```yml
- uses:actions/checkout@v2
- uses:actions/checkout@v3
with:
token:${{ secrets.PAT }}
repository:owner/repo
# Make changes to pull request here
- uses:peter-evans/create-pull-request@v3
- uses:peter-evans/create-pull-request@v5
with:
token:${{ secrets.PAT }}
```
@ -182,22 +200,23 @@ How to use SSH (deploy keys) with create-pull-request action:
```yml
steps:
- uses:actions/checkout@v2
- uses:actions/checkout@v3
with:
ssh-key:${{ secrets.SSH_PRIVATE_KEY }}
# Make changes to pull request here
- name:Create Pull Request
uses:peter-evans/create-pull-request@v3
uses:peter-evans/create-pull-request@v5
```
### Push pull request branches to a fork
Instead of pushing pull request branches to the repository you want to update, you can push them to a fork of that repository.
This allows you to employ the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) by using a dedicated user acting as a [machine account](https://docs.github.com/en/github/site-policy/github-terms-of-service#3-account-requirements).
This user has no access to the main repository.
This user only has `read` access to the main repository.
It will use their own fork to push code and create the pull request.
Note that if you choose to use this method (not give the machine account `write` access to the repository) the following inputs cannot be used: `labels`, `assignees`, `reviewers`, `team-reviewers` and `milestone`.
1. Create a new GitHub user and login.
2. Fork the repository that you will be creating pull requests in.
@ -207,16 +226,18 @@ It will use their own fork to push code and create the pull request.
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
- uses:actions/checkout@v3
# Make changes to pull request here
- uses:peter-evans/create-pull-request@v3
- uses:peter-evans/create-pull-request@v5
with:
token:${{ secrets.MACHINE_USER_PAT }}
push-to-fork:machine-user/fork-of-repository
```
Note: You can also combine `push-to-fork` with [creating pull requests in a remote repository](#creating-pull-requests-in-a-remote-repository).
### Authenticating with GitHub App generated tokens
A GitHub App can be created for the sole purpose of generating tokens for use with GitHub actions.
@ -230,6 +251,8 @@ GitHub App generated tokens are more secure than using a PAT because GitHub App
- Uncheck `Active` under `Webhook`. You do not need to enter a `Webhook URL`.
- Under `Repository permissions: Contents` select `Access: Read & write`.
- Under `Organization permissions: Members` select `Access: Read-only`.
- **NOTE**: Only needed if you would like add teams as reviewers to PRs.
2. Create a Private key from the App settings page and store it securely.
@ -241,7 +264,7 @@ GitHub App generated tokens are more secure than using a PAT because GitHub App
```yaml
steps:
- uses:actions/checkout@v2
- uses:actions/checkout@v3
- uses:tibdex/github-app-token@v1
id:generate-token
@ -252,11 +275,53 @@ GitHub App generated tokens are more secure than using a PAT because GitHub App
# Make changes to pull request here
- name:Create Pull Request
uses:peter-evans/create-pull-request@v3
uses:peter-evans/create-pull-request@v5
with:
token:${{ steps.generate-token.outputs.token }}
```
### GPG commit signature verification
The action can use GPG to sign commits with a GPG key that you generate yourself.
1. Follow GitHub's guide to [generate a new GPG key](https://docs.github.com/en/github/authenticating-to-github/generating-a-new-gpg-key).
2. [Add the public key](https://docs.github.com/en/github/authenticating-to-github/adding-a-new-gpg-key-to-your-github-account) to the user account associated with the [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) that you will use with the action.
3. Copy the private key to your clipboard, replacing `email@example.com` with the email address of your GPG key.
4. Paste the private key into a repository secret where the workflow will run. e.g. `GPG_PRIVATE_KEY`
5. Create another repository secret for the key's passphrase, if applicable. e.g. `GPG_PASSPHRASE`
6. The following example workflow shows how to use [crazy-max/ghaction-import-gpg](https://github.com/crazy-max/ghaction-import-gpg) to import your GPG key and allow the action to sign commits.
Note that the `committer` email address *MUST* match the email address used to create your GPG key.
```yaml
steps:
- uses: actions/checkout@v3
- uses: crazy-max/ghaction-import-gpg@v3
with:
gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
passphrase: ${{ secrets.GPG_PASSPHRASE }}
git-user-signingkey: true
git-commit-gpgsign: true
# Make changes to pull request here
- name: Create Pull Request
uses: peter-evans/create-pull-request@v5
with:
token: ${{ secrets.PAT }}
committer: example <email@example.com>
```
### Running in a container or on self-hosted runners
This action can be run inside a container, or on [self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners), by installing the necessary dependencies.
@ -276,12 +341,12 @@ jobs:
- name: Install dependencies
run: apk --no-cache add git
- uses:actions/checkout@v2
- uses: actions/checkout@v3
# Make changes to pull request here
- name: Create Pull Request
uses:peter-evans/create-pull-request@v3
uses: peter-evans/create-pull-request@v5
```
**Ubuntu container example:**
@ -299,70 +364,10 @@ jobs:
add-apt-repository -y ppa:git-core/ppa
apt-get install -y git
- uses:actions/checkout@v2
- uses: actions/checkout@v3
# Make changes to pull request here
- name: Create Pull Request
uses:peter-evans/create-pull-request@v3
```
### Creating pull requests on tag push
An `on: push` workflow will also trigger when tags are pushed.
During these events, the `actions/checkout` action will check out the `ref/tags/<tag>` git ref by default.
This means the repository will *not* be checked out on an active branch.
If you would like to run `create-pull-request` action on the tagged commit you can achieve this by creating a temporary branch as follows.
This is an alternative, simpler workflow to the one above. However, this is not guaranteed to checkout the tagged commit.
There is a chance that in between the tag being pushed and checking out the `master` branch in the workflow, another commit is made to `master`. If that possibility is not a concern, this workflow will work fine.
This is a use case where a branch should be kept up to date with another by opening a pull request to update it. The pull request should then be updated with new changes until it is merged or closed.
In this example scenario, a branch called `production` should be updated via pull request to keep it in sync with `master`. Merging the pull request is effectively promoting those changes to production.
In this example scenario, a branch called `production` should be updated via pull request to keep it in sync with `main`. Merging the pull request is effectively promoting those changes to production.
```yml
name:Create production promotion pull request
on:
push:
branches:
- master
- main
jobs:
productionPromotion:
runs-on:ubuntu-latest
steps:
- uses:actions/checkout@v2
- uses:actions/checkout@v3
with:
ref:production
- name:Reset promotion branch
run:|
git fetch origin master:master
git reset --hard master
git fetch origin main:main
git reset --hard main
- name:Create Pull Request
uses:peter-evans/create-pull-request@v3
uses:peter-evans/create-pull-request@v5
with:
branch:production-promotion
```
## Use case: Create a pull request to update X on release
This pattern will work well for updating any kind of static content based on the tagged commit of a release. Note that because `release` is one of the [events which checkout a commit](concepts-guidelines.md#events-which-checkout-a-commit) it is necessary to supply the `base` input to the action.
### Update changelog
Raises a pull request to update the `CHANGELOG.md` file based on the tagged commit of the release.
Note that [git-chglog](https://github.com/git-chglog/git-chglog/) requires some configuration files to exist in the repository before this workflow will work.
This workflow assumes the tagged release was made on a default branch called `main`.
## Use case: Create a pull request to update X periodically
This pattern will work well for updating any kind of static content from an external source. The workflow executes on a schedule and raises a pull request when there are changes.
@ -101,16 +145,16 @@ jobs:
update-dep:
runs-on:ubuntu-latest
steps:
- uses:actions/checkout@v2
- uses:actions/setup-node@v1
- uses:actions/checkout@v3
- uses:actions/setup-node@v3
with:
node-version:'12.x'
node-version:'16.x'
- name:Update dependencies
run:|
npx -p npm-check-updates ncu -u
npm install
- name:Create Pull Request
uses:peter-evans/create-pull-request@v3
uses:peter-evans/create-pull-request@v5
with:
token:${{ secrets.PAT }}
commit-message:Update dependencies
@ -130,17 +174,17 @@ The above workflow works best in combination with a build workflow triggered on
name:CI
on:
push:
branches:[master]
branches:[main]
pull_request:
branches:[master]
branches:[main]
jobs:
build:
runs-on:ubuntu-latest
steps:
- uses:actions/checkout@v2
- uses:actions/setup-node@v1
- uses:actions/checkout@v3
- uses:actions/setup-node@v3
with:
node-version:12.x
node-version:16.x
- run:npm ci
- run:npm run test
- run:npm run build
@ -161,16 +205,17 @@ jobs:
update-dep:
runs-on:ubuntu-latest
steps:
- uses:actions/checkout@v2
- uses:actions/setup-java@v1
- uses:actions/checkout@v3
- uses:actions/setup-java@v2
with:
distribution:'temurin'
java-version:1.8
- name:Grant execute permission for gradlew
run:chmod +x gradlew
- name:Perform dependency resolution and write new lockfiles
commit-message:Update swagger-ui to ${{ steps.swagger-ui.outputs.release_tag }}
title:Update SwaggerUI to ${{ steps.swagger-ui.outputs.release_tag }}
@ -276,6 +323,41 @@ jobs:
branch:swagger-ui-updates
```
### Keep a fork up-to-date with its upstream
This example is designed to be run in a seperate repository from the fork repository itself.
The aim of this is to prevent committing anything to the fork's default branch would cause it to differ from the upstream.
In the following example workflow, `owner/repo` is the upstream repository and `fork-owner/repo` is the fork. It assumes the default branch of the upstream repository is called `main`.
The [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) should have `repo` scope. Additionally, if the upstream makes changes to the `.github/workflows` directory, the action will be unable to push the changes to a branch and throw the error "_(refusing to allow a GitHub App to create or update workflow `.github/workflows/xxx.yml` without `workflows` permission)_". To allow these changes to be pushed to the fork, add the `workflow` scope to the PAT. Of course, allowing this comes with the risk that the workflow changes from the upstream could run and do something unexpected. Disabling GitHub Actions in the fork is highly recommended to prevent this.
When you merge the pull request make sure to choose the [`Rebase and merge`](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges#rebase-and-merge-your-pull-request-commits) option. This will make the fork's commits match the commits on the upstream.
```yml
name:Update fork
on:
schedule:
- cron:'0 0 * * 0'
jobs:
updateFork:
runs-on:ubuntu-latest
steps:
- uses:actions/checkout@v3
with:
repository:fork-owner/repo
- name:Reset the default branch with upstream changes
If you have git hooks that prevent the action from working correctly you can remove them before running the action.
```yml
# Remove git hooks
- run:rm -rf .git/hooks
- name:Create Pull Request
uses:peter-evans/create-pull-request@v5
```
### 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`](https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-output-parameter). Note that the step where output variables are defined must have an id.
Note that the step where output variables are defined must have an id.
pr_body="This PR was auto-generated on $(date +%d-%m-%Y) \
by [create-pull-request](https://github.com/peter-evans/create-pull-request)."
echo "pr_title=$pr_title" >> $GITHUB_OUTPUT
echo "pr_body=$pr_body" >> $GITHUB_OUTPUT
- name:Create Pull Request
uses:peter-evans/create-pull-request@v3
uses:peter-evans/create-pull-request@v5
with:
title:${{ steps.vars.outputs.pr_title }}
body:${{ steps.vars.outputs.pr_body }}
```
Alternatively, [`set-env`](https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-environment-variable) can be used to create environment variables.
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@v3
with:
title:${{ env.PULL_REQUEST_TITLE }}
body:${{ env.PULL_REQUEST_BODY }}
In this example, a markdown template file is added to the repository at `.github/pull-request-template.md` with the following content.
```
This is a test pull request template
Render template variables such as {{ .foo }} and {{ .bar }}.
```
### Setting the pull request body from a file
This example shows how file content can be read into a variable and passed to the action.
The content must be [escaped to preserve newlines](https://github.community/t/set-output-truncates-multiline-strings/16852/3).
The template is rendered using the [render-template](https://github.com/chuhlomin/render-template) action and the result is used to create the pull request.
- The action will no longer leave the local repository checked out on the pull request `branch`. Instead, it will leave the repository checked out on the branch or commit that it was when the action started.
- When using `add-paths`, uncommitted changes will no longer be destroyed. They will be stashed and restored at the end of the action run.
### What's new
- Adds input `body-path`, the path to a file containing the pull request body.
- At the end of the action run the local repository is now checked out on the branch or commit that it was when the action started.
- Any uncommitted tracked or untracked changes are now stashed and restored at the end of the action run. Currently, this can only occur when using the `add-paths` input, which allows for changes to not be committed. Previously, any uncommitted changes would be destroyed.
- The proxy implementation has been revised but is not expected to have any change in behaviour. It continues to support the standard environment variables `http_proxy`, `https_proxy` and `no_proxy`.
- Now sets the git `safe.directory` configuration for the local repository path. The configuration is removed when the action completes. Fixes issue https://github.com/peter-evans/create-pull-request/issues/1170.
- Now determines the git directory path using the `git rev-parse --git-dir` command. This allows users with custom repository configurations to use the action.
- Improved handling of the `team-reviewers` input and associated errors.
## Updating from `v3` to `v4`
### Behaviour changes
- The `add-paths` input no longer accepts `-A` as a valid value. When committing all new and modified files the `add-paths` input should be omitted.
- If using self-hosted runners or GitHub Enterprise Server, there are minimum requirements for `v4` to run. See "What's new" below for details.
### What's new
- Updated runtime to Node.js 16
- The action now requires a minimum version of v2.285.0 for the [Actions Runner](https://github.com/actions/runner/releases/tag/v2.285.0).
- If using GitHub Enterprise Server, the action requires [GHES 3.4](https://docs.github.com/en/enterprise-server@3.4/admin/release-notes) or later.
## Updating from `v2` to `v3`
### Breaking changes
### Behaviour changes
- The `author` input now defaults to the user who triggered the workflow run. This default is set via [action.yml](../action.yml) as `${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>`, where `github.actor` is the GitHub user account associated with the run. For example, `peter-evans <peter-evans@users.noreply.github.com>`.
@ -31,7 +62,7 @@
push-to-fork: machine-user/fork-of-repository
```
### New features
### What's new
- The action has been converted to Typescript giving it a significant performance improvement.
@ -48,7 +79,7 @@
## Updating from `v1` to `v2`
### Breaking changes
### Behaviour changes
- `v2` now expects repositories to be checked out with `actions/checkout@v2`
@ -66,8 +97,8 @@
If neither `author` or `committer` are set the action will default to making commits as the GitHub Actions bot user.
### New features
### What's new
- 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.
- Unpushed commits made during the workflow before the action runs will now be considered as changes to be raised in the pull request. See [Create your own commits](https://github.com/peter-evans/create-pull-request#create-your-own-commits) for details.
- New commits made to the pull request base will now be taken into account when pull requests are updated.
- If an updated pull request no longer differs from its base it will automatically be closed and the pull request branch deleted.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
