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

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 accepts several reference types. In 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:

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

To checkout a specific tag:

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

To checkout a specific commit SHA:

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

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

Implementation Details

The getRefSpec function in src/ref-helper.ts (lines 79-88) builds the Git fetch command from the resolved ref. The entry point in src/main.ts passes the resolved reference to 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 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 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.

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