Referencia de ejecutores autohospedados

Requisitos para máquinas de ejecutores autoalojados

Puedes usar una máquina como ejecutor autohospedado, siempre que cumpla con estos requisitos:

Puedes instalar y ejecutar la aplicación del ejecutor autoalojado en la máquina. Consulta Sistemas operativos compatibles y Arquitecturas de procesador compatibles.
La máquina puede comunicarse con GitHub Actions.
La máquina tiene suficientes recursos de hardware para el tipo de flujos de trabajo que planeas ejecutar. La propia aplicación del ejecutor autoalojado solo requiere unos recursos mínimos.
Si quieres ejecutar flujos de trabajo que usan acciones del contenedor Docker o contenedores de servicio, debes usar una máquina Linux y Docker debe estar instalado.

Sistemas operativos admitidos

Linux

Red Hat Enterprise Linux 8 o superior
CentOS 8 o superior
Oracle Linux 8 o posterior
Fedora 29 o posterior
Debian 10 o posterior
Ubuntu 20.04 o posterior
Linux Mint 20 o posterior
openSUSE 15.2 o posterior
SUSE Enterprise Linux (SLES) 15 SP2 o posterior

Windows

Windows 10 de 64 bits
Windows 11 de 64 bits
Windows Server 2016 de 64 bits
Windows Server 2019 de 64 bits
Windows Server 2022 de 64 bits

Arquitecturas de procesador admitidas

x64: Linux, macOS, Windows.
ARM64: Linux, macOS.
ARM32: Linux.

Precedencia de enrutamiento para los ejecutores auto-hospedados

Al enrutar un trabajo a un ejecutor autohospedado, GitHub busca un ejecutor que coincida con las etiquetas y grupos del runs-on trabajo:

Si GitHub encuentra un ejecutor en línea e inactivo que coincida con las etiquetas y los grupos de runs-on, el trabajo se asigna al ejecutor y se le envía.
- Si ele ejecutor no recoge el job asignado en 60 segundos, este volverá a ponerse en cola para que el ejecutor nuevo pueda aceptarlo.
Si GitHub no encuentra un ejecutor en línea e inactivo que coincida con las etiquetas y grupos del runs-on trabajo, el trabajo permanecerá en cola hasta que un ejecutor aparezca en línea.
Si el job permanece en cola por más de 24 horas, este fallará.

El escalado automático permite ajustar dinámicamente el número de ejecutores autohospedados en función de la demanda. Esto ayuda a optimizar el uso de recursos y garantiza una capacidad de ejecutor suficiente durante las horas punta, al tiempo que reduce los costos durante períodos de baja actividad. Hay varios enfoques para implementar el escalado automático para los ejecutores autohospedados, cada uno con diferentes ventajas en cuanto a complejidad, fiabilidad y capacidad de respuesta.

Actions Runner Controller

Actions Runner Controller (ARC) es la implementación de referencia de las API de conjuntos de escalado de GitHub y la solución recomendada basada en Kubernetes para el escalado automático de ejecutores autogestionados. ARC proporciona una solución completa de escalado automático, lista para su uso en producción, para equipos que ejecutan GitHub Actions en entornos de Kubernetes.

GitHub recomienda ARC para organizaciones con infraestructura y equipos de Kubernetes que tengan experiencia en Kubernetes. ARC controla el ciclo de vida completo de los ejecutores dentro del clúster, desde el aprovisionamiento hasta la ejecución del trabajo y la limpieza.

Para más información, consulta Controlador del ejecutor de acciones y Compatibilidad con Actions Runner Controller.

GitHub Actions Cliente del conjunto de escalado de ejecutores

El GitHub Actions Runner Scale Set Client es un módulo independiente basado en Go que permite a los equipos de plataforma, integradores e proveedores de infraestructura crear soluciones de escalado automático personalizadas para GitHub Actions ejecutores en máquinas virtuales, contenedores, infraestructura local y servicios en la nube, con compatibilidad con plataformas Windows, Linux y macOS.

El cliente orquesta las interacciones con la API para los conjuntos de escalado GitHub y deja en sus manos el aprovisionamiento de la infraestructura. El usuario define cómo se crean, escalan y destruyen los ejecutores y configura los ejecutores con varias etiquetas para la asignación y el enrutamiento flexibles de los trabajos. Esto proporciona a las organizaciones un control pormenorizado sobre la administración del ciclo de vida del ejecutor y la telemetría en tiempo real para la ejecución del trabajo.

El cliente está diseñado para trabajar de forma rápida con configuraciones básicas, lo que permite a los equipos implementar rápidamente el escalado automático. Sin embargo, su verdadero poder radica en su flexibilidad: el cliente se ha creado para ampliarse y personalizarse para satisfacer los requisitos de infraestructura, las restricciones de cumplimiento y los flujos de trabajo operativos específicos de cada organización. Tanto si necesita una lógica de escalado simple como estrategias de aprovisionamiento complejas y de varios entornos, el cliente se adapta a sus necesidades.

