在 GitHub Actions 中获取 Commit SHA 的指南

1. 概述

GitHub Actions 是目前最流行的 CI/CD 自动化工具之一。它可以通过监听 GitHub 仓库中的特定事件（如 push、pull_request 等）来触发自动化流程。

在某些场景下，获取 commit SHA 是非常有用的，例如用于版本打标（tagging）、与 GitHub API 交互等。

在本教程中，我们将探讨在 GitHub Actions 中获取 Commit SHA 的不同方式。

---

2. Pull Request 中的 Merge Commit

在介绍如何获取 Commit SHA 之前，我们先来了解 Pull Request 中的 Merge Commit，这对理解不同场景下的 SHA 值非常关键。

当你发起一个 Pull Request 时，GitHub 会在后台生成一个内部的 Merge Commit，用以表示源分支与目标分支合并后的结果。这个 Commit 并不属于源分支或目标分支本身：

需要注意的是，这里涉及三个 SHA 值：

• 源分支头指针的 SHA
• 目标分支头指针的 SHA
• GitHub 自动生成的 Merge Commit 的 SHA

如果你的 Workflow 同时监听 pull_request 和 push 事件，那么会生成两个不同的 Workflow 运行实例：

对于 push 事件，通常你关心的是当前分支头指针的 Commit SHA；而对于 pull_request 事件，通常会使用 Merge Commit 的 SHA。

你也可以通过以下链接访问具体的 Commit 页面来验证：

https://github.com/[username]/[repository-name]/commit/[commit-sha]

---

3. 使用 github 上下文获取 Commit SHA

GitHub Actions 提供了一个内置的 github 上下文对象，其中包含了一些非常实用的字段，包括当前 Commit SHA。

3.1 push 事件

定义一个监听 push 事件的 Workflow：

$ cat .github/workflows/commit-sha-push.yml
name: Workflow to get commit sha in GitHub actions

on:
  push:

jobs:
  display-commit-sha:
    runs-on: ubuntu-latest
    steps:
      - name: commit SHA of the head of the branch
        run: echo "The commit SHA is ${{ github.sha }}"

✅ github.sha 会自动设置为当前分支头指针的 Commit SHA。

运行结果如下：

验证分支的 Commit 历史，可以看到值一致：

3.2 pull_request 事件

定义一个监听 pull_request 事件的 Workflow：

$ cat .github/workflows/commit-sha-pull-request.yml
name: Workflow to get commit sha in GitHub actions

on:
  pull_request:

jobs:
  display-commit-sha:
    runs-on: ubuntu-latest
    steps:
      - name: Get commit SHA of the merge commit
        run: echo "commit SHA:"  ${{ github.sha }}
      - name: Display Source and Target Commit SHA
        run: |
          echo "Source commit SHA: ${{ github.event.pull_request.head.sha }}"
          echo "Target commit SHA: ${{ github.event.pull_request.base.sha }}"

⚠️ 注意：在 pull_request 事件中，github.sha 表示的是 GitHub 自动生成的 Merge Commit 的 SHA。而源分支和目标分支的头 Commit SHA 可以通过 github.event 获取。

运行结果如下：

验证目标分支的历史：

查看 Merge Commit 页面：

---

4. 使用 git 命令获取 Commit SHA

除了使用 github 上下文，我们还可以通过 git 命令来获取 Commit SHA。

4.1 push 事件

$ cat .github/workflows/commit-sha-push-git-cmd.yml
name: Workflow to get commit sha in GitHub actions

on:
  push:

jobs:
    display-commit-sha:
        runs-on: ubuntu-latest
        steps:
        - uses: actions/checkout@v3

        - name: commit SHA of the head of the branch
          run: echo "The commit SHA is $(git rev-parse HEAD)"

✅ 使用 actions/checkout 拉取代码，然后通过 git rev-parse HEAD 获取当前 HEAD 指向的 Commit SHA。

运行结果如下：

验证 Commit 历史：

4.2 pull_request 事件

$ cat .github/workflows/commit-sha-pull-request-git-cmd.yml
name: Workflow to get commit sha in GitHub actions

on:
  pull_request:

jobs:
  display-commit-sha:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Get commit SHA
      run: |
        git fetch origin \
        +refs/pull/${{ github.event.pull_request.number }}/\*:refs/remotes/origin/pull/${{ github.event.pull_request.number }}/\* \
        +refs/heads/${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}
        echo "Merge commit SHA: $(git rev-parse origin/pull/${{ github.event.pull_request.number }}/merge)"
        echo "Source commit SHA: $(git rev-parse origin/pull/${{ github.event.pull_request.number }}/head)"
        echo "Target commit SHA: $(git rev-parse origin/${{ github.base_ref }})"

✅ 通过 git fetch 获取 Pull Request 相关引用，并使用 git rev-parse 获取三个 Commit SHA：

• Merge Commit
• Source Branch Commit
• Target Branch Commit

运行结果如下：

查看 Merge Commit 页面：

---

5. 总结

在本教程中，我们学习了在 GitHub Actions 中获取 Commit SHA 的两种主要方式：

• 使用 github 上下文直接获取（适用于简单场景）
• 使用 git 命令手动获取（更灵活，适用于复杂场景）

✅ 对于 push 事件，推荐使用 github.sha 或 git rev-parse HEAD。
✅ 对于 pull_request 事件，注意区分 Merge Commit 与源/目标分支的 Commit SHA。

合理使用这些方法，可以让你在 CI/CD 流程中更灵活地控制构建、部署与版本标记等操作。