* Update git.fetch calls to use depth=1 (#2810)
* When base is set, fetch depth=1
* PR Feedback - remove depth=1 from tryFetch function
* push-to-fork fix
* test updates to handle shallow fetch of base
---------
Co-authored-by: Eric Webb <eric@collectivegenius.net>
* feat: update author and committer input defaults
* Update github-actions[bot]
* Update author to new email format
* feat: optional input for git ops token
* feat: allow push-to-fork to push to sibling repos (#2414)
Fixes#2412.
* build: update dist
* feat: update action runtime to node 20 (#2340)
* feat: add truncate warning to pull request body
* perf: unshallow only when necessary
* fix: remove the remote for the fork on completion
* feat: infer github server and api urls
* test: integration test fixes
* build: bump major version
* docs: update to v6
---------
Co-authored-by: Teko <112829523+Teko012@users.noreply.github.com>
Co-authored-by: Benjamin Gilbert <bgilbert@backtick.net>
- [Concepts, guidelines and advanced usage](docs/concepts-guidelines.md)
- [Concepts, guidelines and advanced usage](docs/concepts-guidelines.md)
- [Examples](docs/examples.md)
- [Examples](docs/examples.md)
- [Updating to v5](docs/updating.md)
- [Updating to v6](docs/updating.md)
- [Common issues](docs/common-issues.md)
## Usage
## Usage
```yml
```yml
- uses:actions/checkout@v3
- uses:actions/checkout@v4
# Make changes to pull request here
# Make changes to pull request here
- name:Create Pull Request
- name:Create Pull Request
uses:peter-evans/create-pull-request@v5
uses:peter-evans/create-pull-request@v6
```
```
You can also pin to a [specific release](https://github.com/peter-evans/create-pull-request/releases) version in the format `@v5.x.x`
You can also pin to a [specific release](https://github.com/peter-evans/create-pull-request/releases) version in the format `@v6.x.x`
### Workflow permissions
### Workflow permissions
@ -52,14 +53,15 @@ All inputs are **optional**. If not set, sensible defaults will be used.
| Name | Description | Default |
| Name | Description | Default |
| --- | --- | --- |
| --- | --- | --- |
| `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` |
| `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` |
| `git-token` | The [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) that the action will use for git operations. | Defaults to the value of `token` |
| `path` | Relative path under `GITHUB_WORKSPACE` to the repository. | `GITHUB_WORKSPACE` |
| `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). | |
| `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` |
| `commit-message` | The message to use when committing changes. See [commit-message](#commit-message). | `[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>` |
| `committer` | The committer name and email address in the format `Display Name <email@address.com>`. Defaults to the GitHub Actions bot user on github.com. | `github-actions[bot] <41898282+github-actions[bot]@users.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>` |
| `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_id }}+${{ 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` |
| `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` |
| `delete-branch` | Delete the `branch`if it doesn't have an active pull request associated with it. See [delete-branch](#delete-branch). | `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. | |
| `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. |
| `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. | |
| `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. | |
@ -72,11 +74,38 @@ All inputs are **optional**. If not set, sensible defaults will be used.
| `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. | |
| `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. | |
| `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` |
| `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` |
| `sign-commit` | Sign the commit as bot [refer: [Signature verification for bots](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#signature-verification-for-bots)]. This can be useful if your repo or org has enforced commit-signing. | `false` |
#### commit-message
In addition to a message, the `commit-message` input can also be used to populate the commit description. Leave a single blank line between the message and description.
```yml
commit-message:|
the first line is the commit message
the commit description starts
after a blank line and can be
multiple lines
```
#### delete-branch
The `delete-branch` feature doesn't delete branches immediately on merge. (It can't do that because it would require the merge to somehow trigger the action.)
The intention of the feature is that when the action next runs it will delete the `branch` if there is no diff.
Enabling this feature leads to the following behaviour:
1. If a pull request was merged and the branch is left undeleted, when the action next runs it will delete the branch if there is no further diff.
2. If a pull request is open, but there is now no longer a diff and the PR is unnecessary, the action will delete the branch causing the PR to close.
If you want branches to be deleted immediately on merge then you should use GitHub's `Automatically delete head branches` feature in your repository settings.
#### Proxy support
For self-hosted runners behind a corporate proxy set the `https_proxy` environment variable.
For self-hosted runners behind a corporate proxy set the `https_proxy` environment variable.
```yml
```yml
- name:Create Pull Request
- name:Create Pull Request
uses:peter-evans/create-pull-request@v5
uses:peter-evans/create-pull-request@v6
env:
env:
https_proxy:http://<proxy_address>:<port>
https_proxy:http://<proxy_address>:<port>
```
```
@ -89,6 +118,7 @@ The following outputs can be used by subsequent workflow steps.
-`pull-request-url` - The URL of the pull request.
-`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-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.
-`pull-request-head-sha` - The commit SHA of the pull request branch.
-`pull-request-branch` - The branch name of the pull request.
Step outputs can be accessed as in the following example.
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.
Note that in order to read the step outputs the action step must have an id.
@ -96,7 +126,7 @@ Note that in order to read the step outputs the action step must have an id.
```yml
```yml
- name:Create Pull Request
- name:Create Pull Request
id:cpr
id:cpr
uses:peter-evans/create-pull-request@v5
uses:peter-evans/create-pull-request@v6
- name:Check outputs
- name:Check outputs
if:${{ steps.cpr.outputs.pull-request-number }}
if:${{ steps.cpr.outputs.pull-request-number }}
run:|
run:|
@ -115,7 +145,7 @@ How the action behaves:
- 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 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 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 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 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.
- 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`](#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).
For further details about how the action works and usage guidelines, see [Concepts, guidelines and advanced usage](docs/concepts-guidelines.md).
@ -159,7 +189,7 @@ File changes that do not match one of the paths will be stashed and restored aft
```yml
```yml
- name:Create Pull Request
- name:Create Pull Request
uses:peter-evans/create-pull-request@v5
uses:peter-evans/create-pull-request@v6
with:
with:
add-paths:|
add-paths:|
*.java
*.java
@ -173,7 +203,7 @@ Note that the repository must be checked out on a branch with a remote, it won't
```yml
```yml
steps:
steps:
- uses:actions/checkout@v3
- uses:actions/checkout@v4
- name:Create commits
- name:Create commits
run:|
run:|
git config user.name 'Peter Evans'
git config user.name 'Peter Evans'
@ -186,7 +216,7 @@ Note that the repository must be checked out on a branch with a remote, it won't
- name:Uncommitted change
- name:Uncommitted change
run:date +%s > report.txt
run:date +%s > report.txt
- name:Create Pull Request
- name:Create Pull Request
uses:peter-evans/create-pull-request@v5
uses:peter-evans/create-pull-request@v6
```
```
### Create a project card
### Create a project card
@ -196,7 +226,7 @@ To create a project card for the pull request, pass the `pull-request-number` st
- [Disable force updates to existing PR branches](#disable-force-updates-to-existing-pr-branches)
- [Add a no-verify option to bypass git hooks](#add-a-no-verify-option-to-bypass-git-hooks)
## Troubleshooting
### Create using an existing branch as the PR branch
A common point of confusion is to try and use an existing branch containing changes to raise in a PR as the `branch` input. This will not work because the action is primarily designed to be used in workflows where the PR branch does not exist yet. The action creates and manages the PR branch itself.
If you have an existing branch that you just want to create a PR for, then I recommend using the official [GitHub CLI](https://cli.github.com/manual/gh_pr_create) in a workflow step.
Alternatively, if you are trying to keep a branch up to date with another branch, then you can follow [this example](https://github.com/peter-evans/create-pull-request/blob/main/docs/examples.md#keep-a-branch-up-to-date-with-another).
## Frequently requested features
### Disable force updates to existing PR branches
This behaviour is fundamental to how the action works and is a conscious design decision. The "rule" that I based this design on is that when a workflow executes the action to create or update a PR, the result of those two possible actions should never be different. The easiest way to maintain that consistency is to rebase the PR branch and force push it.
If you want to avoid this behaviour there are some things that might work depending on your use case:
- Check if the pull request branch exists in a separate step before the action runs and act accordingly.
- Use the [alternative strategy](https://github.com/peter-evans/create-pull-request#alternative-strategy---always-create-a-new-pull-request-branch) of always creating a new PR that won't be updated by the action.
- [Create your own commits](https://github.com/peter-evans/create-pull-request#create-your-own-commits) each time the action is created/updated.
### Add a no-verify option to bypass git hooks
Presently, there is no plan to add this feature to the action.
The reason is that I'm trying very hard to keep the interface for this action to a minimum to prevent it becoming bloated and complicated.
Git hooks must be installed after a repository is checked out in order for them to work.
So the straightforward solution is to just not install them during the workflow where this action is used.
- If hooks are automatically enabled by a framework, use an option provided by the framework to disable them. For example, for Husky users, they can be disabled with the `--ignore-scripts` flag, or by setting the `HUSKY` environment variable when the action runs.
```yml
uses: peter-evans/create-pull-request@v6
env:
HUSKY: '0'
```
- If hooks are installed in a script, then add a condition checking if the `CI` environment variable exists.
```sh
#!/bin/sh
[ -n "$CI" ] && exit 0
```
- If preventing the hooks installing is problematic, just delete them in a workflow step before the action runs.
@ -36,7 +36,7 @@ For each [event type](https://docs.github.com/en/actions/reference/events-that-t
The default can be overridden by specifying a `ref` on checkout.
The default can be overridden by specifying a `ref` on checkout.
```yml
```yml
- uses:actions/checkout@v3
- uses:actions/checkout@v4
with:
with:
ref:develop
ref:develop
```
```
@ -73,7 +73,7 @@ jobs:
example:
example:
runs-on:ubuntu-latest
runs-on:ubuntu-latest
steps:
steps:
- uses:actions/checkout@v3
- uses:actions/checkout@v4
```
```
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.
@ -88,7 +88,7 @@ In these cases, you *must supply* the `base` input so the action can rebase chan
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.
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
```yml
- uses:peter-evans/create-pull-request@v5
- uses:peter-evans/create-pull-request@v6
with:
with:
base:${{ github.head_ref }}
base:${{ github.head_ref }}
```
```
@ -96,7 +96,7 @@ Workflows triggered by [`pull_request`](https://docs.github.com/en/actions/refer
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.
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.
```yml
```yml
- uses:peter-evans/create-pull-request@v5
- uses:peter-evans/create-pull-request@v6
with:
with:
base:main
base:main
```
```
@ -173,14 +173,14 @@ This action uses [ncc](https://github.com/vercel/ncc) to compile the Node.js cod
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.
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
```yml
- uses:actions/checkout@v3
- uses:actions/checkout@v4
with:
with:
token:${{ secrets.PAT }}
token:${{ secrets.PAT }}
repository:owner/repo
repository:owner/repo
# Make changes to pull request here
# Make changes to pull request here
- uses:peter-evans/create-pull-request@v5
- uses:peter-evans/create-pull-request@v6
with:
with:
token:${{ secrets.PAT }}
token:${{ secrets.PAT }}
```
```
@ -200,14 +200,14 @@ How to use SSH (deploy keys) with create-pull-request action:
```yml
```yml
steps:
steps:
- uses:actions/checkout@v3
- uses:actions/checkout@v4
with:
with:
ssh-key:${{ secrets.SSH_PRIVATE_KEY }}
ssh-key:${{ secrets.SSH_PRIVATE_KEY }}
# Make changes to pull request here
# Make changes to pull request here
- name:Create Pull Request
- name:Create Pull Request
uses:peter-evans/create-pull-request@v5
uses:peter-evans/create-pull-request@v6
```
```
### Push pull request branches to a fork
### Push pull request branches to a fork
@ -226,11 +226,11 @@ Note that if you choose to use this method (not give the machine account `write`
6. As shown in the following example workflow, set the `push-to-fork` input to the full repository name of the fork.
6. As shown in the following example workflow, set the `push-to-fork` input to the full repository name of the fork.
```yaml
```yaml
- uses:actions/checkout@v3
- uses:actions/checkout@v4
# Make changes to pull request here
# Make changes to pull request here
- uses:peter-evans/create-pull-request@v5
- uses:peter-evans/create-pull-request@v6
with:
with:
token:${{ secrets.MACHINE_USER_PAT }}
token:${{ secrets.MACHINE_USER_PAT }}
push-to-fork:machine-user/fork-of-repository
push-to-fork:machine-user/fork-of-repository
@ -264,7 +264,7 @@ GitHub App generated tokens are more secure than using a PAT because GitHub App
```yaml
```yaml
steps:
steps:
- uses:actions/checkout@v3
- uses:actions/checkout@v4
- uses:tibdex/github-app-token@v1
- uses:tibdex/github-app-token@v1
id:generate-token
id:generate-token
@ -275,7 +275,7 @@ GitHub App generated tokens are more secure than using a PAT because GitHub App
# Make changes to pull request here
# Make changes to pull request here
- name:Create Pull Request
- name:Create Pull Request
uses:peter-evans/create-pull-request@v5
uses:peter-evans/create-pull-request@v6
with:
with:
token:${{ steps.generate-token.outputs.token }}
token:${{ steps.generate-token.outputs.token }}
```
```
@ -304,19 +304,19 @@ The action can use GPG to sign commits with a GPG key that you generate yourself
- The default values for `author` and `committer` have changed. See "What's new" below for details. If you are overriding the default values you will not be affected by this change.
- On completion, the action now removes the temporary git remote configuration it adds when using `push-to-fork`. This should not affect you unless you were using the temporary configuration for some other purpose after the action completes.
### What's new
- Updated runtime to Node.js 20
- The action now requires a minimum version of [v2.308.0](https://github.com/actions/runner/releases/tag/v2.308.0) for the Actions runner. Update self-hosted runners to v2.308.0 or later to ensure compatibility.
- The default value for `author` has been changed to `${{ github.actor }} <${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com>`. The change adds the `${{ github.actor_id }}+` prefix to the email address to align with GitHub's standard format for the author email address.
- The default value for `committer` has been changed to `github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>`. This is to align with the default GitHub Actions bot user account.
- Adds input `git-token`, the [Personal Access Token (PAT)](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) that the action will use for git operations. This input defaults to the value of `token`. Use this input if you would like the action to use a different token for git operations than the one used for the GitHub API.
-`push-to-fork` now supports pushing to sibling repositories in the same network.
- Previously, when using `push-to-fork`, the action did not remove temporary git remote configuration it adds during execution. This has been fixed and the configuration is now removed when the action completes.
- If the pull request body is truncated due to exceeding the maximum length, the action will now suffix the body with the message "...*[Pull request body truncated]*" to indicate that the body has been truncated.
- The action now uses `--unshallow` only when necessary, rather than as a default argument of `git fetch`. This should improve performance, particularly for large git repositories with extensive commit history.
- The action can now be executed on one GitHub server and create pull requests on a *different* GitHub server. Server products include GitHub hosted (github.com), GitHub Enterprise Server (GHES), and GitHub Enterprise Cloud (GHEC). For example, the action can be executed on GitHub hosted and create pull requests on a GHES or GHEC instance.
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.