Cómo configurar un runner propio para GitHub Actions

Un self-hosted runner, o runner autoalojado, en GitHub Actions es una máquina propia del usuario que se conecta a GitHub para ejecutar en ella los trabajos de los flujos de trabajo, en contraposición a los runners alojados que proporciona la propia plataforma. Para entenderlo conviene recordar que en GitHub Actions un runner es simplemente la máquina donde se ejecutan los trabajos definidos en un flujo de trabajo, como compilar el código, ejecutar las pruebas o desplegar la aplicación. Por defecto, esos trabajos se ejecutan en runners alojados por GitHub, que son máquinas que la plataforma crea de forma automática y limpia para cada ejecución y destruye al terminar, sin que el usuario tenga que administrar nada, ocupándose GitHub del mantenimiento, los parches y las actualizaciones. Un self-hosted runner, en cambio, es una máquina que aporta y controla el propio usuario, ya sea un servidor físico, una máquina virtual o un contenedor, en la que se instala el software del runner y que se registra en GitHub para que quede a la escucha de trabajos y los ejecute cuando llegan. La diferencia fundamental es, por tanto, de quién es la máquina y quién la administra: en el caso alojado es de GitHub y no requiere gestión, mientras que en el caso autoalojado es del usuario, que asume la responsabilidad de mantener el sistema operativo, el software del runner y, muy especialmente, su seguridad. Además, a diferencia del runner alojado, que parte limpio en cada ejecución, el runner propio es persistente por defecto, conservando su estado entre ejecuciones salvo que se configure expresamente para ser efímero. El self-hosted runner permite cosas que el alojado no ofrece, como usar hardware específico, acceder a redes privadas o disponer de un entorno preconfigurado, pero a cambio de asumir su mantenimiento y de gestionar cuidadosamente su seguridad, ya que se convierte en una máquina propia que ejecuta el código que llega en los flujos de trabajo. Por ello, no es una opción mejor ni peor en abstracto, sino una respuesta a necesidades concretas que los runners alojados no cubren.

Conviene usar un runner propio autoalojado en lugar de los runners alojados por GitHub cuando existe una necesidad concreta que los runners alojados no pueden satisfacer, y no simplemente por costumbre o por la sensación de tener más control, ya que para la mayoría de los proyectos los runners alojados son la opción más cómoda y recomendable. Hay cuatro grandes situaciones que justifican un runner propio. La primera es la necesidad de hardware específico que los runners alojados no ofrecen, como unidades de procesamiento gráfico para tareas de aprendizaje automático o de cálculo intensivo, cantidades muy grandes de memoria, o una arquitectura de procesador concreta que se requiere para compilar o probar el software. La segunda es la necesidad de acceder a una red privada, por ejemplo cuando el flujo de trabajo debe desplegar a servidores internos de la organización que no son accesibles desde internet, algo que un runner alojado, al estar fuera de esa red, no puede hacer, mientras que un runner propio ubicado dentro de la red interna sí. La tercera es disponer de un entorno preparado con dependencias pesadas ya instaladas, de modo que no haya que reinstalarlas o reconstruirlas en cada ejecución, lo que puede ahorrar mucho tiempo cuando el entorno de compilación o de pruebas es grande y costoso de montar desde cero. La cuarta es el control de costes cuando el volumen de ejecuciones es muy elevado, situación en la que utilizar hardware propio puede resultar más económico que pagar por un consumo masivo de minutos en runners alojados. Fuera de estos casos, montar un runner propio no aporta ventajas y sí inconvenientes, porque añade una máquina que hay que mantener, actualizar y proteger, e introduce riesgos de seguridad que los runners alojados evitan al ser limpios y desechables. Por ello, la recomendación es utilizar por defecto los runners alojados y recurrir a los propios únicamente cuando se dé alguna de esas necesidades específicas, valorando en ese caso si compensan el coste de mantenimiento y las precauciones de seguridad que exigen.

