Permission Denied (publickey) in GitHub Actions: Fix
Last updated
git@github.com: Permission denied (publickey) means git tried to use SSH to reach GitHub and the runner has no key that GitHub accepts. A fresh runner has no SSH keys at all, so any git@github.com: URL, SSH submodule or SSH-based dependency fails until you give the job a key, or switch the URL to HTTPS with a token.
The exact message
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
A similar failure over HTTPS reads could not read Username.
Fix 1: use HTTPS and a token (usually simplest)
Rewrite SSH URLs to HTTPS for the job, then use a token as in the could not read Username fix:
- run: git config --global url."https://x-access-token:${GH_TOKEN}@github.com/".insteadOf "git@github.com:"
env:
GH_TOKEN: ${{ secrets.CROSS_REPO_TOKEN }}
Fix 2: give the job an SSH key
Create a key pair with no passphrase, add the public key to the target repository as a deploy key (Settings, Deploy keys), and store the private key as a repository secret named DEPLOY_KEY. Then either let actions/checkout use it:
- uses: actions/checkout@v4
with:
repository: my-org/private-lib
ssh-key: ${{ secrets.DEPLOY_KEY }}
or load it into an SSH agent for all later git and ssh commands, which also works for submodules and git-based package installs:
- uses: webfactory/ssh-agent@v0.9.0
with:
ssh-private-key: ${{ secrets.DEPLOY_KEY }}
- run: git submodule update --init --recursive
Generate a key with ssh-keygen -t ed25519 -C "ci" -f deploy_key -N "", and delete the local copy once it is stored in the secret.
Limits of deploy keys
A deploy key works for one repository only, and GitHub does not allow the same public key on two repositories. If a job needs several private repositories over SSH, load several keys, one per repository, or use one token with access to all of them. A machine user or a GitHub App is often cleaner than many deploy keys.
Other causes
- The key was added to the wrong repository, or as read-only when you push. Tick "Allow write access" only for jobs that push.
- The secret contains a private key with lost newlines or Windows line endings. Paste the whole file, including the
BEGINandENDlines. - The key has a passphrase. Non-interactive jobs cannot enter it.
- The key is in the secret but never loaded, because the agent step is in a different job.
- In a Docker container job,
sshruns inside the container, which does not have the host's agent socket. Load the key in the container.
Test the key quickly
- run: ssh -T -o StrictHostKeyChecking=accept-new git@github.com || true
A working key prints Hi <repo>! You've successfully authenticated. The || true is there because the command always exits non-zero for a shell-less account, so read the output.
How to prevent it
- Prefer HTTPS with a scoped token or a GitHub App token for CI.
- If you use deploy keys, name them by repository and rotate them on a schedule.
- Keep SSH keys in secrets, never in the repository.
- Do not give write access to keys that only read.
FAQ
Why does it work on my laptop?
Your laptop has your SSH key loaded. A runner is a fresh machine with none.
Can I use my personal SSH key in CI?
Technically yes, but it gives CI the same access as you. Use a deploy key or a machine account with the smallest access needed.
Does actions/checkout need an SSH key for the current repository?
No. It uses the GITHUB_TOKEN over HTTPS for the repository the workflow runs in.
What about known_hosts errors?
The ssh-agent action adds GitHub's host keys for you. If you call ssh directly, use StrictHostKeyChecking=accept-new or add GitHub's published host keys.
Related
- Permission Denied to github-actions[bot] (403): FixFix "Permission to repo.git denied to github-actions[bot]" (403) when a workflow pushes: set contents write, check branch rules and fork limits.
- Refusing to Allow a GitHub App to Update Workflow: FixFix "refusing to allow a GitHub App to create or update workflow without workflows permission": use a PAT or App token with workflow write access.
- Cache Service Responded With 429: FixFix "Failed to restore: Cache service responded with 429" in GitHub Actions: too many cache requests. Upgrade actions/cache, restore once, save once.
- fatal: could not read Username for github.com: FixFix "fatal: could not read Username for 'https://github.com'" in GitHub Actions: private repos, submodules and git dependencies need a token.