git-auto-commit 操作

针对80%使用场景的 GitHub 文件提交操作。

这是一个 GitHub 操作，用于在工作流运行期间检测更改的文件，并将它们提交并推送回 GitHub 仓库。默认情况下，提交以"GitHub Actions"的名义进行，并由最后一次提交的用户共同署名。

如果你想了解更多关于这个操作在底层如何工作的信息，可以查看 Michael Heap 的这篇文章。

使用方法

将 git-auto-commit 添加到你的工作流中只需要几行代码。

将默认 GITHUB_TOKEN 的 contents 权限设置为 true。（推送新提交到仓库所必需）
在你的作业结束时，在可能添加或更改文件的其他步骤之后，添加以下步骤。

- uses: stefanzweifel/git-auto-commit-action@v5

你的工作流应该类似于这个例子。

name: Format

on: push

jobs:
  format-code:
    runs-on: ubuntu-latest

    permissions:
      # 给予默认的 GITHUB_TOKEN 写入权限，以提交和推送
      # 添加或更改的文件到仓库。
      contents: write

    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.head_ref }}

      # 在这里添加其他更改仓库文件的步骤
      # …

      # 将所有更改的文件提交回仓库
      - uses: stefanzweifel/git-auto-commit-action@v5

[!注意] 该操作必须在运行在类 UNIX 系统（如 ubuntu-latest）的作业中使用。

以下是包含所有可用选项的扩展示例。

- uses: stefanzweifel/git-auto-commit-action@v5
  with:
    # 可选。为创建的提交设置提交信息。
    # 默认为 "Apply automatic changes"
    commit_message: 自动更改

    # 可选。要推送提交的本地和远程分支名称。
    # 默认为当前分支。
    # 如果分支不存在，你可能需要设置 `create_branch: true`。
    branch: feature-123

    # 可选。`git-commit` 使用的选项。
    # 参见 https://git-scm.com/docs/git-commit#_options
    commit_options: '--no-verify --signoff'

    # 可选。应该添加到提交的文件的 glob 模式
    # 默认为全部 (.)
    # 参见 git 的 `pathspec` 文档
    # - https://git-scm.com/docs/git-add#Documentation/git-add.txt-ltpathspecgt82308203
    # - https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefpathspecapathspec
    file_pattern: '*.php src/*.js tests/*.js'

    # 可选。仓库的本地文件路径。
    # 默认为仓库的根目录。
    repository: .

    # 可选的提交用户和作者设置
    commit_user_name: My GitHub Actions Bot # 默认为 "github-actions[bot]"
    commit_user_email: my-github-actions-bot@example.org # 默认为 "41898282+github-actions[bot]@users.noreply.github.com"
    commit_author: Author <actions@github.com> # 默认为 "username <username@users.noreply.github.com>"，其中 "username" 属于触发运行的提交作者

    # 可选。在本地仓库创建并推送到远程仓库和指定分支的标签名。
    tagging_message: 'v1.0.0'

    # 可选。`git-status` 用于确定仓库是否有更改的选项。
    # 参见 https://git-scm.com/docs/git-status#_options
    status_options: '--untracked-files=no'

    # 可选。`git-add` 使用的选项。
    # 参见 https://git-scm.com/docs/git-add#_options
    add_options: '-u'

    # 可选。`git-push` 使用的选项。
    # 参见 https://git-scm.com/docs/git-push#_options
    push_options: '--force'
    
    # 可选。禁用更改检查，始终尝试创建提交并推送
    skip_dirty_check: true    
    
    # 可选。跳过内部的 `git fetch` 调用
    skip_fetch: true    
    
    # 可选。跳过内部的 `git checkout` 调用
    skip_checkout: true

    # 可选。防止 shell 展开文件名。 
    # 详情：https://www.gnu.org/software/bash/manual/html_node/Filename-Expansion.html
    disable_globbing: true

    # 可选。在本地和远程仓库中创建给定的分支名。
    create_branch: true

