How to checkout a private submodule from a github action?

[jaredly]

Apparently the $GITHUB_TOKEN only has permissions for the current repo (which makes sense) – is there a way to allow access to another private repo?

It’s currently failing:

Submodule 'secrets' ([email protected]:{}/{}.git) registered for path 'secrets'
Cloning into '/home/runner/work/{}/{}/secrets'...
Host key verification failed.
fatal: Could not read from remote repository.
Please make sure you have the correct access rights

and the repository exists.

fatal: clone of '[email protected]:{}/{}.git' into submodule path '/home/runner/work/{}/{}/secrets' failed

Failed to clone 'secrets'. Retry scheduled

[oldskool]

You should be able to set a custom token when using the checkout action. So, if you have a token that you know will have access to both your current repo as well as the submodule(s), you can run a step like:

- uses: actions/checkout@v1
  with:
    token: ${{ secrets.ACCESS_TOKEN }}
    submodules: true

Which would use a secret called “ACCESS_TOKEN” (which you should then create in the repository that runs your workflow) to pull the repositories.

[jaredly]

Cool yeah that makes sense. I only wish there were a way to generate a custom token with restricted access to only a couple of repos 😕 I guess I’ll probably make a bot account with limited permissions and go with that.

Thanks!

[Stanzilla]

Sadly they broke that with actions@v2 so beware when updating! You now have to use something like this if you want to keep using SSH URLs instead of HTTPS:

steps:
      - uses: actions/checkout@v2
      - name: Checkout submodules
        uses: actions/checkout@v2
        with:
          repository: yourPrivateOrg/yourPrivateRepo
          token: ${{ secrets.ACCESS_TOKEN }}
          path: yourPrivateRepo

[yurist38]

I've just had a few hours of debugging and found out that THE TOKEN MUST HAVE AN EXPIRATION DATE! Otherwise, it won't work, be careful.

[nobelwong]

Legend!

[dpmcgabriel]

How to generete the token btw?

[yurist38]

You need to go to Settings -> Developer Settings -> Personal access tokens and then either Fine-grained tokens or Tokens (classic) (I still use classic ones mostly)

[asbjornu]

As per actions/checkout#287 (comment), it is now possible to use actions/create-github-app-token to create a token usable by actions/checkout as such:

jobs:
  test-submodules:
    runs-on: ubuntu-latest
    steps:
    - name: Get token from Github App
      uses: actions/create-github-app-token@v1
      id: app_token
      with:
        app-id: ${{ secrets.APP_ID }}
        private-key: ${{ secrets.APP_PEM }}
        # owner is required, otherwise the creds will fail the checkout step
        owner: ${{ github.repository_owner }}

    - name: Checkout from GitHub
      uses: actions/checkout@v4
      with:
        submodules: true
        token: ${{ steps.app_token.outputs.token }}

It feels a bit over the top to create an entire GitHub App for this purpose, but it works and is more robust than a personal access token.

[sheershoff]

the owner part was not obvious for me, thank you!

[parth-hb]

I faced same issue and struggled atleast 2 days to make it work. If you're also struggling with the same, here's a reliable and tested fix using Deploy Keys.

Steps

1. Generate an SSH Key

   ssh-keygen -t rsa -b 4096 -C "ci-access" -f submodule_deploy_key

2. Add Public Key to Submodule Repo

   • Go to your submodule repo (e.g., my-org/my-redux-store)
   • Navigate to: Settings → Deploy Keys
   • Click "Add deploy key", paste the public key from submodule_deploy_key.pub
   • Make sure to enable Allow write access if required

3. Add Private Key to Main Repo Secrets

   • Go to your main repo (my-org/my-app)
   • Add a secret like SUBMODULE_SSH_KEY
   • Paste contents of submodule_deploy_key (the private key)

4. Modify Workflow
   Before updating submodules, add:

   - name: Checkout main repo (no submodules)
     uses: actions/checkout@v4
     with:
        submodules: false
          
   - name: Setup SSH for submodules
     run: |
       mkdir -p ~/.ssh
       echo "${{ secrets.SUBMODULE_SSH_KEY }}" > ~/.ssh/id_rsa
       chmod 600 ~/.ssh/id_rsa
       ssh-keyscan github.com >> ~/.ssh/known_hosts
   
    - name: Init and update submodules
      run: |
       git submodule sync
       git submodule update --init --recursive
   

This should fix the common Permission denied or Repository not found errors when dealing with submodules.

---

Works great when:

• You don’t want to use personal tokens
• Better than using app tokens
• You want tight access control over a single repo
• You prefer SSH over HTTPS

[greenmoss]

You said it already "single repo", but worth calling out more, as people like me who read too quickly might not catch it:

Github only allows you to use your deploy key once, so it will work on your first submodule.

If you try to authorize one deploy key on multiple submodules, Github will deny your key with error "Key is already in use".

[wherka-ama]

Hello,
if anyone here is still interested in this topic I might have some good news.

I've been working on a GitHub CLI extension that solves a common pain point: managing Git authentication across multiple organizations.

Key features:

• 🔐 GitHub App authentication - No more long-lived PATs for CI/CD
• 🔀 Pattern-based routing - Different credentials for different repos/orgs (technically they are not really patterns, more like a hierarchy based approach - org or org/repo)
• 🔑 PAT support - Mix GitHub Apps with PATs when needed
• 🏢 Multi-org friendly - Works seamlessly with submodules across orgs
• 🔒 Secure storage - Encrypted credentials with automatic token caching

Install:

gh extension install AmadeusITGroup/gh-app-auth

Here's the repo:
📦 https://github.com/AmadeusITGroup/gh-app-auth

It is written in GO, released under Apache and all kinds of contributions are welcome.

It's still early days - there may be bugs and rough edges I haven't discovered yet. Would love your feedback, issues, or PRs! 🙏