Introduction

actions/checkout usually works out of the box for the repository that triggered the workflow, but private repository access breaks quickly when the job checks out a second repository, private submodules, or a repository blocked by organization policy. The error often looks like a generic Git auth failure even though the real problem is token scope or repository visibility.

Symptoms

  • actions/checkout@v4 fails with terminal prompts disabled, repository not found, or HTTP 403
  • Checkout works for the current repository but fails for submodules or a second private repository
  • The same workflow succeeds in one repository but fails when copied to another
  • Organization-owned repositories fail while personal repositories succeed

Common Causes

  • The workflow removed contents: read from the GITHUB_TOKEN permissions
  • The job is checking out a different private repository that the default token cannot access
  • Private submodules require a PAT or GitHub App token with access to those repositories
  • Organization Actions policy restricts repository or workflow token access

Step-by-Step Fix

  1. 1.Confirm whether the failure is for the current repository, another repository, or submodules
  2. 2.The fix differs depending on whether checkout is targeting the triggering repository or an extra private dependency.
yaml
- uses: actions/checkout@v4
  with:
    submodules: recursive
  1. 1.Give the workflow explicit read permission to repository contents
  2. 2.Minimal-permission workflows must still allow the checkout step to read repository contents.
yaml
permissions:
  contents: read
  1. 1.Use a separate token for cross-repository checkout or private submodules
  2. 2.The default GITHUB_TOKEN is scoped to the current repository. For another private repository, use a fine-grained PAT or GitHub App token that can read the target repository.
yaml
- uses: actions/checkout@v4
  with:
    repository: myorg/shared-lib
    path: shared-lib
    token: ${{ secrets.CROSS_REPO_READ_TOKEN }}
  1. 1.Check organization policy if the token should work but still fails
  2. 2.Some failures come from org-level Actions restrictions rather than the workflow YAML itself. Review repository access, Actions policy, and token restrictions in organization settings.

Prevention

  • Declare permissions: explicitly in every workflow so checkout behavior is predictable
  • Use dedicated fine-grained read tokens for cross-repository access rather than overbroad classic PATs
  • Keep private submodule access documented alongside the workflow that needs it
  • Test checkout of secondary repositories separately before combining it with build and deploy steps