请注意，该操作依赖于 bash。如果你在作业中与自定义 Docker 容器结合使用该操作，请确保已安装 bash。

工作流示例

在这个例子中，我们在一个 PHP 项目中运行 php-cs-fixer 来自动修复代码风格，然后将可能更改的文件提交回仓库。

注意，我们在 checkout 操作中明确指定了 ${{ github.head_ref }}。这是为了与 pull_request 事件（或任何其他非 push 事件）一起工作所必需的。

name: php-cs-fixer

on:
  pull_request:
  push:
    branches:
      - main
jobs:
  php-cs-fixer:
    runs-on: ubuntu-latest

    permissions:
      # 授予默认的 GITHUB_TOKEN 写入权限，以便将更改的文件提交并推送回仓库。
      contents: write

    steps:
    - uses: actions/checkout@v4
      with:
        ref: ${{ github.head_ref }}

    - name: 运行 php-cs-fixer
      uses: docker://oskarstark/php-cs-fixer-ga

    - uses: stefanzweifel/git-auto-commit-action@v5
      with:
        commit_message: 应用 php-cs-fixer 更改

## 输入参数

查看 [`action.yml`](https://github.com/stefanzweifel/git-auto-commit-action/blob/master/action.yml) 获取完整的支持输入参数列表。

## 输出结果

您可以使用这些输出来根据 `git-auto-commit-action` 的结果触发工作流程中的其他操作。

- `changes_detected`：如果仓库有变更且文件已更改，则返回 "true"，否则返回 "false"。
- `commit_hash`：如果创建了提交，则返回完整的提交哈希值。

**⚠️ 使用输出时，步骤需要指定一个 id。请参见下面的示例。**

### 示例

```yaml
  - uses: stefanzweifel/git-auto-commit-action@v5
    id: auto-commit-action #输出显示在 ${{ steps }} 中必需的
    with:
      commit_message: 应用 php-cs-fixer 更改

  - name: "如果检测到变更则运行"
    if: steps.auto-commit-action.outputs.changes_detected == 'true'
    run: echo "有变更！"

  - name: "如果未检测到变更则运行"
    if: steps.auto-commit-action.outputs.changes_detected == 'false'
    run: echo "无变更！"

限制与注意事项

此 Action 的目标是"满足 80% 用例的提交文件 Action"。因此，如果您的工作流程属于不支持的 20% 部分，可能会遇到问题。

以下是 Action 已知不支持的边缘情况列表：

当仓库与远程不同步时不执行 git pull。 该 Action 在执行 git push 之前不会执行 git pull。您负责在工作流程运行中保持仓库的最新状态。

不支持在构建矩阵中运行 Action。如果您的工作流程使用构建矩阵，并且希望每个作业都提交并推送文件到远程，您将遇到工作流程中的仓库变得过时的问题。由于 Action 不会为您执行 git pull，您必须自己执行。

不支持 git rebase 或 git merge。有许多将远程上游更改整合到本地仓库的策略。git-auto-commit 不想负责执行这些操作。

不支持检测 CR（回车）和 LF（换行）之间的换行符更改。这是一个低级问题，您必须在项目中以其他方式解决。抱歉。

如果此 Action 不适用于您的工作流程，请查看 EndBug/add-and-commit。

检出正确的分支

您必须使用 action/checkout@v2 或更高版本来检出仓库。在非 push 事件（如 pull_request）中，请确保指定要检出的 ref：

- uses: actions/checkout@v4
  with:
    ref: ${{ github.head_ref }}

这样做是为了避免以分离状态检出仓库。

此 Action 创建的提交不会触发新的工作流程运行

由此产生的提交不会触发另一个 GitHub Actions 工作流程运行。这是由于 GitHub 设置的限制。

当您使用仓库的 GITHUB_TOKEN 代表 GitHub Actions 应用执行任务时，由 GITHUB_TOKEN 触发的事件不会创建新的工作流程运行。这可以防止您意外创建递归的工作流程运行。

您可以通过创建新的个人访问令牌 (PAT)，将令牌作为密钥存储在您的仓库中，然后将新令牌传递给 actions/checkout Action 步骤来更改此行为。

- uses: actions/checkout@v4
  with:
    token: ${{ secrets.PAT }}

如果您创建个人访问令牌，请应用 repo 和 workflow 范围。

如果您在组织中工作，不想从个人账户创建 PAT，我们建议使用机器人账户来生成令牌。

使用个人访问令牌时防止无限循环

如果您使用个人访问令牌 (PAT) 将提交推送到 GitHub 仓库，生成的提交或推送可能会触发其他 GitHub Actions 工作流程。这可能导致无限循环。

如果您想防止这种情况，可以在提交消息中添加 skip-checks:true。有关详细信息，请参阅跳过工作流程运行。

未检测到文件更改

您的工作流程更改了文件，但 "git-auto-commit" 没有检测到更改吗？检查适用于相应文件的 .gitignore。您可能不小心将文件标记为被 git 忽略。

高级用法

多行提交消息

如果您的提交消息应跨多行，您必须创建一个单独的步骤来生成字符串。以下示例可作为生成多行提交消息的起点。在GitHub文档中了解更多关于GitHub Actions中多行字符串的工作原理。

    # 构建多行提交消息
    # 根据需要调整
    - run: echo "提交消息1" >> commitmessage.txt
    - run: echo "提交消息2" >> commitmessage.txt
    - run: echo "提交消息3" >> commitmessage.txt

    # 创建一个多行字符串，供git-auto-commit Action使用
    - name: 设置提交消息
      id: commit_message_step
      run: |
        echo 'commit_message<<EOF' >> $GITHUB_OUTPUT
        cat commitmessage.txt >> $GITHUB_OUTPUT
        echo 'EOF' >> $GITHUB_OUTPUT

    # 快速删除临时存储提交消息的文件
    - run: rm -rf commitmessage.txt

    - uses: stefanzweifel/git-auto-commit-action@v5
      id: commit
      with:
        commit_message: ${{ steps.commit_message_step.outputs.commit_message }}

签名提交

如果您想使用GPG密钥签名提交，您需要使用一个额外的action。您可以使用crazy-max/ghaction-import-gpg action并按照其设置说明进行操作。

由于git-auto-commit默认不使用您的用户名和邮箱创建提交，您必须在工作流中覆盖这些值。

- name: "导入GPG密钥"
  id: import-gpg
  uses: crazy-max/ghaction-import-gpg@v6
  with:
    gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
    passphrase: ${{ secrets.GPG_PASSPHRASE }}
    git_user_signingkey: true
    git_commit_gpgsign: true

- name: "提交并推送更改"
  uses: stefanzweifel/git-auto-commit-action@v5
  with:
     commit_author: "${{ steps.import-gpg.outputs.name }} <${{ steps.import-gpg.outputs.email }}>"
     commit_user_name: ${{ steps.import-gpg.outputs.name }}
     commit_user_email: ${{ steps.import-gpg.outputs.email }}

详情请参阅讨论#334。

在私有仓库的复刻中使用

默认情况下，GitHub Actions不会在私有仓库的复刻上运行工作流。要为私有仓库启用Actions，请在仓库设置中启用"从拉取请求运行工作流"。

详情请参阅GitHub的这则公告或GitHub文档。

在公共仓库的复刻中使用

[!注意] 从技术上讲，此Action可以与复刻一起使用。但请注意，触发器及其选项的组合可能会导致问题。请阅读文档了解GitHub Actions支持哪些触发器。
确保您的贡献者在打开拉取请求时启用"允许维护者编辑"。(了解更多)

如果您将此Action与代码检查/修复工具结合使用，在main分支上对push事件运行Action会更简单。

[!警告] 由于GitHub的限制，如果复刻位于组织下，此Action目前无法将提交推送到基础仓库。详情请参阅github/community#6634和此评论。

默认情况下，此Action不会在由复刻打开的拉取请求上运行。（这是GitHub的限制，而非我们的限制。）然而，有几种方法可以在应由复刻仓库触发的工作流中使用此Action。

工作流应在基础仓库中运行

[!注意] 以下部分解释了如何将git-auto-commit与pull_request_target触发器结合使用。在工作流中使用pull_request_target可能导致仓库被入侵，正如GitHub自己的安全团队所提到的。这意味着恶意行为者可能会泄露/窃取您的GitHub Actions仓库机密。使用pull_request_target时请注意这个风险。

如果您的工作流运行代码修复工具，请考虑通过监听push事件在默认分支上运行工作流，或使用第三方工具如autofix.ci。我们保留这份文档，因为多年来有很多关于如何将此action用于公共复刻的问题。

以下工作流在每次向main分支推送提交或发生拉取请求活动时运行，通过监听pull_request_target事件。如果工作流是由 pull_request_target 事件触发的，工作流将在拉取请求的基础分支上下文中运行，而不是像 pull_request 事件那样在合并提交的上下文中运行。换句话说，这将允许您的工作流在拉取请求打开的仓库中运行，并将更改推送回 fork。

查看 #211 中的讨论以获取更多相关信息。

name: 格式化 PHP

on:
  push:
    branches:
      - main
  pull_request_target:

jobs:
  php-cs-fixer:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
    - uses: actions/checkout@v4
      with:
        # 检出 fork/head 仓库并将更改推送到 fork。
        # 如果跳过此步骤，将检出基础仓库并将更改提交到基础仓库！
        repository: ${{ github.event.pull_request.head.repo.full_name }}

        # 检出 fork 中创建的分支。将自动将更改推送回此分支。
        ref: ${{ github.head_ref }}

    - name: 运行 php-cs-fixer
      uses: docker://oskarstark/php-cs-fixer-ga

    - uses: stefanzweifel/git-auto-commit-action@v5

有关在 fork 上运行 Actions 的更多信息，请参阅 GitHub 的这则公告。

使用 `--amend` 和 `--no-edit` 作为提交选项

如果您想使用此 Action 创建一个使用 --amend 和 --no-edit 的提交，您需要进行一些调整。

[!注意] 如果您修改已发布的提交，应该了解重写历史的影响。参见变基。

首先，您需要使用 git log -1 --pretty=%s 提取上一次提交消息。然后，您需要通过 commit_message 输入选项将这个最后的提交消息提供给 Action。

默认情况下，提交作者会更改为 username <username@users.noreply.github.com>，其中 username 是触发工作流的用户名（这里使用了 github.actor 上下文）。如果您想保留原作者的姓名和电子邮件，必须从最后一次提交中提取它们，并通过 commit_author 输入选项提供给 Action。

最后，您必须使用 push_options: '--force' 来覆盖 GitHub 远程仓库上的 git 历史。（git-auto-commit 不会为您执行 git-rebase！）

您工作流中的步骤可能如下所示：

- uses: actions/checkout@4
  with:
    # 获取最后 2 次提交而不是仅 1 次。（仅获取 1 次提交会覆盖整个历史）
    fetch-depth: 2

# 工作流中触发文件更改的其他步骤

- name: 获取最后一次提交消息
  id: last-commit
  run: |
    echo "message=$(git log -1 --pretty=%s)" >> $GITHUB_OUTPUT
    echo "author=$(git log -1 --pretty=\"%an <%ae>\")" >> $GITHUB_OUTPUT

- uses: stefanzweifel/git-auto-commit-action@v5
  with:
    commit_author: ${{ steps.last-commit.outputs.author }}
    commit_message: ${{ steps.last-commit.outputs.message }}
    commit_options: '--amend --no-edit'
    push_options: '--force'
    skip_fetch: true

有关详细信息，请参阅 #159 中的讨论。

故障排除

Action 无法将提交推送到仓库

确保检出正确的分支。

Action 无法将提交推送到仓库：认证问题

如果您的工作流由于认证问题无法将提交推送到仓库，请更新您的工作流配置和 actions/checkout 的使用方式。

将 token 值更新为个人访问令牌应该能解决您的问题。

git-auto-commit 无法推送在 `.github/workflows/` 中创建或更新文件的提交

GitHub Action 发放的默认 GITHUB_TOKEN 没有权限修改位于 .github/workflows/ 中的工作流文件。要解决这个问题，请创建一个个人访问令牌（PAT），并将该令牌传递给工作流中的 actions/checkout 步骤。（类似于如何推送到受保护分支）。

如果 PAT 对您不起作用，您也可以创建一个新的 GitHub 应用程序并在工作流中使用其令牌。详情请参见 #87 中的这条评论。

有关此主题的详细信息和讨论，请参见 #322。

推送到受保护分支

如果您的仓库使用了受保护分支，您需要对工作流程进行一些更改，以使操作正常工作：您需要一个个人访问令牌，并且要么允许强制推送，要么个人访问令牌需要属于管理员。

首先，您需要创建一个新的个人访问令牌（PAT），将令牌作为密钥存储在您的仓库中，并将新令牌传递给actions/checkout操作步骤。

- uses: actions/checkout@v4
  with:
    token: ${{ secrets.PAT }}

您可以在GitHub文档中了解更多关于个人访问令牌的信息。

[!提示] 如果您在一个组织中工作，并且不想从您的个人账户创建PAT，我们建议使用机器人账户来创建此类令牌。

如果您选择"强制推送"的方式，您需要启用对受保护分支的强制推送（参见文档），并更新您的工作流程以使用强制推送，如下所示。

    - uses: stefanzweifel/git-auto-commit-action@v5
      with:
        commit_message: 应用php-cs-fixer更改
        push_options: --force

此操作的提交不会触发新的工作流程

这是由于GitHub设置的限制，此操作所做的提交不会触发新的工作流程运行。

路径规范'x'未匹配任何文件

如果您使用自定义的file_pattern，并且操作抛出一个致命错误，错误信息为"路径规范'file-pattern'未匹配任何文件"，问题可能是仓库中不存在该模式的文件。

file_pattern在此操作中同时用于git-status和git-add。如果您使用类似*.js *.ts的文件模式，但项目仓库中不存在*.ts文件，git-add将抛出一个致命错误。

详情请参见问题#227。

自定义`file_pattern`，文件已更改但日志中显示"工作树干净。没有需要提交的内容。"

如果您使用自定义的file_pattern，并且操作未检测到工作流程中所做的更改，您可能遇到了通配符问题。

假设您使用file_pattern: '*.md'来检测和提交仓库中所有Markdown文件的更改。如果您的工作流程现在只更新子目录中的.md文件，但仓库根目录中有一个未更改的.md文件，git-auto-commit操作将在工作流程日志中显示"工作树干净。没有需要提交的内容。"

这是因为在将*.md通配符发送给git-status之前，它已被展开。git-status将收到仓库根目录中未更改的.md文件的文件名，并且不会检测到任何更改；因此操作不执行任何操作。

要解决此问题，请在工作流程中添加disable_globbing: true。

- uses: stefanzweifel/git-auto-commit-action@v5
  with:
    file_pattern: '*.md'
    disable_globbing: true

详情请参见问题#239。

运行测试

该操作使用bats编写了测试。在本地运行测试套件之前，您必须使用npm或yarn安装依赖项。

npm install
yarn

您可以使用npm或yarn运行测试套件。

npm run test
yarn test

版本控制

我们使用SemVer进行版本控制。有关可用版本，请参见此仓库的标签。

我们还提供主要版本标签，以便更容易使用某个主要版本的最新发布。例如，您可以使用stefanzweifel/git-auto-commit-action@v5来始终使用当前主要版本的最新发布。（更多关于此的信息在这里。）

鸣谢

这个操作受到了加拿大数字服务的auto-commit操作和Eric Johnson的这个commit操作的启发和改编。

许可证

本项目采用MIT许可证 - 有关详细信息，请参阅LICENSE文件。

git-auto-commit-action