How to Use actions/checkout to Fetch a Specific Repository and Ref

To fetch a specific repository and ref with actions/checkout, set the repository input to the target owner/repo and the ref input to a branch name, tag, or commit SHA.

The actions/checkout action is the standard GitHub Actions utility for cloning repositories into your workflow's $GITHUB_WORKSPACE. By configuring the repository and ref inputs defined in action.yml, you can override the default behavior to pull code from external repositories or specific commit histories. This guide explains how to target precise code states using the official source implementation.

Understanding the Core Inputs

The action accepts two primary inputs that control the fetch target: repository and ref.

The Repository Input

By default, actions/checkout clones ${{ github.repository }}—the repository where the workflow is currently running. To fetch a different repository, provide the owner/repo string. This triggers the action to construct a remote URL targeting the external repository, as handled in src/url-helper.ts.

The Ref Input

The ref input accepts any valid Git reference: branch names, tags, or full commit SHAs. When unspecified, the action defaults to the reference or SHA that triggered the workflow run. Supplying a specific ref forces the checkout to that exact revision, with resolution logic implemented in src/ref-helper.ts.

Authentication and Remote Configuration

When fetching external or private repositories, you must provide credentials. The action supports two primary authentication methods defined in the source configuration:

• token: Accepts a GitHub Personal Access Token (PAT) or the default GITHUB_TOKEN. The action passes this to src/url-helper.ts to construct an authenticated HTTPS URL.
• ssh-key: Accepts a private SSH key for SSH-based cloning, bypassing HTTPS authentication entirely.

These credentials are essential when the repository input points to a private repo or when crossing organizational boundaries.

Source Code Architecture

The checkout logic is implemented across several TypeScript modules in the src/ directory.

Input Parsing and Orchestration

The entry point src/main.ts parses workflow inputs using the definitions from action.yml. It validates the repository and ref values, determines the authentication strategy, and delegates Git operations to the command manager.

Git Command Execution

The src/git-command-manager.ts file contains the low-level Git wrapper. It executes git clone, git fetch, and git checkout commands based on the inputs provided. This module handles advanced options like fetch-depth, submodules, and sparse-checkout configurations.

Reference Resolution

When you specify a ref, src/ref-helper.ts resolves the string into a concrete Git reference. It distinguishes between branch names, tags, and SHAs, ensuring the subsequent checkout command targets the correct Git object.

URL Construction

The src/url-helper.ts module builds the remote URL. If using a token, it injects the credential into the HTTPS URL for authenticated access. This module ensures the repository input translates into a valid Git remote endpoint for both GitHub.com and GitHub Enterprise Server.

Practical Configuration Examples

These YAML configurations demonstrate how to combine the repository and ref inputs for common scenarios.

Fetch a Private Repository at a Specific Branch

- name: Checkout tools repo
  uses: actions/checkout@v4
  with:
    repository: my-org/my-tools
    ref: feature/awesome-feature
    token: ${{ secrets.PAT }}
    path: tools

This example clones my-org/my-tools into a subdirectory named tools, checking out the feature/awesome-feature branch using a Personal Access Token for authentication.

Fetch a Public Repository at a Tag

- uses: actions/checkout@v4
  with:
    repository: octocat/Hello-World
    ref: v1.2.3
    fetch-depth: 0

Here, the action fetches the v1.2.3 tag from the public octocat/Hello-World repository. The fetch-depth: 0 parameter retrieves the full Git history.

Checkout a Specific Commit SHA

- uses: actions/checkout@v4
  with:
    ref: a1b2c3d4e5f6g7h8i9j0
    fetch-depth: 1

This configuration checks out an exact commit SHA from the current repository, fetching only that specific commit to minimize network overhead and storage.

Summary

• The repository input overrides the default ${{ github.repository }} to target external repositories using the owner/repo format.
• The ref input accepts branches, tags, or commit SHAs to pin the checkout to a specific revision.
• Authentication requires either a token for HTTPS or an ssh-key for SSH access when cloning private repos.
• The core logic resides in src/main.ts, with Git operations handled by src/git-command-manager.ts and reference resolution in src/ref-helper.ts.

Frequently Asked Questions

What is the default behavior if I don't specify repository or ref?

If omitted, the repository input defaults to the repository where the workflow is triggered (${{ github.repository }}), and ref defaults to the SHA or reference that triggered the workflow run. The action checks out the current repository at the trigger commit.

Can I use actions/checkout with GitHub Enterprise Server?

Yes, the action supports GitHub Enterprise Server. Provide the github-server-url input or ensure the GITHUB_SERVER_URL environment variable is set. The src/url-helper.ts module constructs the appropriate URL for Enterprise endpoints automatically.

How do I checkout a repository from a different organization?

Set the repository input to the full owner/repo path of the target repository. Ensure your token has read access to that organization. The action will clone the external repo into $GITHUB_WORKSPACE or the specified path subdirectory.

What is the difference between ref and fetch-depth?

The ref input specifies which Git reference to checkout (branch, tag, or SHA), while fetch-depth controls how much history to retrieve. A fetch-depth of 1 creates a shallow clone with only the latest commit, whereas 0 fetches all history. These inputs work independently—you can checkout a specific ref with minimal or full history.

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