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

> Learn how to use actions/checkout with a specific ref in GitHub Actions. Target any branch tag or commit SHA by setting the ref input in your workflow step.

- Repository: [GitHub Actions/checkout](https://github.com/actions/checkout)
- Tags: how-to-guide
- Published: 2026-07-17

---

**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`](https://github.com/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)](https://github.com/actions/checkout/blob/main/action.yml):

```yaml
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)](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)](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

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

```

### Checkout a Tag

```yaml
- 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:

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

```

### Use Context Expressions

Reference dynamic values like pull request head commits:

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

```

### Combine with Sparse Checkout

```yaml
- 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`](https://github.com/actions/checkout/blob/main/src/ref-helper.ts) with input definitions in [`action.yml`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/src/ref-helper.ts).