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

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

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

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

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

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

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