How to Checkout Multiple Repositories in a Single GitHub Actions Workflow

You can invoke the actions/checkout action multiple times within a single job, using the repository input to specify different repos and the path input to control their placement under $GITHUB_WORKSPACE.

The official actions/checkout action supports cloning multiple repositories by running separate steps for each target. As defined in the repository's action.yml, the action accepts a repository parameter to select any accessible repo and a path parameter to define its location relative to the workspace root. This architecture enables side-by-side clones, nested checkouts, and access to private repositories through explicit token authentication.

Core Inputs for Multi-Repository Checkout

The actions/checkout action exposes three critical inputs in action.yml that make multi-repository workflows possible:

• repository – The full name in owner/repo format. When omitted, the action defaults to the current repository triggering the workflow.
• path – The relative directory under $GITHUB_WORKSPACE where the code is placed. Defaults to the workspace root, which would overwrite previous checkouts if not specified for subsequent clones.
• token – The authentication credential. The default ${{ github.token }} only accesses the current repository; private repositories require a Personal Access Token (PAT) with appropriate scopes.

Side-by-Side Checkout Pattern

Place repositories in sibling directories to keep codebases isolated while maintaining clean separation of concerns. This pattern creates distinct folders under $GITHUB_WORKSPACE for each repository.

- name: Checkout main repo
  uses: actions/checkout@v7
  with:
    path: main          # clones into $GITHUB_WORKSPACE/main

- name: Checkout tools repo
  uses: actions/checkout@v7
  with:
    repository: my-org/my-tools
    path: my-tools      # clones into $GITHUB_WORKSPACE/my-tools

As documented in the README.md (lines 61-74), this configuration ensures the second checkout does not overwrite the first by explicitly defining unique paths.

Nested Checkout Pattern

Clone secondary repositories inside subdirectories of your primary codebase. This approach is useful when integrating shared libraries or documentation that must reside within the main repository's structure.

- name: Checkout primary repo
  uses: actions/checkout@v7

- name: Checkout tools repo (nested)
  uses: actions/checkout@v7
  with:
    repository: my-org/my-tools
    path: my-tools      # creates $GITHUB_WORKSPACE/my-tools inside the primary repo

According to the official documentation in README.md (lines 77-88), the path input interprets the destination relative to the workspace root, allowing nested placement regardless of the primary checkout's location.

Accessing Private Repositories

When the target repository has restricted visibility, you must provide a Personal Access Token with repo scope via the token input. The default GITHUB_TOKEN secret lacks permissions to access repositories outside the workflow's context.

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

- name: Checkout private tools repo
  uses: actions/checkout@v7
  with:
    repository: my-org/my-private-tools
    token: ${{ secrets.GH_PAT }}   # PAT stored as a repository secret

    path: my-tools

This pattern, referenced in README.md (lines 91-104), requires storing the PAT as an encrypted secret in your repository settings and referencing it explicitly in the workflow file.

Complete Workflow Example

This comprehensive configuration demonstrates checking out the current repository alongside both public and private dependencies:

name: Multi-repo checkout demo
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # Primary repository

      - uses: actions/checkout@v7
        with:
          path: primary

      # Secondary public repo

      - uses: actions/checkout@v7
        with:
          repository: octocat/example
          path: example

      # Secondary private repo

      - uses: actions/checkout@v7
        with:
          repository: my-org/secret-lib
          token: ${{ secrets.GH_PAT }}
          path: secret-lib

Each step runs independently, performing its own git clean and fetch operations unless you override these defaults with the clean or fetch-depth inputs.

Validation and Testing

The actions/checkout repository includes automated tests that verify multi-repository functionality. The __test__/verify-side-by-side.sh script validates that multiple checkouts create correctly isolated directory structures, while __test__/verify-worktree.sh ensures the workspace layout remains consistent when performing nested checkouts. These tests confirm that the path parameter correctly scopes each repository without interference between clone operations.

Summary

• Invoke actions/checkout multiple times within a single job to checkout multiple repositories in a single workflow.
• Set the path input for every checkout after the first to prevent overwriting previously cloned code.
• Use the repository input to specify external repositories in owner/repo format.
• Provide a PAT via the token input when accessing private repositories outside the workflow's default scope.
• Reference test scripts like __test__/verify-side-by-side.sh to understand validated implementation patterns.

Frequently Asked Questions

Can I checkout multiple repositories in one GitHub Actions job?

Yes, you can invoke the actions/checkout action multiple times within the same job. Each invocation is independent and creates a distinct clone, provided you use the path input to specify unique destination directories for each repository.

How do I access a private repository from my workflow?

You must provide a Personal Access Token (PAT) with repo scope through the token input. Store the PAT as a repository or organization secret, then reference it as ${{ secrets.SECRET_NAME }}. The default ${{ github.token }} cannot access repositories other than the one triggering the workflow.

What is the default path when using actions/checkout?

The default path is the $GITHUB_WORKSPACE root. Without a path specification, the action clones code directly into the workspace directory, which overwrites any previous checkout. Always specify path when checking out multiple repositories to maintain separate directories.

Do I need to checkout the current repository first?

No, the order is flexible. However, checking out the primary repository first is conventional practice. If you omit the path input for the first checkout, subsequent checkouts must specify paths to avoid overwriting the initial clone.

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