Token de GitHub y autenticación en Git: personal access token, Git Credential Manager, push sin contraseña

Por qué Git ya no acepta la contraseña de GitHub

Si al ejecutar git push escribes el usuario y la contraseña de github.com y recibes un rechazo, no es un error de tecleo. Desde el 13 de agosto de 2021, GitHub desactivó el acceso con contraseña para las operaciones de Git por HTTPS. En su lugar hay que usar un token de acceso personal (personal access token, PAT) o la autenticación en el navegador que realiza Git Credential Manager.

El mensaje de error tiene este aspecto:

remote: Support for password authentication was removed on August 13, 2021.
remote: Please see https://docs.github.com/... for information on currently recommended modes of authentication.
fatal: Authentication failed for 'https://github.com/user/project.git/'

La razón es sencilla: la contraseña de la cuenta da acceso total a todo, no se puede limitar a un repositorio y es incómodo revocarla. El token, en cambio, se crea para una tarea concreta, tiene fecha de caducidad y un conjunto de permisos, y si se filtra se elimina en un minuto sin cambiar la contraseña. GitLab y Bitbucket siguieron el mismo camino, así que lo que se explica a continuación se aplica en lo esencial también a ellos.

Dos formas de autenticarse: HTTPS y SSH

Git se comunica con el repositorio remoto con uno de dos protocolos, y de él depende cómo inicias sesión.

La clave SSH se configura una sola vez y después Git no pide ni usuario ni contraseña. Su creación y su alta en GitHub están explicadas en el artículo sobre la configuración de Git; aquí nos centramos en HTTPS, que es donde los principiantes ven con más frecuencia la petición de contraseña. Para saber qué protocolo usa tu repositorio, ejecuta:

git remote -v
origin  https://github.com/user/project.git (fetch)
origin  https://github.com/user/project.git (push)

Cómo crear un token de GitHub (personal access token)

El personal access token es una cadena larga y aleatoria que GitHub te da en lugar de la contraseña para el acceso programático. Los tokens classic empiezan por ghp_, y los fine-grained, por github_pat_. El token se muestra una sola vez, justo después de crearlo, así que cópialo a tu gestor de contraseñas.

Paso a paso

1. Entra en github.com, pulsa tu avatar en la esquina superior derecha y abre Settings.
2. En la parte inferior del menú izquierdo elige Developer settings y después Personal access tokens.
3. Elige el tipo: Fine-grained tokens (recomendado) o Tokens (classic), y pulsa el botón para generar uno nuevo.
4. Pon un nombre claro (por ejemplo, «portátil, trabajo»), una fecha de caducidad y los permisos.
5. Pulsa generar y copia el token de inmediato.

Fine-grained o classic

El token fine-grained se limita a repositorios concretos y a permisos individuales. Para el trabajo normal con código, selecciona los repositorios necesarios y, en los permisos de repositorio, da Contents: Read and write; con eso bastan clone, pull y push. Si solo lees un repositorio privado, basta con Read-only.

El token classic afecta a todos tus repositorios a la vez. Para hacer push a un repositorio hace falta el ámbito repo, y para modificar archivos en .github/workflows, además, workflow. El classic es más sencillo, pero más peligroso: si se filtra, el atacante obtiene acceso a toda la cuenta.

Fecha de caducidad

GitHub ofrece varias duraciones y permite elegir una fecha propia. Se puede crear un token sin caducidad, pero no conviene: un token eterno olvidado es un agujero de seguridad clásico. Lo razonable es entre 30 y 90 días y renovarlo cuando llegue el recordatorio que GitHub envía al correo antes de que expire.

Git push y git clone con token

Usar el token es más sencillo de lo que parece: Git pregunta «Password» y pegas el token en lugar de la contraseña.

$ git push origin main
Username for 'https://github.com': tu-usuario
Password for 'https://tu-usuario@github.com': <pega el token>

En la terminal no se ven los caracteres de la contraseña; es normal. Pega el token y pulsa Enter. En Git Bash de Windows, el pegado funciona con Shift+Insert o con el botón derecho del ratón.

Git clone with token

Un repositorio privado se clona igual: git clone pide el usuario y el token. Si necesitas evitar las preguntas (por ejemplo, en un script), el token se puede poner directamente en la dirección:

git clone https://tu-usuario:<TOKEN>@github.com/user/project.git

Hay un inconveniente: la dirección con el token queda guardada en .git/config y puede acabar en el historial de la shell. Después de clonar, quita el token de la dirección:

git remote set-url origin https://github.com/user/project.git

En los sistemas de CI, el token se pasa como variable de entorno secreta, nunca como parte de un archivo. En GitHub Actions ya existe el token integrado GITHUB_TOKEN para el repositorio actual, así que a menudo no hace falta un PAT.

GitLab: git clone con token

En GitLab el token se crea en la configuración del perfil, en la sección Access tokens; para trabajar con código hacen falta los ámbitos read_repository y write_repository. El esquema es el mismo: el usuario de GitLab como nombre y el token como contraseña.

git clone https://oauth2:<TOKEN>@gitlab.com/group/project.git

GitLab acepta el nombre oauth2 para cualquier token personal; también puedes escribir tu propio usuario.

Git pull y fetch

En un repositorio público, git pull y git clone funcionan sin autenticación. Usuario y token se piden solo para repositorios privados o para git push. Si un pull en un proyecto público pide contraseña, lo más probable es que la dirección tenga una errata: GitHub responde a un repositorio inexistente igual que a uno privado.

Git Credential Manager: qué es

