How to Checkout Multiple Repositories Side-by-Side with actions/checkout

You can checkout multiple repositories side-by-side in a single GitHub Actions workflow by invoking actions/checkout multiple times with the path input parameter to specify separate subdirectories under $GITHUB_WORKSPACE.

The actions/checkout action supports cloning multiple repositories into isolated subdirectories within the same job. By leveraging the path input defined in action.yml (lines 55-57), you direct each checkout instance to a specific folder, preventing conflicts while enabling cross-repository workflows.

How the Path Input Enables Side-by-Side Checkouts

The path input determines where under $GITHUB_WORKSPACE the repository is placed. According to the source code in action.yml, when you specify a path, the action delegates directory preparation to src/git-directory-helper.ts, which creates the directory if missing or cleans it if requested.

The workflow follows this sequence:

1. Input Parsing: src/input-helper.ts reads the path and repository inputs, defaulting the repository to ${{ github.repository }} if omitted
2. Directory Preparation: src/git-directory-helper.ts validates and prepares the target path
3. Git Operations: src/git-source-provider.ts executes the clone or fetch operations into the specified directory
4. Isolation: Each checkout step runs independently, leaving repositories in separate folders

This architecture ensures that checking out a secondary repository never interferes with previously checked out code.

Step-by-Step Implementation

Checkout the Primary Repository

First, checkout your workflow's primary repository into a named subdirectory. While this step is optional (the action defaults to the workspace root), explicitly setting a path establishes a consistent structure for multi-repo workflows.

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

This places the repository in $GITHUB_WORKSPACE/main.

Checkout Secondary Repositories

Add additional steps for each repository you need side-by-side. Use the repository input to specify the owner/repo format, and path to define the subdirectory name.

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

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

The src/input-helper.ts file handles the authentication token propagation, while src/main.ts coordinates the execution flow for each instance.

Accessing Side-by-Side Repositories

After checkout, reference the repositories using the ${{ github.workspace }} context combined with your specified path names.

- name: Use multiple repos
  run: |
    echo "Contents of main repo:"
    ls ${{ github.workspace }}/main
    echo "Contents of tools repo:"
    ls ${{ github.workspace }}/my-tools

Complete Workflow Example

This example demonstrates checking out three repositories—your primary code, a shared tools library, and a private utilities repository—into parallel directories.

# .github/workflows/multi-repo.yml

name: Multi-repo Checkout
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - 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: my-tools

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

      - name: Run cross-repo script
        run: |
          echo "Main repo files:"
          ls ${{ github.workspace }}/main
          echo "Tools repo files:"
          ls ${{ github.workspace }}/my-tools
          echo "Private utils files:"
          ls ${{ github.workspace }}/private-utils

This pattern appears in the official README.md (lines 61-74) and supports use cases including monorepo builds, dependency compilation from external sources, and integration testing across repositories.

Key Source Files and Implementation Details

Understanding the internal implementation helps troubleshoot complex checkout scenarios:

• action.yml: Defines the path input schema and default values
• src/main.ts: Entry point that orchestrates the checkout process and registers problem matchers
• src/git-directory-helper.ts: Implements directory creation logic, handling edge cases like existing files and submodule conflicts
• src/input-helper.ts: Parses workflow inputs including repository, path, and token, converting them into the sourceSettings object consumed by the git provider
• src/git-source-provider.ts: Executes the actual git clone, fetch, and checkout commands based on the processed settings

Summary

• Use the path input to specify unique subdirectories for each repository checkout
• Invoke actions/checkout multiple times in the same job to create side-by-side repositories
• Reference files using ${{ github.workspace }}/<path> in subsequent steps
• Authentication for private repositories requires passing a PAT via the token input
• The action's modular architecture (input-helper.ts, git-directory-helper.ts, git-source-provider.ts) ensures reliable isolation between checkouts

Frequently Asked Questions

Can I checkout multiple repositories in parallel?

No, steps in a GitHub Actions job execute sequentially, not in parallel. Each actions/checkout step runs after the previous one completes. However, because each checkout uses a unique path, they do not interfere with one another. If you need true parallel checkout, you must use separate jobs, though this requires uploading and downloading artifacts to combine the code.

How do I handle private repositories when checking out multiple repos?

Specify a Personal Access Token (PAT) or GitHub App token using the token input parameter. As parsed by src/input-helper.ts, this token overrides the default GITHUB_TOKEN, allowing access to private repositories within your organization or accessible via the PAT's permissions. The token must have read access to the target repositories.

Does the path input create the directory automatically?

Yes. The src/git-directory-helper.ts module automatically creates the specified directory if it does not exist. If the directory already contains files and you have set clean: true, the action will remove existing contents before performing the checkout. This ensures a clean state for each repository.

Can I checkout repositories from different organizations?

Yes, provided you have access. Use the repository input with the full owner/repo format (e.g., other-org/their-repo). For private repositories outside your current organization, you must provide a token with appropriate cross-organization read permissions. The action supports any repository accessible via the GitHub API or git protocol using the supplied credentials.

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