<img width="24" height="24" src="https://yellow-cdn.veclightyear.com/835a84d5/4b09ec7f-3082-4a0e-b563-e25da8419dc3.svg"> 创建拉取请求

这是一个用于在 Actions 工作空间中为您的仓库变更创建拉取请求的 GitHub Action。

在工作流程中，对 Actions 工作空间中仓库的更改会在各步骤之间持续存在。这个 Action 旨在与其他修改或向您的仓库添加文件的步骤一起使用。这些更改将自动提交到一个新分支，并创建一个拉取请求。

创建拉取请求 Action 将：

检查 Actions 工作空间中的仓库变更。这包括：
- 未跟踪（新）文件
- 已跟踪（修改）文件
- 工作流程中尚未推送的提交
将所有更改提交到新分支，或更新现有的拉取请求分支。
创建一个拉取请求，将新分支合并到基础分支——即工作流程中检出的分支。

文档

使用方法

      - uses: actions/checkout@v4

      # 在此处对拉取请求进行更改

      - name: 创建拉取请求
        uses: peter-evans/create-pull-request@v6

您也可以固定到特定发布版本，格式为 @v6.x.x

工作流程权限

要使此 Action 正常工作，您必须明确允许 GitHub Actions 创建拉取请求。此设置可以在仓库设置中的 Actions > General > Workflow permissions 下找到。

对于属于组织的仓库，管理员可以在组织设置中的 Actions > General > Workflow permissions 下管理此设置。

Action 输入

所有输入都是可选的。如果未设置，将使用合理的默认值。

注意：如果您希望此 Action 创建的拉取请求触发 on: push 或 on: pull_request 工作流程，则不能使用默认的 GITHUB_TOKEN。请参阅此处的文档了解解决方法。

名称	描述	默认值
`token`	`GITHUB_TOKEN`（权限为 `contents: write` 和 `pull-requests: write`）或具有 `repo` 范围的个人访问令牌 (PAT)。	`GITHUB_TOKEN`
`git-token`	Action 将用于 git 操作的个人访问令牌 (PAT)。	默认为 `token` 的值
`path`	`GITHUB_WORKSPACE` 下仓库的相对路径。	`GITHUB_WORKSPACE`
`add-paths`	要提交的文件路径列表，以逗号或换行符分隔。路径应遵循 git 的 pathspec 语法。如果未指定路径，将添加所有新文件和修改的文件。参见添加特定路径。
`commit-message`	提交更改时使用的消息。参见 commit-message。	`[create-pull-request] automated change`
`committer`	提交者的名称和电子邮件地址，格式为 `Display Name <email@address.com>`。默认为 github.com 上的 GitHub Actions 机器人用户。	`github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>`
`author`	作者的名称和电子邮件地址，格式为 `Display Name <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`。拉取请求将被创建以将分支的分支合并到父分支的基础分支中。详见将拉取请求分支推送到分叉。
`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`	创建一个草稿拉取请求。创建后无法通过接口更改草稿状态，只能通过网页界面更改。	`false`

commit-message

除了消息外，commit-message 输入还可用于填充提交描述。在消息和描述之间留一个空行。

          commit-message: |
            第一行是提交消息

            提交描述从空行之后开始
            可以是多行的

delete-branch

delete-branch 功能不会在合并时立即删除分支。（它无法做到这一点，因为它需要合并以某种方式触发 Action。）该功能的目的是，当 Action 下一次运行时，如果没有差异，它将删除 branch。

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

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

如果您希望分支在合并后立即删除，那么应该使用 GitHub 的"自动删除头部分支"功能，该功能位于您的仓库设置中。

代理支持

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

      - name: 创建拉取请求
        uses: peter-evans/create-pull-request@v6
        env:
          https_proxy: http://<proxy_address>:<port>

Action 输出

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

pull-request-number - 拉取请求编号。
pull-request-url - 拉取请求的 URL。
pull-request-operation - Action 执行的拉取请求操作，created、updated 或 closed。
pull-request-head-sha - 拉取请求分支的提交 SHA。
pull-request-branch - 拉取请求的分支名称。

步骤输出可以按照以下示例访问。注意，为了读取步骤输出，Action 步骤必须有一个 id。

      - name: 创建拉取请求
        id: cpr
        uses: peter-evans/create-pull-request@v6
      - name: 检查输出
        if: ${{ steps.cpr.outputs.pull-request-number }}
        run: |
          echo "拉取请求编号 - ${{ steps.cpr.outputs.pull-request-number }}"
          echo "拉取请求 URL - ${{ steps.cpr.outputs.pull-request-url }}"

Action 行为

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

Action 的行为方式：

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

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

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

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

要使用此策略，请使用以下选项之一设置输入 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 文件中。该操作会遵循这个文件。

添加特定路径

你可以通过 add-paths 输入来控制哪些文件被提交。路径应遵循 git 的 pathspec 语法。不匹配任一路径的文件更改将被暂存，并在操作完成后恢复。

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

创建自己的提交

除了依赖该操作处理未提交的更改外，你还可以在操作运行前创建自己的提交。注意，仓库必须在有远程分支的情况下检出，对于检出提交的事件则无法使用。

    steps:
      - uses: actions/checkout@v4
      - 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@v6

创建项目卡片

要为拉取请求创建项目卡片，将 pull-request-number 步骤输出传递给 create-or-update-project-card 操作。

      - name: Create Pull Request
        id: cpr
        uses: peter-evans/create-pull-request@v6

      - name: Create or Update Project Card
        if: ${{ steps.cpr.outputs.pull-request-number }}
        uses: peter-evans/create-or-update-project-card@v2
        with:
          project-name: My project
          column-name: My column
          issue-number: ${{ steps.cpr.outputs.pull-request-number }}

自动合并

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

参考示例

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

有关更实际的用例，请参阅示例。

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

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

      - name: Create Pull Request
        id: cpr
        uses: peter-evans/create-pull-request@v6
        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