El GitHub Actions Runner Scale Set Client es un proyecto de código abierto. El repositorio actions/scaleset contiene el código fuente completo, la documentación completa y ejemplos prácticos que le ayudarán a empezar. Encontrará guías de implementación, configuraciones de ejemplo para varios escenarios de infraestructura y arquitecturas de referencia que muestran cómo integrar el cliente con diferentes sistemas de aprovisionamiento. El repositorio también incluye directrices de contribución para los equipos interesados en ampliar el cliente o compartir sus patrones de escalado automático con la comunidad.

Nota: El cliente del grupo de escalado de ejecutores no sustituye a Actions Runner Controller (ARC), que sigue siendo la implementación de referencia de las API del grupo de escalado y la solución recomendada para Kubernetes para el escalado automático de ejecutores. En su lugar, el cliente es una herramienta complementaria para interactuar con las mismas API del conjunto de escalado para crear soluciones de escalado automático personalizadas fuera de Kubernetes.

Ejecutores efímeros para el escalado automático

GitHub recomienda implementar el escalado automático con ejecutores autohospedados efímeros; No se recomienda el escalado automático con ejecutores autohospedados persistentes. En determinados casos, GitHub no puede garantizar que las tareas no se asignen a ejecutores persistentes mientras se están apagando. Con los runners efímeros, esto se puede garantizar porque GitHub solo asigna una tarea a un runner.

Este acercamiento te permite administrar tus ejecutores como sistemas efímeros, ya que puedes utilizar la automatización para proporcionar un ambiente limpio para cada job. Esto ayuda a limitar la exposición de cualquier recurso sensible de los jobs anteriores y también ayuda a mitigar el riesgo de un ejecutor puesto en riesgo que esté recibiendo jobs nuevos.

Advertencia

Los archivos de registro de aplicaciones del ejecutor para ejecutores efímeros deben reenviarse a una solución de almacenamiento de registros externa para solucionar problemas y diagnósticos. Aunque no es necesario que los ejecutores efímeros se implementen, GitHub recomienda garantizar que los registros del ejecutor se reenvíen y conserven externamente antes de implementar una solución de escalado automático de ejecutores efímeros en un entorno de producción. Para más información, consulta Supervisión y solución de problemas de ejecutores autohospedados.

Para agregar un ejecutor efímero a su entorno, incluya el parámetro --ephemeral al registrar el ejecutor mediante config.sh. Por ejemplo:

./config.sh --url https://github.com/octo-org --token example-token --ephemeral

A continuación, el servicio GitHub Actions dará de baja automáticamente al ejecutor después de procesar una tarea. Entonces podrás crear tu propia automatización que elimine el ejecutor después de que se desregistró.

Nota:

Si un trabajo se etiqueta para algún tipo de ejecutor, pero no hay ninguno disponible que coincida con esas características, el trabajo no fallará inmediatamente en el momento de ponerse en cola. En vez de esto, el job permanecerá en cola hasta que venza el tiempo límite de 24 horas.

Como alternativa, puedes crear ejecutores efímeros y Just-In-Time mediante la API REST. Para más información, consulta Puntos de conexión de API de REST para ejecutores autohospedados.

Actualizaciones de software del ejecutor en ejecutores autohospedados

Predeterminadamente, los ejecutores auto-hospedados realizan una actualización de software cuando una versión nueva del software ejecutor esté disponible. Si usas ejecutores efímeros en contenedores, esto podría ocasionar que existieran actualizaciones de software repetidas cuando se lance una versión nueva del ejecutor. El apagar las actualizaciones automáticas te permite actualizar la versión del ejecutor directamente en la imagen del contenedor en tu propia programación de tiempos.

Para desactivar las actualizaciones automáticas de software e instalar las actualizaciones de software usted mismo, especifique la marca --disableupdate al registrar el ejecutor mediante config.sh. Por ejemplo:

./config.sh --url https://github.com/YOUR-ORGANIZATION --token EXAMPLE-TOKEN --disableupdate

Si inhabilitas las actualizaciones automáticas, aún debes actualizar tu versión de ejecutor con frecuencia. La nueva funcionalidad en GitHub Actions requiere cambios tanto en el servicio GitHub Actions_como_ en el software del ejecutor. Es posible que el ejecutor no pueda procesar correctamente los trabajos que aprovechan las nuevas características de GitHub Actions sin una actualización de software.

Si inhabilitas las actualizaciones automáticas, necesitarás actualizar la versión de tu ejecutor en los siguientes 30 días después de que una versión nueva esté disponible. Es posible que desee suscribirse a las notificaciones de lanzamientos en el actions/runner repositorio. Para más información, consulta Configuración de notificaciones.

Para saber cómo instalar la versión más reciente del ejecutor, consulte las instrucciones de instalación de la versión más reciente.

Advertencia

