Resolución de errores comunes de autenticación en Git usando SSH y tokens

La mayoría de los problemas de autenticación en Git se reducen a una discrepancia entre la URL remota, la credencial que Git intenta usar y los permisos en la cuenta de alojamiento de Git. El texto del error puede parecer dramático, pero la solución suele ser mecánica una vez que se sabe qué ruta está tomando Git.

Comience con la URL remota:

git remote -v

Si ve https://github.com/org/repo.git, Git está usando HTTPS y necesitará un nombre de usuario más un token o un ayudante de credenciales que pueda proporcionarlo. Si ve [email protected]:org/repo.git, Git está usando SSH y necesitará una clave privada que coincida con una clave pública registrada en el host.

No mezcle los dos mientras soluciona el problema. Elija HTTPS o SSH, haga que la URL remota coincida y luego pruebe esa ruta directamente.

Lea el error literalmente

fatal: Authentication failed for 'https://...' generalmente significa que Git llegó al servidor pero no presentó una credencial HTTPS válida. La credencial anterior puede estar en caché, el token puede haber expirado o el token puede no tener acceso a ese repositorio.

remote: Permission to org/repo denied o 403 Forbidden generalmente significa que su identidad fue reconocida pero no tiene permiso para la operación. Por ejemplo, puede estar usando un token de la cuenta incorrecta, un token sin acceso de escritura o una clave SSH adjunta a un usuario diferente.

Permission denied (publickey) significa que SSH no ofreció una clave que el servidor acepte.

Un mensaje repetido de nombre de usuario/contraseña a través de HTTPS generalmente significa que Git sigue recibiendo un rechazo y vuelve a preguntar. Escribir la contraseña de su cuenta repetidamente no ayudará en hosts que requieren tokens para operaciones de Git.

Solucionar HTTPS con un token de acceso personal

Para remotos HTTPS, cree un token de acceso personal en la configuración de su cuenta de alojamiento de Git. Los nombres de los menús exactos difieren entre GitHub, GitLab, Bitbucket y plataformas autoalojadas, pero la forma es la misma: cree un token, asígnele acceso al repositorio, establezca una caducidad que coincida con la política de su organización y cópielo inmediatamente.

Cuando Git le solicite, use su nombre de usuario normal y pegue el token como contraseña:

Username: su-nombre-de-usuario
Password: <pegar-token-aquí>

Use los permisos más restringidos que funcionen. Para un repositorio privado al que hace push, necesita acceso de lectura y escritura al repositorio. Para clonar repositorios públicos, es posible que no necesite un token en absoluto. Los tokens detallados y las reglas de SSO de la organización pueden agregar otra capa: un token puede existir pero aún necesita aprobación o autorización SSO antes de poder acceder a un repositorio de la empresa.

Si Git nunca solicita el nuevo token, probablemente esté usando una credencial anterior en caché. Borre la entrada almacenada para el host y luego intente de nuevo.

En macOS, revise el Acceso a Llaveros en busca de entradas relacionadas con su host de Git, como github.com o git:https://github.com.

En Windows, abra el Administrador de Credenciales y elimine la credencial genérica relevante para el host.

En Linux, inspeccione su ayudante configurado:

git config --global --get credential.helper
git config --show-origin --get-all credential.helper

El ayudante cache almacena credenciales temporalmente en la memoria. El ayudante store las escribe en el disco en texto plano a menos que configure una capa de almacenamiento más segura, así que úselo con cuidado. El sistema de ayudantes de credenciales de Git está diseñado para pedir credenciales a los ayudantes y permitir que estos guarden las exitosas; la seguridad depende del ayudante que elija.

Una secuencia de reinicio HTTPS útil es:

git remote -v
git config --show-origin --get-all credential.helper
# eliminar la credencial anterior del almacén de credenciales del SO
git ls-remote origin

git ls-remote origin es una prueba limpia porque contacta al remoto sin cambiar su árbol de trabajo.