Instalar y registrar un runner propio en GitHub Actions es un proceso relativamente sencillo que se realiza desde la configuración del repositorio o de la organización y que la propia plataforma guía paso a paso. El primer paso consiste en preparar la máquina que hará de runner, que puede ser un servidor físico, una máquina virtual o un contenedor, asegurándose de que tenga el sistema operativo y las dependencias que los trabajos vayan a necesitar, como las herramientas de compilación o los entornos de ejecución correspondientes. El segundo paso es obtener el comando de registro desde la configuración, navegando en el apartado de acciones a la sección de runners y eligiendo añadir un nuevo runner; allí GitHub muestra un conjunto de instrucciones específicas para el sistema operativo elegido, que incluyen un token de registro temporal. El tercer paso es ejecutar en la máquina esas instrucciones, que descargan el software del runner, lo configuran y lo registran contra el repositorio o la organización usando el token proporcionado, estableciendo así la conexión entre la máquina y GitHub. El cuarto paso, muy recomendable, es configurar el runner para que se ejecute como un servicio del sistema, de manera que arranque automáticamente y quede permanentemente a la escucha de trabajos sin necesidad de intervención manual, en lugar de tener que lanzarlo a mano cada vez. Una vez registrado y en marcha, el runner aparece disponible en la configuración y queda listo para recibir trabajos. El último paso es indicar en los flujos de trabajo que ciertos trabajos deben ejecutarse en el runner propio, lo cual se hace especificando en la definición del trabajo que se ejecute en un runner autoalojado, ya sea mediante la etiqueta general correspondiente o mediante etiquetas personalizadas que se pueden asignar al runner para dirigir hacia él trabajos concretos, algo útil cuando se tienen varios runners con características distintas. Aunque el proceso de instalación en sí es directo, conviene recordar que la parte verdaderamente importante y que requiere más atención no es la instalación, sino la seguridad del runner, especialmente si el repositorio es público, por lo que antes de poner un runner propio en producción hay que planificar cómo se va a aislar y proteger.

Un runner propio en un repositorio público es peligroso porque un runner ejecuta el código que llega en los flujos de trabajo, y en un repositorio público cualquier persona del mundo puede proponer cambios que podrían llegar a ejecutarse en la máquina propia, con el acceso que esta tenga a la red interna. Para entender el riesgo hay que recordar cómo funciona la colaboración en los repositorios públicos: cualquiera puede crear una propuesta de cambio, conocida como pull request, para contribuir al proyecto, y esa propuesta puede incluir modificaciones en el código e incluso en los propios flujos de trabajo. Si los flujos de trabajo se ejecutan en un runner autoalojado, una propuesta de cambio malintencionada podría contener código diseñado para hacer daño, que se ejecutaría directamente en la máquina del runner, es decir, en un servidor propio del usuario u organización. Esto significa que un atacante desconocido podría llegar a ejecutar comandos arbitrarios en esa máquina, robar información, moverse hacia otros sistemas accesibles desde la red interna en la que se encuentre el runner, o comprometer secretos y credenciales presentes en el entorno. El agravante es que, a diferencia de los runners alojados por GitHub, que son limpios y desechables y quedan aislados, un runner propio suele tener acceso a recursos internos y persistir su estado, lo que amplifica el daño potencial. Por todas estas razones, GitHub desaconseja explícitamente el uso de runners autoalojados en repositorios públicos. Si aun así resulta imprescindible usarlos en ese contexto, deben adoptarse medidas estrictas de aislamiento y mínima exposición: hacer los runners efímeros, de modo que se destruyan tras cada trabajo y no persista nada entre ejecuciones; evitar que tengan acceso a secretos sensibles o a redes internas críticas; concederles el mínimo privilegio posible; y considerar mecanismos que exijan aprobación antes de ejecutar flujos de trabajo procedentes de contribuciones externas. En repositorios privados el riesgo es sustancialmente menor, porque solo colaboradores de confianza pueden lanzar los flujos de trabajo, pero aun así el runner sigue siendo una puerta de entrada a la infraestructura que conviene endurecer con buenas prácticas de seguridad.

