How to Checkout a Specific Commit with actions/checkout

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. 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 reads the ref input (documented in 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 at lines 36-38).

Complete Workflow Examples

Checkout a specific commit with full history:

- 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):

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

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

- 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, 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 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 (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.

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