Saltar al contenido

Permission Denied (publickey) en GitHub Actions: solución

Última actualización:

git@github.com: Permission denied (publickey) significa que git intentó usar SSH para conectarse a GitHub y el runner no tiene ninguna clave que GitHub acepte. Un runner recién creado no tiene claves SSH, así que cualquier URL git@github.com:, submódulo SSH o dependencia basada en SSH falla hasta que asigne una clave al job o cambie la URL a HTTPS con un token.

El mensaje exacto

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.

Un fallo similar en HTTPS muestra could not read Username.

Solución 1: usar HTTPS y un token (normalmente la más sencilla)

Reescriba las URL de SSH a HTTPS para el job y, a continuación, use un token como en la solución de could not read Username:

- run: git config --global url."https://x-access-token:${GH_TOKEN}@github.com/".insteadOf "git@github.com:"
  env:
    GH_TOKEN: ${{ secrets.CROSS_REPO_TOKEN }}

Solución 2: asignar al job una clave SSH

Cree un par de claves sin contraseña, añada la clave pública al repositorio de destino como deploy key (Settings, Deploy keys) y guarde la clave privada como secreto del repositorio llamado DEPLOY_KEY. Después, haga que actions/checkout la use:

- uses: actions/checkout@v4
  with:
    repository: my-org/private-lib
    ssh-key: ${{ secrets.DEPLOY_KEY }}

o cárguela en un agente SSH para todos los comandos git y ssh posteriores, lo que también funciona con submódulos e instalaciones de paquetes basadas en git:

- uses: webfactory/ssh-agent@v0.9.0
  with:
    ssh-private-key: ${{ secrets.DEPLOY_KEY }}
- run: git submodule update --init --recursive

Genere una clave con ssh-keygen -t ed25519 -C "ci" -f deploy_key -N "" y elimine la copia local una vez guardada en el secreto.

Límites de las deploy keys

Una deploy key funciona solo para un repositorio, y GitHub no permite la misma clave pública en dos repositorios. Si un job necesita varios repositorios privados por SSH, cargue varias claves, una por repositorio, o use un único token con acceso a todos ellos. Una cuenta de usuario de máquina o una GitHub App suele ser más práctica que muchas deploy keys.

Otras causas

  1. La clave se añadió al repositorio equivocado, o como solo lectura cuando se necesita hacer push. Marque "Allow write access" solo en los jobs que hagan push.
  2. El secreto contiene una clave privada con saltos de línea perdidos o finales de línea de Windows. Pegue el archivo completo, incluidas las líneas BEGIN y END.
  3. La clave tiene contraseña. Los jobs no interactivos no pueden introducirla.
  4. La clave está en el secreto, pero nunca se carga, porque el paso del agente está en otro job.
  5. En un job de contenedor Docker, ssh se ejecuta dentro del contenedor, que no tiene el socket del agente del host. Cargue la clave dentro del contenedor.

Pruebe la clave rápidamente

- run: ssh -T -o StrictHostKeyChecking=accept-new git@github.com || true

Una clave que funciona muestra Hi <repo>! You've successfully authenticated. El || true está ahí porque el comando siempre termina con código distinto de cero en una cuenta sin shell, así que lea la salida.

Cómo prevenirlo

  1. Para CI, prefiera HTTPS con un token de alcance limitado o un token de GitHub App.
  2. Si usa deploy keys, nómbrelas por repositorio y rótelas periódicamente.
  3. Guarde las claves SSH en secretos, nunca en el repositorio.
  4. No conceda acceso de escritura a claves que solo necesitan lectura.

Preguntas frecuentes

¿Por qué funciona en mi portátil?

Su portátil tiene cargada su clave SSH. Un runner es una máquina nueva sin ninguna.

¿Puedo usar mi clave SSH personal en CI?

Técnicamente sí, pero da a CI el mismo acceso que tiene usted. Use una deploy key o una cuenta de máquina con el mínimo acceso necesario.

¿Necesita actions/checkout una clave SSH para el repositorio actual?

No. Usa el GITHUB_TOKEN por HTTPS para el repositorio en el que se ejecuta el workflow.

¿Qué pasa con los errores de known_hosts?

La acción ssh-agent añade por usted las claves de host de GitHub. Si llama a ssh directamente, use StrictHostKeyChecking=accept-new o añada las claves de host publicadas por GitHub.