Cuando trabajamos con proyectos alojados en GitHub, es común que al principio usemos una URL HTTPS con un Personal Access Token para clonar, descargar o actualizar el repositorio. Sin embargo, estos tokens pueden vencer, ser revocados o simplemente dejar de funcionar por cambios de seguridad.
En este artículo veremos cómo migrar la autenticación de un proyecto desde HTTPS con token hacia SSH, cómo validar que la conexión funcione correctamente y qué hacer cuando Git no permite cambiar de rama porque existen archivos locales modificados, como puede pasar con archivos de configuración en Laravel.
El problema: el token de acceso ya venció
Supongamos que tenemos un proyecto Laravel en un servidor de pruebas o demo. Al intentar ejecutar comandos como git fetch, git pull o git checkout, GitHub responde con un error de autenticación porque el token que se usaba anteriormente ya venció.
En muchos casos, aunque ya hayamos creado una llave SSH en el servidor, Git seguirá usando el token anterior si el repositorio todavía tiene configurada una URL remota con HTTPS.
Es decir, crear una llave SSH no cambia automáticamente la forma en que Git se conecta al repositorio. También debemos actualizar la URL remota del proyecto.
1. Revisar la URL remota actual
Primero debemos entrar a la carpeta del proyecto y revisar qué URL remota está usando Git.
cd /ruta/general/del/proyecto
git remote -vSi la respuesta muestra una URL similar a esta:
origin https://github.com/usuario/repositorio.git (fetch)
origin https://github.com/usuario/repositorio.git (push)significa que el proyecto todavía está usando HTTPS.
En algunos casos, incluso puede aparecer un token dentro de la URL, algo parecido a esto:
origin https://[email protected]/usuario/repositorio.gitEse es el escenario que debemos corregir.
2. Cambiar la URL remota de HTTPS a SSH
Para que Git use la llave SSH, debemos cambiar la URL remota del repositorio usando el comando git remote set-url.
git remote set-url origin [email protected]:usuario/repositorio.gitEste comando cambia el origen del repositorio para que Git deje de usar HTTPS y empiece a usar SSH.
Después podemos verificar nuevamente la configuración:
git remote -vLa salida esperada sería algo como:
origin [email protected]:usuario/repositorio.git (fetch)
origin [email protected]:usuario/repositorio.git (push)3. Probar la conexión SSH con GitHub
Antes de intentar descargar ramas o actualizar el proyecto, conviene probar que la llave SSH realmente esté funcionando.
ssh -T [email protected]Si la autenticación es correcta, GitHub responderá con un mensaje indicando que la conexión fue exitosa, aunque no permita acceso de shell. Esto es normal.
Una respuesta esperada puede ser similar a:
Hi usuario! You've successfully authenticated, but GitHub does not provide shell access.Con eso confirmamos que la autenticación SSH ya está funcionando.
4. Descargar información actualizada del repositorio
Una vez configurada la URL SSH, podemos ejecutar:
git fetch origin
Este comando descarga la información actualizada de las ramas remotas sin mezclar cambios todavía en la rama actual.
5. Cambiar a una rama remota
Si necesitamos crear una rama local a partir de una rama remota, podemos usar:
git checkout -b nombre-rama origin/nombre-ramaSin embargo, en proyectos reales puede aparecer un error indicando que un archivo local tiene cambios y que Git necesita sobrescribirlo para cambiar de rama.
Un caso común en Laravel puede ser un archivo como:
config/app.php6. ¿Por qué pasa este error?
Git protege los cambios locales para evitar que se pierdan accidentalmente. Si tenemos modificaciones en un archivo y la rama a la que queremos cambiar también modifica ese archivo, Git detiene el proceso.
A veces se intenta usar el comando assume-unchanged para que Git ignore temporalmente un archivo:
git update-index --assume-unchanged config/app.phpEste comando puede ayudar en algunos escenarios locales, pero no es una solución ideal para manejar archivos de configuración modificados en servidores o ambientes de demo.
Además, aunque un archivo esté marcado como assume-unchanged, Git aún puede bloquear operaciones si necesita proteger cambios locales antes de cambiar de rama.
7. Revisar si un archivo está marcado como assume-unchanged
Podemos revisar el estado del archivo con:
git ls-files -v config/app.phpSi el archivo aparece con una letra minúscula al inicio, significa que está marcado como assume-unchanged.
8. Quitar assume-unchanged
Antes de resolver el conflicto, es recomendable quitar esa marca para que Git vuelva a tratar el archivo normalmente.
git update-index --no-assume-unchanged config/app.php9. Opción segura: guardar temporalmente los cambios con stash
Si necesitamos conservar los cambios locales del archivo, podemos guardarlos temporalmente con git stash.
git stash push -m "Backup config app" -- config/app.phpDespués ya podemos intentar cambiar de rama:
git checkout -b nombre-rama origin/nombre-ramaY si necesitamos recuperar los cambios guardados:
git stash popSi al recuperar los cambios aparecen conflictos, deberán resolverse manualmente.
10. Opción rápida: descartar cambios locales
Si los cambios locales no son importantes, podemos descartarlos.
git restore config/app.phpDespués intentamos nuevamente cambiar de rama:
git checkout -b nombre-rama origin/nombre-ramaEsta opción debe usarse con cuidado, porque elimina los cambios locales del archivo.
11. Mejor práctica en Laravel: usar .env para configuración por ambiente
En Laravel, lo más recomendable es evitar modificar archivos como config/app.php directamente en cada servidor. Si una configuración cambia dependiendo del ambiente, lo ideal es manejarla desde el archivo .env.
Por ejemplo, en lugar de dejar un valor fijo dentro de config/app.php, podemos leerlo desde una variable de entorno:
'custom_product' => env('APP_CUSTOM_PRODUCT', false),Y en el archivo .env del servidor:
APP_CUSTOM_PRODUCT=trueDe esta manera cada ambiente puede tener su propia configuración sin modificar archivos versionados en Git.
12. Flujo recomendado completo
Un flujo seguro para este tipo de situación sería:
cd /ruta/general/del/proyecto
git remote -v
git remote set-url origin [email protected]:usuario/repositorio.git
git remote -v
ssh -T [email protected]
git fetch origin
git update-index --no-assume-unchanged config/app.php
git stash push -m "Backup config app" -- config/app.php
git checkout -b nombre-rama origin/nombre-ramaSi después necesitamos recuperar los cambios locales:
git stash popConclusión
Cuando un proyecto deja de autenticarse con GitHub porque venció un access token, una buena solución es migrar la conexión del repositorio a SSH. Para que esto funcione, no basta con crear la llave SSH: también debemos cambiar la URL remota del repositorio.
Además, si Git bloquea un cambio de rama por archivos modificados, debemos decidir si queremos conservar esos cambios con git stash o descartarlos con git restore.
En proyectos Laravel, la recomendación más limpia es mantener los archivos de configuración versionados sin modificaciones locales y mover los valores específicos de cada ambiente al archivo .env. Esto evita conflictos, mejora el flujo de despliegue y reduce errores al trabajar con ramas en Git.
Si necesitas ayuda para crear un proyecto de software en Maria Tech contamos con los expertos para apoyarte.
Deja un comentario