Uno de los errores más comunes en proyectos de desarrollo consiste en subir accidentalmente información sensible a un repositorio Git. Credenciales, claves API, contraseñas, certificados o archivos de configuración pueden terminar formando parte del historial de commits y permanecer accesibles incluso después de ser eliminados de las versiones más recientes.
Para solucionar este problema, Git proporciona herramientas que permiten reescribir el historial del repositorio y eliminar completamente información confidencial. Entre ellas, git-filter-repo se ha convertido en la opción recomendada por la comunidad debido a su potencia, velocidad y facilidad de uso.
En este artículo exploraremos qué es git-filter-repo, cuándo utilizarlo y cómo eliminar información sensible de forma segura.
El problema de la información sensible en Git
Cuando un archivo se añade a un commit, Git almacena permanentemente esa versión dentro del historial.
Por ejemplo:
git add config.env
git commit -m «Add configuration file»
Aunque posteriormente eliminemos el archivo:
git rm config.env
git commit -m «Remove sensitive file»
la información sigue existiendo en commits anteriores.
Esto significa que cualquier persona con acceso al repositorio podría recuperar esos datos.
Riesgos asociados
La exposición accidental de información sensible puede provocar:
- acceso no autorizado a sistemas
- compromiso de bases de datos
- uso indebido de APIs
- filtración de datos corporativos
- incumplimiento normativo
Por ello es fundamental actuar rápidamente cuando ocurre este tipo de incidentes.
¿Qué es git-filter-repo?
git-filter-repo es una herramienta diseñada para reescribir el historial completo de un repositorio Git.
Permite:
- eliminar archivos
- modificar contenidos históricos
- renombrar rutas
- limpiar commits
- reducir tamaño del repositorio
Actualmente es la alternativa recomendada frente a herramientas más antiguas como:
- git filter-branch
- BFG Repo-Cleaner
Instalación de git-filter-repo
La instalación depende del sistema operativo.
En entornos Python:
pip install git-filter-repo
También puede instalarse mediante gestores de paquetes específicos según la plataforma.
Una vez instalado:
git filter-repo –help
permite verificar que la herramienta está disponible.
Eliminar un archivo sensible
Supongamos que accidentalmente se ha subido un archivo:
.env
Para eliminarlo completamente del historial:
git filter-repo –path .env –invert-paths
Esto elimina todas las apariciones históricas del archivo.
Eliminar múltiples archivos
También es posible eliminar varios archivos simultáneamente.
git filter-repo \
–path .env \
–path credentials.json \
–path secrets.txt \
–invert-paths
Esto limpia todos los archivos especificados.
Sustituir información sensible
En algunos casos interesa reemplazar información específica.
Por ejemplo:
API_KEY=123456
por:
API_KEY=REDACTED
Para ello puede utilizarse un archivo de reemplazo.
Ejemplo:
123456==>REDACTED
Ejecución:
git filter-repo –replace-text replacements.txt
Esto modifica todas las apariciones dentro del historial.
Reescritura del historial
Es importante entender que git-filter-repo modifica completamente los hashes de los commits.
Después de ejecutar la herramienta:
- el historial cambia
- los identificadores de commits cambian
- será necesario sincronizar nuevamente con el repositorio remoto
Por ello debe utilizarse con precaución.
Actualizar el repositorio remoto
Una vez finalizada la limpieza:
git push origin –force –all
Y posteriormente:
git push origin –force –tags
Esto reemplaza el historial existente en el servidor remoto.
Consideraciones para equipos
Cuando se reescribe el historial, todos los colaboradores deben sincronizar sus repositorios.
Normalmente se recomienda:
- informar al equipo
- coordinar la operación
- evitar commits simultáneos
- realizar copias de seguridad previas
Esto minimiza posibles conflictos.
GitHub y repositorios públicos
Si la información sensible estuvo disponible públicamente, eliminarla del historial puede no ser suficiente.
También es recomendable:
- revocar credenciales expuestas
- generar nuevas claves
- rotar contraseñas
- revisar accesos recientes
La limpieza del historial no garantiza que la información no haya sido copiada previamente.
Buenas prácticas para evitar incidentes
La mejor solución sigue siendo la prevención.
Algunas recomendaciones incluyen:
- utilizar .gitignore
- almacenar secretos en gestores seguros
- revisar cambios antes de hacer commit
- utilizar herramientas de detección de secretos
- implementar revisiones de código
Uso de .gitignore
Por ejemplo:
.env
*.pem
*.key
credentials.json
Esto evita que determinados archivos se añadan accidentalmente al repositorio.
Herramientas de detección automática
Existen soluciones que ayudan a detectar credenciales antes de subir código.
Algunas de las más utilizadas son:
- GitGuardian
- TruffleHog
- Gitleaks
- GitHub Secret Scanning
Estas herramientas añaden una capa adicional de protección.
Casos de uso habituales
git-filter-repo resulta especialmente útil para:
- eliminar credenciales expuestas
- limpiar archivos grandes innecesarios
- corregir errores históricos
- renombrar estructuras de directorios
- reducir tamaño del repositorio
Git y la seguridad en proyectos modernos
A medida que los equipos adoptan prácticas DevOps y CI/CD, la gestión segura del código se vuelve cada vez más importante.
La protección de secretos y credenciales debe formar parte de cualquier estrategia de desarrollo moderna.
Conclusión
La exposición accidental de información sensible en Git es un problema más común de lo que parece. Afortunadamente, herramientas como git-filter-repo permiten limpiar el historial del repositorio de forma eficiente y segura.
Comprender cómo funciona esta herramienta y aplicar buenas prácticas de gestión de secretos ayuda a proteger los proyectos, reducir riesgos de seguridad y mantener repositorios más limpios y profesionales.