Solucionar SSH con claves

Para remotos SSH, primero verifique si ya tiene claves:

ls -al ~/.ssh

Los nombres de clave comunes incluyen id_ed25519, id_rsa y nombres específicos del host como github_work_ed25519. El archivo .pub es la clave pública que sube al host de Git. El archivo sin .pub es privado y no debe compartirse.

Si necesita una nueva clave, Ed25519 es un buen valor predeterminado en sistemas modernos:

ssh-keygen -t ed25519 -C "[email protected]"

Use una frase de contraseña a menos que su entorno tenga una razón de automatización específica para no hacerlo. Luego agregue la clave pública a su cuenta de host de Git o a la configuración de claves de implementación:

cat ~/.ssh/id_ed25519.pub

Pruebe la conexión directamente:

ssh -T [email protected]

Para GitLab o Bitbucket, reemplace el nombre del host. Una prueba exitosa generalmente imprime un saludo o un mensaje que indica que no se proporciona acceso al shell. Eso está bien; la autenticación Git-over-SSH aún puede funcionar.

Si SSH aún falla, pregúntele al cliente SSH qué está haciendo:

ssh -vT [email protected]

Busque líneas que muestren qué claves se ofrecen. Si su clave no se ofrece, cárguela en el agente:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Para múltiples cuentas en el mismo host, use ~/.ssh/config para que Git sepa qué clave pertenece a qué remoto:

Host github-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/github_work_ed25519
  IdentitiesOnly yes

Luego apunte el repositorio a ese alias:

git remote set-url origin git@github-work:org/repo.git

Esto evita el problema común donde SSH ofrece su clave personal a un repositorio de trabajo.

Cambiar protocolos limpiamente

Si su equipo estandariza en SSH, cambie un remoto HTTPS así:

git remote set-url origin [email protected]:ORG/REPO.git

Si su empresa bloquea SSH o requiere inspección HTTPS, cambie al revés:

git remote set-url origin https://github.com/ORG/REPO.git

Después de cambiar la URL, pruebe con una operación de lectura:

git fetch origin

Luego pruebe la acción que falló:

git push origin HEAD

Si fetch funciona pero push falla, la autenticación probablemente sea válida y la autorización es el problema. Verifique la protección de ramas, el rol del repositorio, el alcance del token y las reglas de SSO de la organización.

Entornos CI y servidor

En agentes de compilación y servidores, evite usar el token personal de un humano cuando sea posible. Prefiera claves de implementación, usuarios máquina o el almacén de credenciales integrado de su sistema CI. Mantenga los secretos fuera del historial de comandos y registros. No pegue tokens en URL remotas como esta a menos que esté en un entorno desechable controlado:

https://[email protected]/org/repo.git

Ese estilo puede filtrarse a través de registros, listas de procesos, historial de shell y archivos de configuración.

Para Jenkins, ejecutores de GitHub Actions, ejecutores de GitLab y sistemas similares, almacene las credenciales en el mecanismo secreto de la plataforma e inyéctelas solo para el trabajo que las necesita.

Una lista de verificación rápida

Ejecute estos en orden cuando esté atascado:

git remote -v
git ls-remote origin

Si la URL es HTTPS, borre las credenciales antiguas en caché y use un token actual con los permisos de repositorio correctos.

Si la URL es SSH, ejecute:

ssh -T git@su-nombre-de-host
ssh -vT git@su-nombre-de-host

Confirme que se está ofreciendo la clave esperada y que su mitad pública está registrada con la cuenta correcta.

Si la autenticación tiene éxito pero push falla, busque reglas de autorización: ramas protegidas, rol de escritura faltante, autorización SSO caducada, claves de implementación de solo lectura o tokens sin permiso de escritura.

La solución confiable no es probar contraseñas aleatorias. Haga coincidir el protocolo remoto con el tipo de credencial, elimine las credenciales en caché obsoletas, pruebe la conexión directamente y luego verifique los permisos en el repositorio.