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

> Learn to use actions/checkout to fetch a specific repository and ref. Set repository and ref inputs for precise code retrieval in your GitHub Actions workflows.

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

---

**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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/src/main.ts) parses workflow inputs using the definitions from [`action.yml`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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

```yaml
- 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

```yaml
- 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

```yaml
- 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`](https://github.com/actions/checkout/blob/main/src/main.ts), with Git operations handled by [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) and reference resolution in [`src/ref-helper.ts`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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.