How to Use actions/checkout with a Specific Ref in GitHub Actions

Set the ref input in your workflow step to target any branch, tag, or commit SHA instead of the default trigger ref.

By default, the actions/checkout repository retrieves the code that triggered the workflow run. To use actions/checkout with a specific ref—such as a feature branch, release tag, or historic commit—you must configure the ref input parameter in your workflow step. This parameter is defined in the action’s interface and processed by the underlying Git implementation.

Understanding the ref Input

The ref input accepts any Git reference that git checkout understands, including branch names, tags, full commit SHAs, or explicit references like refs/heads/main. According to the actions/checkout source code, the action passes this value to underlying Git commands (git fetch followed by git checkout) after normalization.

The input is declared in [action.yml](https://github.com/actions/checkout/blob/main/action.yml):

inputs:
  ref:
    description: |
      The branch, tag or SHA to checkout. When checking out the repository that
      triggered a workflow, this defaults to the reference or SHA for that event.
    required: false

If omitted, the action falls back to the reference that caused the run (e.g., the pull-request merge commit or the push SHA). The implementation that resolves and validates the value lives in [src/ref-helper.ts](https://github.com/actions/checkout/blob/main/src/ref-helper.ts), which ensures safe checkout operations before [src/main.ts](https://github.com/actions/checkout/blob/main/src/main.ts) orchestrates the actual repository setup.

Supported Reference Types

The ref parameter accepts several Git reference formats:

• Branch name: my-feature-branch
• Tag: v2.1.0
• Full SHA: a1b2c3d4e5f6… (40-character commit hash)
• Explicit full ref: refs/heads/main

Common Use Cases

Testing Feature Branches

Checkout a development branch to run CI against work-in-progress code without merging to main first.

Building from Release Tags

Create production artifacts from immutable tags to ensure reproducible builds.

Reproducing Historic Builds

Checkout an exact commit SHA to debug a regression or verify a specific state of the codebase.

Implementation Examples

Checkout a Named Branch

- uses: actions/checkout@v7
  with:
    ref: my-feature-branch

Checkout a Tag

- uses: actions/checkout@v7
  with:
    ref: v2.1.0

Checkout a Specific Commit SHA

When checking out a specific SHA, the action automatically adjusts fetch-depth if the commit is not on the default branch. However, you should set fetch-depth: 0 to fetch the entire history and guarantee the commit exists locally:

- uses: actions/checkout@v7
  with:
    ref: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
    fetch-depth: 0

Use Context Expressions

Reference dynamic values like pull request head commits:

- uses: actions/checkout@v7
  with:
    ref: ${{ github.event.pull_request.head.sha }}

Combine with Sparse Checkout

- uses: actions/checkout@v7
  with:
    ref: release-2023
    sparse-checkout: |
      src/
      README.md

Summary

• Set the ref input to checkout branches, tags, or commits other than the workflow trigger
• The action defaults to github.sha/github.ref when ref is omitted
• Implementation resides in src/ref-helper.ts with input definitions in action.yml
• Use fetch-depth: 0 when checking out specific SHAs to ensure availability
• Accepts full refs like refs/heads/main or short names like main

Frequently Asked Questions

What is the default value for the ref input in actions/checkout?

When omitted, the ref input defaults to the reference or SHA that triggered the workflow run (e.g., the pull request merge commit or push SHA). This fallback logic is implemented in src/ref-helper.ts according to the repository source code.

Can I checkout a specific commit SHA from history?

Yes. Pass the full 40-character SHA to the ref input. While the action attempts to adjust fetch-depth automatically for SHAs not on the default branch, you should set fetch-depth: 0 to ensure the commit is available, as shallow clones may exclude older commits.

How do I checkout the head commit of a pull request instead of the merge commit?

Use the expression ${{ github.event.pull_request.head.sha }} as the ref value. This checks out the actual PR head rather than the temporary merge commit GitHub creates for CI testing.

Does the ref parameter accept Git tags?

Yes. You can pass tag names directly (e.g., v2.1.0) to checkout that specific release. The action resolves tags through standard Git references as normalized by src/ref-helper.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}