Gestión de secretos de GitHub Actions: protege las claves de API y las contraseñas en los flujos de trabajo

By Mirko Peters · 2026-10-26

Aprende a proteger tus canalizaciones de CI/CD usando correctamente los secretos de GitHub Actions. Descubre las mejores prácticas para gestionar claves de API y tokens de acceso de forma segura.

Automatically translated with AI from the original post. Read the English original

Cuando tu automatización se ejecuta completamente desatendida en la nube, mantener seguras tus credenciales es fundamental. Gestionar bien los secretos de GitHub Actions garantiza que tus claves de API, contraseñas de implementación y tokens de acceso permanezcan fuera del código fuente, pero siguen siendo fácilmente accesibles para los flujos de trabajo que los necesitan para compilar y publicar tus proyectos.

Puntos clave

• Nunca incluyas contraseñas, claves de API ni tokens de acceso sensibles directamente en tus archivos YAML de flujos de trabajo.
• GitHub ofrece tres niveles de secretos: secretos de repositorio, secretos de organización y secretos de entorno.
• Los secretos se cifran antes de llegar a GitHub y se enmascaran automáticamente dentro de los registros de ejecución.
• Los secretos de entorno pueden exigir una aprobación humana antes de que las credenciales de implementación estén disponibles para un trabajo.
• Aplica siempre el principio de mínimo privilegio, concediendo a cada secreto el conjunto más pequeño de permisos necesario.

Por qué fallan las credenciales en texto plano en CI/CD

Para los desarrolladores que tienen prisa por configurar una nueva canalización, es tentador pegar una clave de API directamente en el archivo de configuración del flujo de trabajo. Al fin y al cabo, si el flujo de trabajo es privado, ¿quién va a verlo? Esta mentalidad introduce vulnerabilidades de seguridad graves. Los archivos de flujo de trabajo están controlados por versiones, lo que significa que cada revisión histórica, cada commit y cada rama conserva un registro permanente de todo lo escrito en esos documentos YAML.

Además, los repositorios a menudo cambian sus permisos, pasan de privados a públicos o son bifurcados por colaboradores. Si tus credenciales viven como cadenas de texto plano en tus archivos de configuración, un único error de permisos puede exponer todo tu entorno de producción. Tratar tus archivos de configuración únicamente como instrucciones, y guardar los datos sensibles en una bóveda cifrada y desacoplada, es la regla fundamental de la seguridad moderna en la nube.

Los tres niveles de secretos de GitHub

GitHub reconoce que las distintas credenciales tienen distintos ámbitos. Para ayudar a los desarrolladores a gestionar el control de acceso de forma eficiente, la plataforma permite configurar secretos en tres niveles organizativos diferentes.

Secretos a nivel de repositorio

Los secretos de repositorio pertenecen exclusivamente a un único proyecto. Si estás creando una aplicación independiente o gestionando un único complemento, un secreto de repositorio mantiene tus cadenas de conexión y tokens de implementación vinculados a ese espacio de trabajo concreto. Otros proyectos de tu organización no pueden acceder a ellos.

Secretos a nivel de organización

Cuando varios repositorios de una empresa necesitan acceder a los mismos recursos compartidos, como un registro de contenedores central o un certificado empresarial de firma de código, los secretos de organización te evitan duplicar entradas. Los administradores pueden definir directivas y elegir los repositorios o equipos específicos que pueden heredar estas credenciales de ámbito organizativo.

Secretos a nivel de entorno

Los secretos de entorno vinculan las credenciales a destinos de implementación concretos, como los entornos de preproducción o producción. Aquí es donde guardas las claves necesarias para acceder a sistemas en producción. Y, lo que es fundamental, los secretos de entorno permiten configurar revisores obligatorios, de modo que una persona deba aprobar manualmente una ejecución de implementación antes de que las credenciales de producción se desbloqueen y se entreguen al runner.

