Retrieving Current Branch and Commit Hash in GitHub Actions: Migration Strategies from Local Scripts to Cloud Workflows

Problem Context and Migration Challenges

In continuous integration and deployment (CI/CD) pipelines, generating Docker image tags that include branch and commit information is a common practice, such as using a format like master.ad959de. In local development environments, developers typically retrieve this data directly via Git commands:

git_branch=`git symbolic-ref --short HEAD`
git_hash=`git rev-parse --short HEAD`
docker_version=${git_branch}.${git_hash}

However, when migrating build scripts to GitHub Actions, executing these commands directly can lead to errors, such as fatal: ref HEAD is not a symbolic ref. This occurs because the workflow environment in GitHub Actions differs from the context of a local Git repository, particularly after using the actions/checkout action, where HEAD references may not have full symbolic ref properties.

Core Solution: Leveraging GitHub Environment Variables

GitHub Actions provides a set of predefined environment variables, with GITHUB_SHA and GITHUB_REF being key to addressing this issue. According to official documentation, GITHUB_SHA represents the commit SHA that triggered the workflow, while GITHUB_REF denotes the branch or tag ref that triggered it (e.g., refs/heads/feature-branch-1). By processing these variables, one can safely extract the required information.

The following code demonstrates how to obtain the short hash and branch name:

git_hash=$(git rev-parse --short "$GITHUB_SHA")
git_branch=${GITHUB_REF#refs/heads/}

Here, the git rev-parse --short "$GITHUB_SHA" command generates a short version based on the full commit hash, and ${GITHUB_REF#refs/heads/} uses Bash string manipulation to remove the refs/heads/ prefix, yielding a clean branch name. This approach avoids direct reliance on Git symbolic refs, ensuring stability in the GitHub Actions environment.

Advanced Implementation: Integration into Workflow Steps

To integrate this logic into a GitHub Actions workflow, one can use environment variables directly in run steps or pass parameters via scripts. For example, in a docker-build.sh script, the tag can be constructed as follows:

docker_version=${git_branch}.${git_hash}
docker build -t myimage:${docker_version} .

Alternatively, a more concise method is to combine variables directly in the workflow:

run: ./docker-build.sh "${GITHUB_REF#refs/heads/}.$(git rev-parse --short "$GITHUB_SHA")"

This eliminates the need for additional script steps, making the workflow more efficient. Note that if branch names contain special characters (e.g., slashes), further processing may be required to ensure Docker tag compatibility.

Alternative Approach: Using GitHub Context Expressions

Beyond environment variables, GitHub Actions supports retrieving similar information through context expressions. For instance, ${{ github.head_ref }} and ${{ github.sha }} can be used to pass branch and commit hash:

run: ./docker-build.sh ${{ github.head_ref }}.${{ github.sha }}

The advantage of this method is that it requires no additional command processing, completing everything within the workflow definition. However, note that github.sha provides the full hash rather than a short version, which may affect tag readability. Additionally, github.head_ref might be unavailable for certain event types (e.g., tag pushes), so it is advisable to check its applicability beforehand.

Environment Variable Persistence and Best Practices

For complex workflows, sharing branch and hash values across multiple steps may be necessary. This can be achieved by setting environment variables for persistence. For example:

run: |
  echo "sha_short=$(git rev-parse --short "$GITHUB_SHA")" >> "$GITHUB_ENV"
  echo "branch=${GITHUB_REF#refs/heads/}" >> "$GITHUB_ENV"

Subsequently, these values can be referenced in other steps using ${{ env.branch }} and ${{ env.sha_short }}. This enhances code maintainability and reusability, especially in multi-step build or testing scenarios.

In summary, when migrating to GitHub Actions, prioritize using GITHUB_SHA and GITHUB_REF environment variables over local Git commands to ensure cross-environment consistency. By combining Bash string manipulation and context expressions, one can build flexible and reliable tagging mechanisms, thereby optimizing CI/CD pipelines.