Qué NO Subir a GitHub: 10 Archivos que Debes Evitar

Escenarios como “recibir una notificación de AWS por facturación elevada después de un git push” o “ser advertido por un superior sobre la exposición de datos sensibles en un pull request” son problemáticos y, en ocasiones, muy reales en el desarrollo de software.

GitHub es una herramienta fundamental, pero su uso conlleva el riesgo inherente de exponer públicamente información que debe permanecer privada. La exposición accidental de datos sensibles es uno de los problemas listados en el famoso proyecto OWASP Top 10.

En este artículo, voy a detallarte qué no subir a GitHub, centrándome en 10 tipos de archivos que los ingenieros, sobre todo al iniciar, tienden a incluir por error.

Entender esto es clave para la seguridad en repositorios Git. La correcta configuración del archivo .gitignore es una medida esencial para proteger la seguridad de los proyectos y la infraestructura asociada.

Nunca debes subir a GitHub archivos que contengan información sensible: Esto incluye credenciales como claves de API o contraseñas en archivos .env, claves SSH (id_rsa), archivos de configuración de proveedores de nube (AWS, GCP), y dumps de bases de datos. Tampoco se deben subir dependencias (node_modules) ni artefactos de compilación (dist/, build/).

Archivos de Alto Riesgo: Protege tus Credenciales en GitHub

Esta sección cubre los archivos sensibles en repositorios GitHub cuya exposición accidental puede tener consecuencias graves.

1. Archivo .env

Nivel de Riesgo: Crítico

Este archivo se utiliza para gestionar variables de entorno y frecuentemente contiene información sensible como claves de API, contraseñas de bases de datos y claves privadas.

Si se sube a un repositorio público, se podría producir una grave filtración de secretos en repositorios, ya que bots automatizados pueden detectar y extraer estas credenciales en segundos para lanzar instancias de alto costo o acceder a datos privados. Siempre deben estar incluidos en el archivo .gitignore.

Recomendación Técnica: Crear un archivo .env.example

Al excluir .env, otros miembros del equipo pueden no saber qué variables de entorno son necesarias. Para solucionar esto, la recomendación es crear y subir un archivo .env.example que contenga únicamente los nombres de las claves, sin sus valores (ej: API_KEY=). Esto facilita la configuración del entorno para los colaboradores y sigue el principio de separar la configuración del código.

2. Archivos de autenticación de proveedores de nube (AWS / GCP / Azure) y herramientas de infraestructura

Nivel de Riesgo: Crítico

• credentials.csv
• google-service-account.json
• aws_access_key_id
• .aws/credentials
• .aws/config
• .azure/
• .gcloud/
• terraform.tfstate

Aunque codificar credenciales directamente en el código fuente es una práctica inaceptable, un error común es colocar los archivos de claves descargados o archivos de estado de infraestructura en la carpeta del proyecto y añadirlos accidentalmente con un git add ..

Estos archivos pueden contener tokens, secretos o metadatos sensibles de la infraestructura.

3. Claves SSH (clave privada)

Nivel de Riesgo: Crítico

• id_rsa
• *.pem

Estos archivos representan el acceso directo a los servidores. Publicarlos es el equivalente a distribuir copias de la llave de acceso a la infraestructura. Nunca deben ser incluidos en un repositorio GitHub.

4. Dumps de bases de datos o archivos de datos

Nivel de Riesgo: Elevado

• db.sqlite3
• dump.sql
• terraform.tfstate
• *.tfstate
• *.tfstate.backup

Aunque se pueda pensar que solo contienen datos de prueba, es común que incluyan datos de producción, secretos de infraestructura o información personal identificable (PII).

Su exposición puede generar riesgos de seguridad y cumplimiento normativo. Además, los archivos binarios, de gran tamaño o estados de infraestructura no son adecuados para la gestión de versiones con Git.

Archivos que Generan Ruido y Dificultan la Colaboración

Esta sección cubre archivos que, si bien no representan un riesgo de seguridad directo, afectan negativamente la calidad y legibilidad del repositorio.

5. Carpeta node_modules

Impacto en el Repositorio: Muy Alto

Contiene el conjunto de librerías de las que depende un proyecto Node.js. Subir esta carpeta incrementa drásticamente el tamaño del repositorio y la cantidad de archivos, dificultando la revisión de cambios.

Los archivos package.json y package-lock.json son suficientes para reconstruir las dependencias ejecutando npm install.

6. Archivos generados por el sistema operativo

Impacto en el Repositorio: Moderado

• .DS_Store (Mac)
• Thumbs.db (Windows)

Son archivos de configuración de vista o miniaturas generados automáticamente por el sistema operativo. Su inclusión en los commits añade ruido innecesario al historial de cambios.

Recomendación Técnica: Configurar un archivo .gitignore global

Para evitar añadir estas exclusiones en cada proyecto, es más eficiente configurar un archivo global:

1. Crea un archivo ~/.gitignore_global en el directorio home.
2. Añade las reglas de exclusión (ej: .DS_Store).
3. Ejecuta el comando git config --global core.excludesfile ~/.gitignore_global.