Cómo GitHub protege tus datos en tránsito

La seguridad no se limita a dónde se almacenan los secretos, sino también a cómo viajan durante la ejecución. Los secretos se cifran en tu equipo local antes de transmitirse a GitHub, de modo que nunca se envían en texto plano por la red. Una vez almacenados, permanecen completamente ocultos en la interfaz de configuración del repositorio.

Cuando se ejecuta un flujo de trabajo, debes pasar explícitamente un secreto a un paso o a una acción por su nombre, usando una sintaxis de expresión como ${{ secrets.DATABASE_URL } }. Esto significa que una acción de terceros maliciosa o descuidada del Marketplace no puede apropiarse automáticamente de todas las credenciales de tu repositorio: solo recibe lo que le entregas de forma explícita.

Además, GitHub analiza automáticamente los registros de salida de los trabajos para enmascarar las cadenas confidenciales. Si tu script muestra accidentalmente un valor secreto en la consola, GitHub intenta sustituir los caracteres por asteriscos. Sin embargo, como los scripts pueden manipular o codificar las cadenas antes de imprimirlas, confiar únicamente en el enmascaramiento de registros no sustituye a escribir código seguro.

Mejores prácticas para la automatización segura

Implementar una gestión sólida de secretos en GitHub Actions requiere adoptar hábitos concretos en el día a día. En primer lugar, distingue siempre entre un valor de configuración y un secreto. Si un valor es simplemente una dirección pública de sitio web, el nombre de un entorno o una marca de función no sensible, mantenlo en texto plano dentro de tu archivo YAML para que tu equipo pueda entender fácilmente cómo funciona la canalización. Reserva la funcionalidad de secretos exclusivamente para los datos que deben permanecer confidenciales.

En segundo lugar, aplica el principio de mínimo privilegio. Genera tokens de acceso de grano fino con las fechas de caducidad más cortas posibles y el alcance de permisos más reducido. Si un token de implementación solo necesita escribir en un bucket concreto de S3, no le concedas derechos administrativos sobre toda tu infraestructura en la nube.

Conclusión

Dominar la gestión de secretos de GitHub Actions convierte tus canalizaciones de CI/CD, de posibles riesgos de seguridad, en motores de automatización sólidos y de nivel empresarial. Al separar tus credenciales de tu código y aprovechar controles de acceso multinivel, puedes entregar software con rapidez sin sacrificar la seguridad.

Para explorar los fundamentos de la creación de flujos de trabajo automatizados, consulta Escucha el episodio completo. ¡Sintoniza la discusión completa para aprender más sobre la configuración de desencadenadores, trabajos y runners para tu entorno cloud moderno!

Preguntas frecuentes

¿Puedo leer un secreto de GitHub Actions en un pull request desde un fork?

De forma predeterminada, GitHub impide que los pull requests de colaboradores externos (forks) accedan a los secretos de tu repositorio, para evitar que se ejecute código malicioso y se roben tus credenciales.

¿Cómo paso un secreto desde un flujo de trabajo a un paso concreto?

Pasas los secretos al flujo de trabajo usando el contexto 'env' dentro de un paso o trabajo, asignando el secreto de GitHub a una variable de entorno, por ejemplo env: API_KEY: ${{ secrets.MY_API_KEY } }.

¿Están garantizados los secretos de GitHub Actions para permanecer ocultos en los registros?

GitHub enmascara automáticamente los valores secretos conocidos en los registros de ejecución, pero esto no es una garantía absoluta. Si un valor secreto se manipula, codifica o transforma antes de imprimirse, partes de él podrían quedar expuestas.

¿Cuál es la diferencia entre los secretos de repositorio y los secretos de entorno?

Los secretos de repositorio están disponibles para cualquier flujo de trabajo de un repositorio determinado, mientras que los secretos de entorno están vinculados a entornos de implementación específicos (como preproducción o producción) y pueden requerir aprobaciones de revisión manual.