# How to Use actions/checkout to Checkout a Specific Branch or Tag

> Learn how to checkout a specific branch or tag with actions/checkout. Simply set the ref input to your desired branch name or tag for precise version control in your GitHub Actions.

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

---

**Yes, actions/checkout can checkout a specific branch or tag by setting the `ref` input to the branch name, tag name, or commit SHA.**

The `actions/checkout` GitHub Action is the standard way to clone repositories in CI/CD workflows. You can checkout a specific branch or tag by configuring the `ref` input, which the action resolves internally before executing Git commands according to the `actions/checkout` source code.

## Using the ref Input to Checkout a Specific Branch or Tag

The `ref` input defined in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) accepts several reference types. In [`src/ref-helper.ts`](https://github.com/actions/checkout/blob/main/src/ref-helper.ts), the `getCheckoutInfo` function processes this input to determine the exact Git object to checkout.

### Branch Names

When you provide a branch name like `feature-xyz`, the `getCheckoutInfo` function (lines 52-57) calls `git.branchExists` to verify the branch exists on the remote. If found, it sets the `startPoint` to `refs/remotes/origin/<branch>` and checks out the branch tip.

### Tag Names

For tag names such as `v2.3.0`, the same function (lines 57-59) invokes `git.tagExists` to locate the tag on the remote. Upon confirmation, it sets the internal `ref` value to `refs/tags/<tag>` before checkout.

### Full Refs and Commit SHAs

The action also accepts full ref names (e.g., `refs/heads/main`, `refs/tags/v1.0.0`, `refs/pull/42/merge`) and processes them according to their prefix (`REFS/HEADS/`, `REFS/TAGS/`, `REFS/PULL/`). If you provide a 40- or 64-character commit SHA, the function returns it unchanged (lines 29-33), allowing the action to checkout that exact commit.

## Practical Workflow Examples

To checkout a specific branch:

```yaml
- name: Checkout feature branch
  uses: actions/checkout@v4
  with:
    ref: feature-xyz

```

To checkout a specific tag:

```yaml
- name: Checkout a release tag
  uses: actions/checkout@v4
  with:
    ref: v2.3.0

```

To checkout a specific commit SHA:

```yaml
- name: Checkout specific commit
  uses: actions/checkout@v4
  with:
    ref: 8a5f3c9b5e6d7e9a1b2c3d4e5f6a7b8c9d0e1f2g

```

## Fetching Complete History

To ensure all history is available for a tag or branch (for example, to run `git log`), set `fetch-depth: 0` and `fetch-tags: true`:

```yaml
- name: Checkout with full history
  uses: actions/checkout@v4
  with:
    ref: v2.3.0
    fetch-depth: 0
    fetch-tags: true

```

When `fetch-tags` is enabled, the action automatically appends `+refs/tags/*:refs/tags/*` to the ref spec (line 91 in [`src/ref-helper.ts`](https://github.com/actions/checkout/blob/main/src/ref-helper.ts)).

## Implementation Details

The `getRefSpec` function in [`src/ref-helper.ts`](https://github.com/actions/checkout/blob/main/src/ref-helper.ts) (lines 79-88) builds the Git fetch command from the resolved ref. The entry point in [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts) passes the resolved reference to [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts), which executes the actual `git fetch` and `git checkout` commands using the generated ref spec.

## Summary

- Set the `ref` input to checkout a specific branch, tag, or commit SHA with actions/checkout.
- The `getCheckoutInfo` function in [`src/ref-helper.ts`](https://github.com/actions/checkout/blob/main/src/ref-helper.ts) handles branch lookups (lines 52-57), tag lookups (lines 57-59), and direct SHA references (lines 29-33).
- Use `fetch-depth: 0` and `fetch-tags: true` when you need complete history or all tags.
- Full ref names like `refs/pull/42/merge` are supported for advanced use cases.

## Frequently Asked Questions

### Can actions/checkout checkout a tag instead of a branch?

Yes. Set the `ref` input to the tag name (e.g., `v2.3.0`). The `getCheckoutInfo` function in [`src/ref-helper.ts`](https://github.com/actions/checkout/blob/main/src/ref-helper.ts) detects the tag using `git.tagExists` and checks out `refs/tags/<tag>` accordingly.

### How do I checkout a pull request merge commit?

Pass the full ref name to the `ref` input: `refs/pull/42/merge`. The `getCheckoutInfo` function recognizes the `REFS/PULL/` prefix and uses the supplied ref directly without additional lookup.

### What is the difference between the ref and commit inputs?

The `ref` input accepts branch names, tag names, or commit SHAs and is the primary way to specify what to checkout. If `ref` is empty and the `commit` input is provided, the action uses the SHA directly (lines 29-33). However, `ref` is the recommended input for all reference types.

### Do I need to set fetch-tags when checking out a tag?

Not necessarily for the checkout itself, but set `fetch-tags: true` if you need the tag metadata or intend to run Git commands that reference other tags. The action automatically adds the tag ref-spec `+refs/tags/*:refs/tags/*` when this option is enabled.