Escribir el token en cada push resulta incómodo. Este trabajo lo asume el credential helper: un programa auxiliar que Git llama cuando necesita credenciales. Git le pasa la dirección del servidor y el programa devuelve el usuario y la contraseña (o el token) desde su almacén.

Git Credential Manager (GCM) es el más cómodo de estos auxiliares. Es un programa multiplataforma de GitHub y Microsoft: en el primer push abre una ventana o el navegador para iniciar sesión en GitHub (también con autenticación de dos factores), y GCM obtiene el token y lo guarda en el almacén seguro del sistema. En este caso no hace falta crear el PAT a mano.

GCM funciona con GitHub, GitLab, Bitbucket y Azure DevOps. En Git para Windows se instala por defecto; es la opción de credential helper que aparece en el instalador.

Qué tipos de credential.helper existen

Configurar la autenticación de Git en Windows, macOS y Linux

Para ver qué helper está configurado:

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

Windows

Si al instalar Git dejaste la configuración por defecto, GCM ya funciona: en el primer push desde Git Bash, PowerShell o VS Code se abrirá la ventana de inicio de sesión en GitHub. Si el helper no está configurado, actívalo a mano:

git config --global credential.helper manager

macOS

En Mac, Git suele usar ya osxkeychain: el token introducido una vez se guarda en el Llavero. Para el inicio de sesión en el navegador instala Git Credential Manager (por ejemplo, con Homebrew: brew install --cask git-credential-manager); él mismo se registra en la configuración.

Linux

En Linux, GCM se instala aparte (paquete .deb o archivo de las versiones del proyecto), y después se configura y se elige el almacén:

git-credential-manager configure
git config --global credential.credentialStore secretservice

En un servidor sin entorno gráfico es más práctica una caché temporal:

git config --global credential.helper 'cache --timeout=3600'

Alternativa para GitHub: gh auth login

Si tienes instalado GitHub CLI, el comando gh auth login guía el inicio de sesión en el navegador, y gh auth setup-git configura Git para tomar las credenciales de gh. Es una forma cómoda de «iniciar sesión en Git Bash» con un solo comando.

Cómo borrar o actualizar la contraseña guardada en Git

La situación más frecuente: el token caducó o cambiaste de cuenta, pero Git sigue usando los datos antiguos y responde Authentication failed. Hay que borrar el registro guardado; en el siguiente push, Git volverá a preguntar.

Comando universal

Funciona con cualquier helper:

printf "protocol=https\nhost=github.com\n\n" | git credential reject

Git reset credentials en Windows

Abre el «Panel de control» → «Administrador de credenciales» → «Credenciales de Windows», busca las entradas del tipo git:https://github.com y elimínalas. Lo mismo desde la línea de comandos:

cmdkey /list | findstr git
cmdkey /delete:git:https://github.com

Si usas GCM, existe también su comando propio para cerrar sesión en la cuenta: git credential-manager github logout <usuario>.

macOS

Abre «Acceso a Llaveros», busca la entrada github.com de tipo «contraseña de Internet» y bórrala. O desde la terminal:

git credential-osxkeychain erase
host=github.com
protocol=https

Después de la última línea pulsa Enter una vez más para enviar la línea vacía.

Linux y store

Para store, elimina la línea con github.com del archivo ~/.git-credentials; para cache, ejecuta git credential-cache exit.

Errores de autenticación y cómo corregirlos

Support for password authentication was removed

Has introducido la contraseña de la cuenta. Crea un token y pégalo en el campo Password, o configura Git Credential Manager. Si el error se repite sin que te pida la contraseña, la contraseña antigua está guardada en el almacén: bórrala como se explicó antes.

git push: Authentication failed

Causas, de más a menos frecuentes: caducó el token; el token fue revocado; el token fine-grained no tiene acceso a este repositorio o el permiso Contents está solo en lectura; en el almacén se guardaron datos de otra cuenta. Revisa la caducidad y los permisos del token en Developer settings y borra las credenciales guardadas.

remote: Permission denied (403)

La autenticación fue correcta, pero tu cuenta no tiene permiso de escritura en este repositorio. El propietario debe añadirte como Collaborator, o puedes trabajar desde tu fork y abrir un pull request.

Repository not found

En un repositorio privado GitHub no revela si existe, así que con un token incorrecto responde «not found». Comprueba la dirección con git remote -v y los permisos del token.

Git clone pide la contraseña cada vez

No hay credential helper configurado. Activa manager u osxkeychain: tras el primer ingreso correcto, Git deja de preguntar. Otra opción es pasar a SSH.

Cómo guardar el token de forma segura

• Concede el mínimo de permisos: un token fine-grained para los repositorios necesarios en lugar de un classic con repo.
• Pon fecha de caducidad y renueva el token en lugar de alargarlo indefinidamente.
• No subas tokens a ningún repositorio ni los pegues en las direcciones remote. Si un token llega a un repositorio público, GitHub puede revocarlo automáticamente, pero considéralo comprometido y elimínalo tú mismo.
• Usa el almacén del sistema (GCM, Llavero) en lugar de store.
• Un token por máquina o por tarea: así, si se filtra, solo revocas ese.

Resumen

La contraseña de GitHub no sirve para Git por HTTPS desde 2021. Hay tres vías válidas: iniciar sesión mediante Git Credential Manager en el navegador, crear un token de GitHub y escribirlo en lugar de la contraseña, o pasar a claves SSH. El token se crea en Settings → Developer settings, y lo guarda el credential.helper; si aparece Authentication failed, casi siempre basta con regenerar el token y borrar las credenciales antiguas. La conexión con GitHub y el trabajo con repositorios remotos se explican con práctica en el curso de Git.