Implementación paso a paso de pipelines GitHub Actions para detección y prevención de secretos con Gitleaks
Introducción
El filtrado accidental de credenciales, tokens API o claves privadas es una de las vulnerabilidades más comunes en entornos de desarrollo. Cuando un secreto se compromete, el daño puede ser inmediato: acceso no autorizado a bases de datos, servicios en la nube o infraestructuras críticas. Para mitigar este riesgo, es esencial integrar la detección de secretos en el proceso de integración continua (CI) y aplicar políticas de bloqueo automático antes de que el código llegue a la rama main o master.
En este artículo vamos a crear, desde cero, un pipeline de GitHub Actions que utilice Gitleaks, una herramienta de código abierto especializada en escanear repositorios en busca de patrones de secretos. Veremos cómo:
- Instalar y configurar Gitleaks en el workflow.
- Definir una política de detección (regex, palabras clave, etc.).
- Abortar automáticamente el push o pull request cuando se detecte un secreto.
- Generar reportes legibles y opcionalmente abrir un issue de remediación.
1. Preparación del entorno
1.1. Requisitos previos
Antes de crear el workflow, asegúrate de contar con:
- Una cuenta en GitHub con permisos de administrador en el repositorio.
- Git instalado localmente (
git --version). - Acceso a la rama
mainomasterdonde se aplicarán las políticas. - Conocimiento básico de YAML.
1.2. Crear la carpeta .github/workflows
GitHub busca los archivos de workflow dentro del directorio .github/workflows. Si no existe, créalo:
mkdir -p .github/workflows
1.3. Definir la política de Gitleaks
Gitleaks permite usar una configuración JSON o TOML. Vamos a crear un archivo llamado .gitleaks.toml en la raíz del proyecto. Este fichero contiene los patrones que queremos detectar:
title = "política de detección de secretos"
[[rules]]
description = "AWS Access Key"
regex = '''AKIA[0-9A-Z]{16}'''
tags = ["AWS", "key"]
[[rules]]
description = "Token de Slack"
regex = '''xox[baprs]-[0-9A-Za-z]{10,48}'''
tags = ["slack"]
[[allowlist]]
description = "Archivos de pruebas que contienen claves dummy"
regex = '''test_.*\.txt'''
Este fichero será leído por Gitleaks en cada ejecución del pipeline.
2. Creación del workflow de GitHub Actions
2.1. Archivo secret-scan.yml
Dentro de .github/workflows, crea el archivo secret-scan.yml con el siguiente contenido:
name: "Escaneo de secretos con Gitleaks"on: push: branches: [ main, master ] pull_request: branches: [ main, master ]
jobs: gitleaks-scan: runs-on: ubuntu-latest permissions: contents: read issues: write # Necesario si queremos crear un issue automáticamente steps: - name: Checkout del código uses: actions/checkout@v4 with: fetch-depth: 0 # Necesario para que Gitleaks analice todo el historial
- name: Instalar Gitleaks run: | curl -sSL https://github.com/gitleaks/gitleaks/releases/download/v8.18.2/gitleaks_8.18.2_linux_x64.tar.gz -o gitleaks chmod +x gitleaks sudo mv gitleaks /usr/local/bin/ - name: Ejecutar escaneo id: gitleaks run: | gitleaks detect --config=.gitleaks.toml --source=. --redact --report-format=json --output=gitleaks-report.json || true - name: Analizar resultados run: | if [ -s gitleaks-report.json ]; then echo "🔴 Se detectaron secretos" cat gitleaks-report.json exit 1 # Fuerza el fallo del job else echo "✅ No se encontraron secretos" fi - name: Crear issue de remediación (opcional) if: failure() uses: actions/github-script@v7 with: script: | const fs = require('fs'); const report = JSON.parse(fs.readFileSync('gitleaks-report.json', 'utf8')); const body = report.map(r => `- **${r.RuleID}** en \`${r.File}\` línea ${r.StartLine}`).join("\n"); github.rest.issues.create({ owner: context.repo.owner, repo: context.repo.repo, title: "🔐 Secret(s) detectado(s) - Acción requerida", body: `Se encontraron los siguientes secretos:\n${body}\n\nPor favor, revíselos y elimine los valores expuestos.`, labels: ["security","gitleaks"] });
2.2. Explicación paso a paso
- on: El workflow se dispara en push y pull request contra
main/master. - checkout: Necesitamos el historial completo (
fetch-depth: 0) porque Gitleaks revisa todos los commits. - Instalar Gitleaks: Descargamos la versión binaria oficial y la movemos a
/usr/local/binpara que esté en$PATH. - Ejecutar escaneo: Usamos la configuración personalizada y generamos un reporte JSON. El comando termina con
|| truepara que el paso no falle automáticamente; controlamos el resultado después. - Analizar resultados: Si el archivo de reporte tiene contenido (
-s), se imprime y se aborta el job conexit 1. De lo contrario, el pipeline continúa con éxito. - Crear issue: Solo se ejecuta cuando el job falla (
if: failure()). Usaactions/github-scriptpara abrir un issue con la lista de secretos encontrados.
3. Políticas de bloqueo y buenas prácticas
3.1. Rechazo automático de pushes
GitHub permite establecer branch protection rules. Después de crear el workflow, habilita la regla “Require status checks to pass before merging” y selecciona “Escaneo de secretos con Gitleaks”. De esta forma, cualquier pull request que falle el escaneo será bloqueado y no podrá ser fusionado.
3.2. Uso de secretos de GitHub para credenciales de escaneo
Si tu organización necesita autenticar a Gitleaks contra un escáner externo (por ejemplo, un API de detección de código), almacena esas credenciales como GitHub Secrets y accede a ellas mediante ${{ secrets.NOMBRE }}. Nunca incluyas valores sensibles directamente en el repositorio.
3.3. Mantener actualizada la lista de reglas
Los atacantes crean nuevos patrones constantemente. Programa una tarea mensual que actualice .gitleaks.toml con los últimos reglas oficiales y realice un push automático.
4. Troubleshooting y errores comunes
4.1. Error: gitleaks: command not found
Posibles causas:
- El paso de instalación falló (por ejemplo, URL incorrecta). Verifica la salida del job.
- El binario no tiene permisos de ejecución. Asegúrate de ejecutar
chmod +x gitleaks.
Solución rápida: reemplaza el bloque de instalación por la acción oficial de Gitleaks:
- name: Setup Gitleaks
uses: gitleaks/gitleaks-action@v2
with:
config_path: .gitleaks.toml
4.2. Error: No se encontraron secretos pero el pipeline sigue fallando
Esto suele ocurrir cuando el archivo de reporte está vacío pero el comando exit 1 se ejecuta de forma prematura. Revisa la condición del paso Analizar resultados. Debe ser:
if [ -s gitleaks-report.json ]; then
# falla
else
# éxito
fi
Asegúrate de que -s (size) esté presente; -f (file exists) no es suficiente.
4.3. Error: Permission denied (publickey) al crear el issue
La acción github-script necesita permiso issues: write. Verifica la sección permissions: del job y, si usas un token personalizado, que esté asignado al secret GITHUB_TOKEN con los alcances correctos.
4.4. Falsos positivos recurrentes
Si ciertas coincidencias son intencionales (por ejemplo, claves de prueba), añádelas a la sección [[allowlist]] del archivo .gitleaks.toml. Usa expresiones regulares que identifiquen sólo los archivos o patrones permitidos.
Conclusión
Integrar Gitleaks en un pipeline de GitHub Actions brinda una capa esencial de defensa contra la exposición accidental de secretos. La solución mostrada:
- Escanea cada push y pull request contra una política definida.
- Bloquea automáticamente la rama protegida cuando se detecta un secreto.
- Genera reportes claros y abre issues de remediación para acelerar la respuesta.
- Se adapta fácilmente a nuevas reglas y a los requisitos de compliance de la organización.
Implementar este flujo de trabajo no solo reduce el riesgo de brechas de seguridad, sino que también fomenta una cultura de “security‑by‑design” entre los desarrolladores. Mantén tu archivo .gitleaks.toml actualizado, revisa periódicamente las protecciones de rama y, sobre todo, educa al equipo sobre la importancia de no incluir credenciales en el código fuente.