# How to Checkout into a Custom Repository Location with actions/checkout

> Learn how to checkout into a custom repository location using actions/checkout's path input. Clone your repo into a subdirectory for organized GitHub Actions workflows.

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

---

**Use the `path` input in `actions/checkout` to clone the repository into a subdirectory of `$GITHUB_WORKSPACE` instead of the default root directory.**

The `actions/checkout` GitHub Action clones your repository into the workflow's workspace by default. When you need to organize multiple checkouts, isolate dependencies, or match a specific directory structure required by your build tools, the `path` input allows you to specify a custom repository location within the workspace.

## Using the `path` Input for Custom Checkouts

By default, `actions/checkout` places repository files directly in `$GITHUB_WORKSPACE`, overwriting any existing content. The `path` input overrides this behavior, directing the action to create a subdirectory and execute `git clone` within that target location.

According to the source code in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) (lines 55-57), the `path` input is defined as an optional string that specifies a "relative path under $GITHUB_WORKSPACE to place the repository." When provided, the action automatically creates the directory structure if it does not exist, ensuring subsequent workflow steps can access files at `$GITHUB_WORKSPACE/<your-path>`.

## Practical Examples for Common Scenarios

### Checkout into a Single Custom Directory

To checkout the current repository into a folder named `src` rather than the workspace root:

```yaml
- uses: actions/checkout@v7
  with:
    path: src

```

After this step completes, your repository files are available at `$GITHUB_WORKSPACE/src`, and your working directory for subsequent steps remains the workspace root unless changed.

### Checkout Multiple Repositories Side-by-Side

When you need to work with multiple repositories simultaneously, specify unique paths for each checkout:

```yaml
- name: Checkout main repo
  uses: actions/checkout@v7
  with:
    path: main

- name: Checkout tools repo
  uses: actions/checkout@v7
  with:
    repository: my-org/my-tools
    path: tools

```

This configuration places the main repository in `$GITHUB_WORKSPACE/main` and the tools repository in `$GITHUB_WORKSPACE/tools`, preventing file collisions and maintaining clean separation between projects.

### Nested Repository Checkouts

You can checkout a repository into a subdirectory of another checked-out repository:

```yaml
- uses: actions/checkout@v7
  with:
    path: project

- name: Checkout helper repo
  uses: actions/checkout@v7
  with:
    repository: my-org/helper
    path: project/helpers/helper-repo

```

The action creates the nested directory structure `project/helpers/helper-repo` and clones the helper repository there, making it available to the main project as a subdirectory.

### Private Repositories with Custom Paths

When checking out a private repository to a custom location, provide a personal access token (PAT) using the `token` input:

```yaml
- uses: actions/checkout@v7
  with:
    repository: my-org/private-repo
    token: ${{ secrets.PAT }}
    path: private

```

The `path` input works independently of authentication, allowing you to organize private dependencies alongside your main codebase.

## How the `path` Input Works Under the Hood

The implementation resides in the action's TypeScript source files (such as [`src/checkout.ts`](https://github.com/actions/checkout/blob/main/src/checkout.ts)). When processing the workflow, the action evaluates the `path` input and constructs the git clone command with an explicit target directory parameter.

As documented in the [`README.md`](https://github.com/actions/checkout/blob/main/README.md) (lines 61-68), the action resolves the path relative to `$GITHUB_WORKSPACE`. The runtime implementation validates the path, creates the directory if necessary, and executes the clone operation within that specific folder. This ensures that `GITHUB_WORKSPACE` remains the working directory for subsequent steps, while repository files reside in the specified subdirectory.

## Summary

- **The `path` input** in `actions/checkout` redirects the clone destination from the workspace root to a custom subdirectory.
- **Directory creation** happens automatically when the specified path does not exist, as defined in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml).
- **Multiple checkouts** can coexist side-by-side by assigning unique paths to each `actions/checkout` step.
- **Access patterns** require referencing the custom path (e.g., `./src` or `./tools`) in subsequent workflow steps to locate checked-out files.

## Frequently Asked Questions

### What is the default checkout location when using actions/checkout?

By default, `actions/checkout` clones the repository directly into `$GITHUB_WORKSPACE`, placing all repository files at the root of the workspace directory. This overwrites any existing files in that location.

### Can I checkout a repository to a location outside of $GITHUB_WORKSPACE?

No, the `path` input only accepts relative paths and must stay within `$GITHUB_WORKSPACE`. The action restricts checkouts to the workspace directory for security and isolation reasons, as enforced by the input validation logic in the action's implementation.

### How do I access files after checking out to a custom path?

Reference the custom path relative to the workspace root in subsequent steps. For example, if you specified `path: src`, access files using [`./src/file.txt`](https://github.com/actions/checkout/blob/main/./src/file.txt) or `${{ github.workspace }}/src/file.txt`. The working directory for most steps remains `$GITHUB_WORKSPACE` unless explicitly changed.

### Does the path input create intermediate directories automatically?

Yes, the action creates the full directory path specified in the `path` input if it does not already exist. This includes nested directories (e.g., `path: tools/helpers/lib`), eliminating the need for separate `mkdir` commands before the checkout step.