Create Pull Request

一个 GitHub Action，用于为 actions 工作区中对仓库的更改创建拉取请求。

Actions 工作区中对仓库的更改会在工作流的各个步骤之间保持。 此 Action 旨在与其他修改或向仓库添加文件的步骤结合使用。 更改将自动提交到新分支，并创建拉取请求。

Create Pull Request Action 将执行以下操作：

1. 检查 Actions 工作区中的仓库更改。包括：
   • 未跟踪（新）文件
   • 已跟踪（已修改）文件
   • 工作流运行期间已提交但未推送的提交
2. 将所有更改提交到新分支，或更新现有拉取请求分支。
3. 创建或更新拉取请求，以将该分支合并到基准分支——即工作流中检出的分支。

文档

• 概念、指南和高级用法
• 示例
• 版本间更新
• 常见问题

用法

      - uses: actions/checkout@v6

      # Make changes to pull request here

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v8

你也可以固定到特定版本，格式为 @v8.x.x，具体可查看特定发布版本。

工作流权限

要使此 action 正常工作，你必须明确允许 GitHub Actions 创建拉取请求。 此设置可在仓库设置的“Actions > 常规 > 工作流权限”中找到。

对于组织所属的仓库，管理员可在组织设置的“Actions > 常规 > 工作流权限”中管理此设置。

Action 输入参数

所有输入参数均为可选。若未设置，将使用合理的默认值。

名称	描述	默认值
token	用于创建和更新拉取请求的令牌。详见 token。	GITHUB_TOKEN
branch-token	用于创建和更新分支的令牌。详见 branch-token。	默认与 token 值相同
path	GITHUB_WORKSPACE 下仓库的相对路径。	GITHUB_WORKSPACE
add-paths	要提交的文件路径列表，以逗号或换行符分隔。路径应遵循 git 的 pathspec 语法。详见 添加特定路径。	若未指定路径，则添加所有新增和修改的文件。
commit-message	提交更改时使用的消息。详见 commit-message。	[create-pull-request] automated change
committer	提交者的姓名和电子邮件地址，格式为 显示名称 <email@address.com>。在 github.com 上默认为 GitHub Actions 机器人用户。	github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
author	作者的姓名和电子邮件地址，格式为 显示名称 <email@address.com>。默认为触发工作流运行的用户。	${{ github.actor }} <${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com>
signoff	在提交日志消息末尾添加由提交者署名的 Signed-off-by 行。	false
branch	拉取请求的分支名称。	create-pull-request/patch
delete-branch	若 branch 没有关联的活动拉取请求，则删除该分支。详见 delete-branch。	false
branch-suffix	使用替代分支策略时的分支后缀类型。有效值为 random、timestamp 和 short-commit-hash。详情请见 替代策略。
base	设置拉取请求的基准分支。	默认为工作流中检出的分支。
push-to-fork	检出的父仓库的一个分支，拉取请求分支将推送到此分支。例如 owner/repo-fork。拉取请求将创建为将分支的分支合并到父仓库的基准分支。详情请见 将拉取请求分支推送到分支。
sign-commits	使用 GITHUB_TOKEN 时，以 github-actions[bot] 身份签名提交；使用 GitHub App 令牌 时，以你自己的机器人身份签名提交。详情请见 提交签名。	false
title	拉取请求的标题。	Changes by create-pull-request action
body	拉取请求的正文内容。	Automated changes by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub action
body-path	包含拉取请求正文内容的文件路径。优先级高于 body。
labels	标签列表，以逗号或换行符分隔。
assignees	被分配人（GitHub 用户名）列表，以逗号或换行符分隔。
reviewers	请求审查的审查者（GitHub 用户名）列表，以逗号或换行符分隔。
team-reviewers	请求审查的 GitHub 团队列表，以逗号或换行符分隔。注意，需要具有 repo 作用域的 PAT 或等效的 GitHub App 权限。
milestone	要关联到此拉取请求的里程碑编号。
draft	创建草稿拉取请求。有效值为 true（仅创建时）、always-true（创建和更新时）和 false。	false
maintainer-can-modify	指示维护者是否可以修改拉取请求。	true

token

token 输入参数默认为仓库的 GITHUB_TOKEN。

其他令牌选项：

• 具有 repo 作用域的经典个人访问令牌 (PAT)。
• 具有 contents: write 和 pull-requests: write 作用域的细粒度个人访问令牌 (PAT)。
• 具有 contents: write 和 pull-requests: write 作用域的GitHub App 令牌。

branch-token

此 action 首先创建一个分支，然后为该分支创建拉取请求。 在某些罕见的用例中，为这些操作使用不同的令牌可能会很有用，甚至是必要的。 除非你确定需要，否则不建议使用此输入参数。

commit-message

除消息外，commit-message 输入参数还可用于填充提交说明。在消息和说明之间保留一个空行。

          commit-message: |
            the first line is the commit message

            the commit description starts
            after a blank line and can be
            multiple lines

delete-branch

delete-branch 功能不会在合并时立即删除分支。（这是无法实现的，因为这需要合并以某种方式触发该操作。）

此功能的目的是，当操作下次运行时，如果没有差异，它将删除 branch。

启用此功能会导致以下行为：

1. 如果拉取请求已合并且分支未被删除，当操作下次运行时，如果没有进一步的差异，它将删除该分支。
2. 如果拉取请求处于打开状态，但现在不再有差异且该 PR 已无必要，操作将删除该分支，导致 PR 关闭。

如果希望在合并时立即删除分支，应在仓库设置中使用 GitHub 的“自动删除头部分支”功能。

Proxy support

对于位于企业代理后的自托管运行器，请设置 https_proxy 环境变量。

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v8
        env:
          https_proxy: http://<proxy_address>:<port>

操作输出

后续工作流步骤可使用以下输出。

• pull-request-number - 拉取请求编号。
• pull-request-url - 拉取请求的 URL。
• pull-request-operation - 操作执行的拉取请求操作，created（已创建）、updated（已更新）、closed（已关闭）或 none（无）。
• pull-request-head-sha - 拉取请求分支的提交 SHA。
• pull-request-branch - 拉取请求的分支名称。
• pull-request-commits-verified - GitHub 是否认为分支提交的签名已验证；true（是）或 false（否）。

步骤输出可按以下示例进行访问。 请注意，若要读取步骤输出，操作步骤必须具有 id。

      - name: Create Pull Request
        id: cpr
        uses: peter-evans/create-pull-request@v8
      - name: Check outputs
        if: ${{ steps.cpr.outputs.pull-request-number }}
        run: |
          echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"
          echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}"

