# How to Checkout a Specific Commit with actions/checkout

> Learn how to checkout a specific commit with actions/checkout. Pass the commit SHA-1 hash to the ref input and set fetch-depth 0 for a reliable workflow.

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

---

**To checkout a specific commit with actions/checkout, pass the full SHA-1 hash to the `ref` input and set `fetch-depth: 0` to ensure the commit is available in the cloned repository history.**

The `actions/checkout` repository provides the official GitHub Action for cloning repositories into your workflow environment. When you need to checkout a specific commit rather than the default branch or triggering SHA, the action supports explicit commit targeting through its input parameters and ref resolution logic.

## How actions/checkout Resolves Commit References

The core logic for interpreting commit SHAs resides in **[`src/ref-helper.ts`](https://github.com/actions/checkout/blob/main/src/ref-helper.ts)**. The `getCheckoutInfo` function receives the user-provided `ref` input and the workflow's `$GITHUB_SHA`. When `ref` contains a full SHA-1 (or SHA-256) hash, the helper identifies it as a commit reference and returns it for direct checkout, as implemented at lines 29-33 of the source file.

The main entry point in **[`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts)** reads the `ref` input (documented in [`README.md`](https://github.com/actions/checkout/blob/main/README.md) at lines 69-73) and passes it to `getCheckoutInfo`. The helper then builds the appropriate ref-specs for the `git fetch` and `git checkout` commands, creating an `ICheckoutInfo` object that drives the remainder of the checkout process.

## Required Configuration for Specific Commits

### Specifying the Commit SHA with `ref`

The `ref` input accepts the full 40-character SHA-1 hash of the target commit. When this value is provided, the action treats it as a commit identifier rather than a branch or tag name, triggering the commit-specific logic in the ref helper.

### Ensuring Commit Availability with `fetch-depth`

By default, `actions/checkout` uses **`fetch-depth: 1`**, which only guarantees the presence of the commit that triggered the workflow. To checkout an arbitrary commit, you must increase the fetch depth so Git can locate the target SHA. Set `fetch-depth: 0` to fetch all history, or specify a sufficient depth to include your target commit (documented in [`README.md`](https://github.com/actions/checkout/blob/main/README.md) at lines 36-38).

## Complete Workflow Examples

Checkout a specific commit with full history:

```yaml
- uses: actions/checkout@v7
  with:
    # Replace with the exact SHA you want

    ref: 9fceb02d0ae9d1e2a2c6e13c3ba7b6d6c0e5a5b0
    # Fetch the full history so the commit can be found

    fetch-depth: 0

```

Checkout a commit with limited history (ensure depth includes the target):

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

```

Default behavior (requires no extra inputs when using the triggering commit):

```yaml
- uses: actions/checkout@v7
  # No extra inputs needed – the action uses $GITHUB_SHA automatically.

```

## Summary

- The **`ref`** input accepts a full commit SHA to checkout a specific commit with actions/checkout.
- The **`fetch-depth`** must be increased from the default `1` to include the target commit in the fetched history.
- Core logic lives in **[`src/ref-helper.ts`](https://github.com/actions/checkout/blob/main/src/ref-helper.ts)**, specifically the `getCheckoutInfo` function and ref-spec generation at lines 96-118.
- When checking out a commit, Git places the repository in a **detached HEAD** state.

## Frequently Asked Questions

### Do I need to set fetch-depth when checking out the current commit?

No. The default `fetch-depth: 1` is sufficient when checking out the commit that triggered the workflow, as this SHA is already fetched by the initial clone. You only need to adjust the fetch depth when targeting a different commit that is not the event's default SHA.

### Can I use a short SHA (7 characters) with the ref input?

No. While Git supports short SHAs locally, `actions/checkout` requires the full SHA-1 hash to uniquely identify the commit during the fetch and checkout process. The `getCheckoutInfo` function in [`src/ref-helper.ts`](https://github.com/actions/checkout/blob/main/src/ref-helper.ts) processes the complete hash to generate correct ref-specs.

### What happens if the commit is not in the fetched history?

The action will fail with a "reference not found" error. The ref-spec generation logic in [`src/ref-helper.ts`](https://github.com/actions/checkout/blob/main/src/ref-helper.ts) (lines 96-118) expects the commit to exist in the fetched repository history. If you encounter this error, increase `fetch-depth` or set it to `0` to fetch all history.

### Is the repository left in a detached HEAD state when checking out a commit?

Yes. When you checkout a specific commit using a SHA, Git places the repository in a detached HEAD state because the commit is not associated with any branch reference. This is the standard Git behavior for checking out arbitrary commits.