Un runner efímero es un runner autoalojado configurado para ejecutar un único trabajo y destruirse o restablecerse por completo después, de modo que no persiste estado alguno entre ejecuciones, a diferencia de un runner persistente, que permanece activo y conserva lo que quede en su sistema de una ejecución a la siguiente. La motivación para usar runners efímeros es fundamentalmente de seguridad y de fiabilidad, y responde a dos problemas de los runners persistentes. El primer problema es la contaminación entre ejecuciones: en un runner persistente, los archivos, procesos, cachés o cambios que deja un trabajo pueden afectar a los trabajos siguientes, provocando comportamientos inconsistentes, resultados que dependen del historial de la máquina o fallos difíciles de reproducir; un runner efímero, al partir siempre de un estado limpio, garantiza que cada trabajo se ejecute en un entorno predecible y sin residuos del anterior, igual que hacen los runners alojados por GitHub. El segundo problema, y más grave, es de seguridad: si un trabajo malicioso o comprometido logra ejecutarse en un runner persistente, puede dejar en la máquina puertas traseras, credenciales robadas, procesos ocultos o modificaciones que persistan y afecten a ejecuciones posteriores o comprometan de forma duradera el sistema; con un runner efímero, como la máquina se destruye y se recrea limpia tras cada trabajo, el margen de un atacante para persistir se reduce drásticamente, ya que cualquier daño desaparece al reiniciarse el entorno. Por estas razones, los runners efímeros son la práctica recomendada cuando se usan runners autoalojados, y resultan especialmente importantes en contextos de mayor riesgo, como los repositorios públicos, donde son una de las medidas clave de aislamiento. Habitualmente se implementan apoyándose en contenedores o en máquinas virtuales que se levantan para un trabajo y se eliminan al finalizar, a menudo mediante mecanismos de escalado automático que crean y destruyen runners según la demanda. En resumen, un runner efímero aporta limpieza y seguridad al asegurar que cada trabajo se ejecuta en un entorno nuevo y desechable, evitando tanto la contaminación entre ejecuciones como la persistencia de posibles compromisos.

No, un runner propio no reemplaza ni cambia los pipelines de GitHub Actions, sino que es simplemente una alternativa sobre dónde se ejecutan los trabajos de esos pipelines, conviviendo con todo lo demás sin alterarlo. Conviene distinguir claramente dos conceptos. Por un lado están los flujos de trabajo o pipelines de GitHub Actions, que son las definiciones de lo que hay que hacer, escritas en archivos de configuración dentro del repositorio, y que describen los trabajos y los pasos que los componen, como obtener el código, instalar dependencias, ejecutar pruebas, construir artefactos o desplegar; esa lógica es exactamente la misma independientemente de dónde se ejecute. Por otro lado está el runner, que es únicamente la máquina que ejecuta esos trabajos definidos en el pipeline. Elegir un runner propio en lugar de uno alojado por GitHub solo cambia el lugar y la máquina donde corre el trabajo, indicándolo en la definición del trabajo mediante la opción correspondiente, pero no modifica en absoluto cómo se escriben los flujos de trabajo, ni los pasos, ni la sintaxis, ni el funcionamiento general de GitHub Actions. De hecho, es perfectamente posible y habitual combinar ambos tipos de runner dentro de un mismo proyecto o incluso de un mismo flujo de trabajo, ejecutando por ejemplo la mayoría de los trabajos en runners alojados y reservando para un runner propio únicamente aquellos que necesitan hardware específico, acceso a una red privada o un entorno especial. Por tanto, aprender a usar un runner propio no sustituye el conocimiento de GitHub Actions ni de sus pipelines, sino que lo complementa, añadiendo la capacidad de dirigir determinados trabajos hacia máquinas propias cuando hay una necesidad concreta que lo justifique. La base sigue siendo entender bien los flujos de trabajo, los trabajos y los pasos de GitHub Actions, y el runner propio es una pieza adicional que se integra en ese marco para cubrir casos particulares, siempre teniendo presente que su uso exige asumir el mantenimiento de la máquina y unas precauciones de seguridad que los runners alojados no requieren.