Step‑by‑Step: Checking Out a Private Repository in GitHub Actions

One of the great strengths of GitHub Actions is its flexibility – you can build workflows that pull in code from other private repositories, not just the one where your workflow resides. This opens the door to reusable components, shared build scripts, or even private actions stored in separate repositories.

The official actions/checkout action supports secure, targeted checkouts from any repository you have access to. If you’ve ever needed to grab a specific branch from a different repository as part of your CI/CD pipeline, this guide will walk you through exactly how to do it.

A common scenario:
You have a reusable GitHub Action stored in a private repository – perhaps a Terraform deployment helper or an AI review tool. You want to use a specific branch of that repository in a workflow running elsewhere, for reasons such as:

• Testing changes before merging to main
• Maintaining environment‑specific versions of your action
• Pulling experimental or cleanup code without affecting the mainline

Instead of manually cloning via shell commands, you can let GitHub Actions do the heavy lifting with actions/checkout

Example: Checking Out a Custom Branch From A Private Repository

Here’s an example – this is the type of snippet used in production to pull in a private action from a separate repository, targeting a non‑default branch.

- uses: actions/checkout@v5
  with:
    repository: thomast1906/terraform-ai-review-action
    token: ${{ secrets.ACTIONS_PAT_TOKEN }}
    path: .github/actions/terraform-ai-review-action
    ref: cleanup-action

Parameter Breakdown

• repository
  In owner/repo format, this tells the action to clone a repository other than the one where the workflow resides. In this example, we’re pulling thomast1906/terraform-ai-review-action.

• uses: actions/checkout@v5
  Specifies the latest major version of the official checkout action, ensuring compatibility with features like sparse checkout and secure authentication.

• token
  Required for private repositories or cross‑repository access.
  Best practice: Store a Personal Access Token in GitHub Secrets and reference it here. Keep scopes minimal – grant only the permissions you need.
• path
  Defines where the repository will be cloned inside the runner’s workspace. This is especially useful when pulling multiple repositories.
• ref
  Points to the branch, tag, or commit SHA you want. In this case, cleanup-action is the branch containing the desired version of the action.

Step‑by‑Step Workflow Setup

To integrate this into a working workflow:

name: Custom Branch Checkout Demo
on:
  workflow_dispatch:

jobs:
  checkout-custom-branch:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout custom branch from external repo
        uses: actions/checkout@v5
        with:
          repository: my-org/my-repo
          ref: feature/my-branch
          token: ${{ secrets.MY_PAT }}
          path: ./external-repo
          fetch-depth: 0

      - name: Use files from external repo
        run: |
          ls -al ./external-repo

What’s Happening:

Checkout Step – Pulls the specified branch from the external repository into ./external-repo

1. Full History – fetch-depth: 0 retrieves the entire commit history, useful for scripts that rely on it
2. Post‑Checkout Actions – Here we list files, but in practice you might run tests, build steps, or execute the action code

Example below showing I am checking out from another repository & then using that new location

Practical Considerations and Best Practices

1. Authentication

• Use GitHub Secrets for tokens; never hard-code them
• GITHUB_TOKEN will not work for cross‑repository access unless permissions are configured
• For private repositories, a PAT with repo scope is often required

2. Performance

• Use fetch-depth: 1 for faster clones when full history is unnecessary
• Enable sparse checkout (sparse-checkout and sparse-checkout-cone-mode) for large monorepos when you only need specific directories

3. Version Pinning

• Pin to a specific major version (@v5) to avoid unexpected changes
• For maximum reproducibility, consider pinning to a commit SHA, especially in production‑critical pipelines

Key Takeaways

• Use actions/checkout@v5 for the latest features and security improvements.
• Always use secure tokens from GitHub Secrets for private repository access.
• Use  ref to target branches, tags, or commits explicitly.
• Optimise performance with fetch-depth: 1 and sparse checkout when full history isn’t required.
• Organise multi‑repository checkouts with the path parameter to prevent overwriting files.
• Check runner compatibility before upgrading to the latest checkout version.

By using custom branch checkouts, you gain flexibility in GitHub Actions – allowing you to reuse code, isolate changes, and build complex CI/CD pipelines without unnecessary complexity