Skip to content

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

  1. The key was added to the wrong repository, or as read-only when you push. Tick "Allow write access" only for jobs that push.
  2. The secret contains a private key with lost newlines or Windows line endings. Paste the whole file, including the BEGIN and END lines.
  3. The key has a passphrase. Non-interactive jobs cannot enter it.
  4. The key is in the secret but never loaded, because the agent step is in a different job.
  5. In a Docker container job, ssh runs 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

  1. Prefer HTTPS with a scoped token or a GitHub App token for CI.
  2. If you use deploy keys, name them by repository and rotate them on a schedule.
  3. Keep SSH keys in secrets, never in the repository.
  4. 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.