Esto aplicará las reglas a todos los repositorios Git en el sistema.

7. Archivos de configuración del editor/IDE

Impacto en el Repositorio: Bajo

• .vscode/ (con excepción de configuraciones compartidas)
• .idea/

Las configuraciones personales del editor no deben ser impuestas al resto del equipo. Es aceptable compartir configuraciones específicas del proyecto (ej: en .vscode/settings.json), pero las configuraciones de usuario deben ser excluidas.

8. Artefactos de compilación y archivos compilados

Impacto en el Repositorio: Alto

• dist/
• build/
• __pycache__/
• *.class
• *.o

Los archivos que pueden ser generados a partir del código fuente no deben ser versionados. Su inclusión provoca grandes diferencias en los commits por cambios mínimos en el código y aumenta innecesariamente el peso del repositorio.

9. Archivos de registro (logs)

Impacto en el Repositorio: Moderado

• *.log
• npm-debug.log

Los registros de ejecución o errores son específicos del entorno de desarrollo local de un programador y no aportan valor al resto del equipo.

10. Notas personales, listas de tareas y archivos con credenciales hardcodeadas

Impacto en el Repositorio: Bajo (pero con posible riesgo de seguridad)

• memo.txt
• todo.md (borradores personales)
• archivos con tokens o claves embebidas en el código

Aunque los documentos del proyecto son bienvenidos, archivos con notas personales pueden ser subidos por error.

Además, es frecuente que desarrolladores guarden temporalmente tokens o claves dentro del código fuente para pruebas, lo que introduce un riesgo real de exposición si se versiona el archivo.

Cómo Usar .gitignore para una Mayor Seguridad

El archivo .gitignore, ubicado en el directorio raíz del proyecto, se utiliza para especificar los archivos y directorios que Git debe ignorar. Puedes consultar la documentación oficial para ver todas sus capacidades.

A continuación, un ejemplo de configuración de gitignore para seguridad:

# Seguridad (alto riesgo)
.env
*.env.*
*.pem
*.key
id_rsa
*.tfstate
*.tfstate.*

# Sistema Operativo (si no usas config global)
.DS_Store
Thumbs.db

# Dependencias y artefactos de compilación
node_modules/
dist/
build/
__pycache__/
*.pyc
venv/
.venv/

# Logs y bases de datos locales
*.log
*.sqlite3

Herramientas recomendadas

Para generar un archivo .gitignore optimizado, recomiendo el uso de gitignore.io. Esta herramienta permite generar un archivo completo especificando el sistema operativo (macOS, Windows), lenguajes (Node, Python, Java) y frameworks utilizados.

También puedes encontrar plantillas listas para usar en este repositorio oficial de GitHub.

¿Ya Subiste un Secreto? Cómo Eliminar Datos Sensibles de Git

Si ya has subido un archivo con información crítica (como .env), eliminarlo y hacer un nuevo commit no es suficiente. La información permanecerá en el historial de Git.

1. Acción Inmediata: Invalidar las credenciales expuestas

Antes que nada, es imperativo invalidar y regenerar todas las claves de API, contraseñas y certificados que fueron expuestos. Los atacantes utilizan bots que escanean repositorios públicos y pueden explotar las credenciales en cuestión de segundos.

Nota Técnica: Escaneo de secretos y push protection

GitHub y los principales proveedores de nube (AWS, etc.) tienen funcionalidades de “Secret Scanning” que monitorizan repositorios públicos en busca de credenciales expuestas.

Si recibes una notificación de GitHub o de tu proveedor de nube, es una señal de que este sistema ha funcionado. Sigue las instrucciones proporcionadas para mitigar el riesgo.

GitHub también dispone de Push Protection que reduce significativamente fugas antes de que lleguen al repositorio.

2. Eliminación permanente del historial

Es necesario reescribir el historial de Git para eliminar por completo el archivo.

El uso de git filter-branch está obsoleto por ser lento y propenso a errores. Las herramientas recomendadas actualmente son:

• git-filter-repo (Recomendado): Herramienta escrita en Python, rápida y la opción oficial recomendada por Git.
• BFG Repo-Cleaner: Herramienta escrita en Java, popular por su simplicidad y facilidad de uso.

Solución para casos no colaborativos (principiantes):

Si la manipulación del historial resulta compleja y el repositorio es personal (sin colaboradores), la opción más segura y definitiva puede ser eliminar el repositorio por completo y crearlo de nuevo desde cero con el historial limpio.

Para profundizar, puedes consultar mi guía sobre los comandos básicos de Git que debes conocer.

Finalmente

Git es una herramienta para registrar el historial de cambios, no para archivar secretos. Mantener un repositorio limpio y bien configurado es un paso fundamental para prevenir errores de seguridad y facilitar la colaboración en equipo. Mi recomendación es verificar y actualizar el archivo .gitignore de forma proactiva.

¡Que tengas una vida segura y feliz en GitHub!

Nota: Se ha señalado que en ciertos casos de uso, como con Marp, puede ser necesario compartir archivos que normalmente serían excluidos. Esto subraya la importancia de evaluar las necesidades específicas de cada proyecto.