操作行为

该操作的默认行为是创建一个拉取请求，该请求将持续更新新的更改，直到被合并或关闭。 更改会提交并推送到一个固定名称的分支，该分支的名称可通过 branch 输入参数进行配置。 任何后续更改都将提交到同一个分支，并反映在打开的拉取请求中。

操作的具体行为如下：

• 如果存在更改（即与检出的基准分支存在差异），更改将被推送到新的 branch 分支，并创建一个拉取请求。
• 如果不存在更改（即与检出的基准分支没有差异），则不会创建拉取请求，操作将静默退出。
• 如果拉取请求已存在，必要时将对其进行更新。Actions 工作区中的本地更改或基准分支上的更改都可能导致更新。如果不需要更新，操作将静默退出。
• 如果拉取请求存在，且基准分支上的新更改使得该拉取请求变得不必要（即拉取请求分支与基准分支之间不再存在差异），则该拉取请求将被自动关闭。此外，如果 delete-branch 设置为 true，则 branch 分支将被删除。

有关操作工作原理和使用指南的更多详细信息，请参阅 概念、指南和高级用法。

替代策略 - 始终创建新的拉取请求分支

在某些使用场景下，可能希望每次有要提交的更改时都创建一个新的唯一分支。 此策略不推荐，因为如果使用不当，可能会导致不必要地创建多个拉取请求。如果有疑问，请使用创建和更新固定名称分支的默认策略。

要使用此策略，请将输入参数 branch-suffix 设置为以下选项之一。

• random - 提交将被推送到一个后缀为随机字母数字字符串的分支。例如：create-pull-request/patch-6qj97jr、create-pull-request/patch-5jrjhvd

• timestamp - 提交将被推送到一个后缀为时间戳的分支。例如：create-pull-request/patch-1569322532、create-pull-request/patch-1569322552

• short-commit-hash - 提交将被推送到一个后缀为简短 SHA1 提交哈希的分支。例如：create-pull-request/patch-fcdfb59、create-pull-request/patch-394710b

控制提交文件

该操作默认会添加所有新增和修改的文件。 如果某些文件不应包含在拉取请求中，您可以使用以下方法来控制提交内容。

删除文件

处理不需要的文件最直接的方法是在该操作运行前的步骤中将其删除。

      - run: |
          rm -rf temp-dir
          rm temp-file.txt

忽略文件

如果存在您想要忽略的文件或目录，只需将它们添加到仓库根目录下的 .gitignore 文件中即可。本 action 会遵循该文件的配置。

添加特定路径

您可以通过 add-paths 输入参数控制要提交的文件。 路径应遵循 git 的 pathspec 语法。 与这些路径均不匹配的文件更改将会被暂存，并在 action 完成后恢复。

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v8
        with:
          add-paths: |
            *.java
            docs/*.md

创建您自己的提交

除了依靠该 action 处理未提交的更改外，您还可以在 action 运行前创建自己的提交。 请注意，仓库必须在带有远程的分支上检出，对于检出提交的事件，此操作将无法正常工作。

    steps:
      - uses: actions/checkout@v6
      - name: Create commits
        run: |
          git config user.name 'Peter Evans'
          git config user.email 'peter-evans@users.noreply.github.com'
          date +%s > report.txt
          git commit -am "Modify tracked file during workflow"
          date +%s > new-report.txt
          git add -A
          git commit -m "Add untracked file during workflow"
      - name: Uncommitted change
        run: date +%s > report.txt
      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v8

自动合并

可以在拉取请求上启用自动合并功能，使其在满足要求后自动合并。 有关使用详情，请参阅 enable-pull-request-automerge 操作。

参考示例

以下工作流设置了该操作的许多输入参数，供参考使用。 请查看 默认值，以避免不必要地设置输入参数。

有关更实际的使用场景，请参见 示例。

jobs:
  createPullRequest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Make changes to pull request
        run: date +%s > report.txt

      - name: Create Pull Request
        id: cpr
        uses: peter-evans/create-pull-request@v8
        with:
          token: ${{ secrets.PAT }}
          commit-message: Update report
          committer: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
          author: ${{ github.actor }} <${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com>
          signoff: false
          branch: example-patches
          delete-branch: true
          title: '[Example] Update report'
          body: |
            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
          assignees: peter-evans
          reviewers: peter-evans
          team-reviewers: |
            developers
            qa-team
          milestone: 1
          draft: false

基于上述参考配置的示例所创建的拉取请求如下所示：

许可证

MIT