Las actualizaciones publicadas para el software, incluidas las versiones principales, secundarias o de revisión, se consideran una actualización disponible. Si no ejecutas una actualización de software en los 30 días posteriores, el servicio de GitHub Actions no pondrá los trabajos en cola para el ejecutor. Adicionalmente, si se requiere una actualización de seguridad crítica, el servicio de las GitHub Actions no pondrá jobs en cola para tu ejecutor sino hasta que este se actualice.

Webhooks para el escalado automático

Puede crear su propio entorno de escalado automático mediante cargas recibidas desde el webhook workflow_job. Este webhook está disponible en los niveles de repositorio, organización y empresa, y la carga de este evento contiene una clave action que corresponde a las fases del ciclo de vida de un trabajo de flujo de trabajo; por ejemplo, cuando los trabajos son queued, in_progress y completed. Entonces debes crear tu propia automatización de escalamiento en respuesta a estas cargas útiles de webhook.

Para obtener más información sobre el webhook workflow_job, consulta Eventos y cargas de webhook.
Para aprender a trabajar con webhooks, consulta Documentación de webhooks.

Nota: Este enfoque se basa en la puntualidad de la entrega de los webhooks para tomar decisiones de escalado, lo que puede introducir retrasos y problemas de fiabilidad. Considere la posibilidad de usar el controlador de acciones o el cliente del conjunto de escalado para escenarios de escalado automático de volúmenes más grandes.

Requisitos de autenticación

Puede registrar y eliminar los ejecutores autohospedados del repositorio y la organización mediante la API. Para autenticarse en la API, la implementación del escalado automático puede usar un token de acceso o una GitHub aplicación.

Tu token de acceso necesitará el siguiente alcance:

En el caso de los repositorios privados, use un token de acceso con el ámbito repo.
En el caso de los repositorios públicos, use un token de acceso con el ámbito public_repo.
En el caso de las organizaciones, use un token de acceso con el ámbito admin:org.

Para autenticarse mediante una GitHub aplicación, debe tener asignados los permisos siguientes:

En el caso de los repositorios, asigne el permiso administration.
En el caso de las organizaciones, asigne el permiso organization_self_hosted_runners.

Puede registrar y eliminar ejecutores autohospedados empresariales mediante la API. Para autenticarte en la API, tu implementación de autoescalamiento puede utilizar un token de acceso.

El token de acceso requerirá el alcance manage_runners:enterprise.

Comunicación

Los ejecutores autoalojados se conectan a tu instancia de GitHub Enterprise Server para recibir asignaciones de tareas y descargar nuevas versiones de la aplicación de ejecutor.

La aplicación ejecutora de GitHub Actions es de código abierto. Puede contribuir y presentar incidencias en el repositorio runner. Cuando se publica una nueva versión, la aplicación del ejecutor se actualizará automáticamente en un plazo de 24 horas.

Requisitos para la comunicación con tu instancia de GitHub Enterprise Server

La aplicación del ejecutor autohospedado debe ejecutarse en el equipo host para aceptar y ejecutar GitHub Actions trabajos.
GitHub Enterprise Server debe aceptar conexiones entrantes desde sus ejecutores a través de HTTP(S) al nombre de host y al subdominio de la API de tu instancia de GitHub Enterprise Server, y sus ejecutores deben permitir conexiones salientes a través de HTTP(S) al nombre de host y al subdominio de la API de tu instancia de GitHub Enterprise Server.
Para que el almacenamiento en caché funcione, el ejecutor debe poder comunicarse con el almacenamiento de blobs y descargar contenido directamente desde él.

Comunicación con GitHub.com

Los ejecutores autohospedados no necesitan conectarse a GitHub.com, a menos que haya habilitado el acceso automático a las acciones de GitHub.com para GitHub Enterprise Server. Para más información, consulta Acerca de utilizar las acciones en tu empresa.

Si desea que el ejecutor se conecte a GitHub.com, la máquina host debe poder realizar conexiones HTTP salientes a través del puerto 80 o conexiones HTTPS a través del puerto 443. Para garantizar la conectividad a través de HTTPS, configure TLS para GitHub Enterprise Server. Consulta Configurar TLS.

Si ha habilitado el acceso automático a las acciones de GitHub.com, el ejecutor autohospedado se conectará directamente a GitHub.com para descargar acciones. Debe asegurarse de que la máquina tiene el acceso de red adecuado para comunicarse con las GitHub direcciones URL que se enumeran a continuación.

Shell

github.com
api.github.com
codeload.github.com

github.com
api.github.com
codeload.github.com

Puede usar la API REST para obtener información meta sobre GitHub, incluidas las direcciones IP y los detalles del dominio de los GitHub servicios. La sección actions_inbound de la API admite tanto dominios completamente calificados como dominios con caracteres comodín. Los dominios completos especifican un nombre de dominio completo (por ejemplo, example.github.com), mientras que los dominios con caracteres comodín usan un * para representar varios subdominios posibles (por ejemplo, *.github.com). A continuación se muestra un ejemplo de los requisitos de un ejecutor autohospedado que utiliza dominios con caracteres comodín. Para más información, consulta Puntos de conexión de la API de REST para metadatos.