Referencia de ejecutores autohospedados

Busca información sobre cómo configurar y usar ejecutores autohospedados.

En este artículo

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

macOS

  • macOS 11.0 (Big Sur) o posterior

Arquitecturas de procesador admitidas

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

Precedencia de enrutamiento para los ejecutores auto-hospedados

Cuando se enruta un trabajo hacia un ejecutor autohospedado, GitHub busca un ejecutor que coincida con las etiquetas y grupos runs-on del trabajo:

  • Si GitHub encuentra un ejecutor inactivo en línea que coincida con las etiquetas y grupos runs-on del trabajo, este se asignará y enviará al ejecutor.
    • 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 ningún ejecutor en línea inactivo que coincida con las etiquetas y grupos runs-on del trabajo, este permanecerá en cola hasta que haya un ejecutor en línea.
  • Si el job permanece en cola por más de 24 horas, este fallará.

Escalabilidad automática

Puedes incrementar o decrementar la cantidad de ejecutores auto-hospedados en tu ambiente automáticamente como respuesta a los eventos de webhook que recibes con una etiqueta particular.

Soluciones de escalado automático admitidas

El proyecto actions/actions-runner-controller (ARC) es un escalador automático de ejecutor basado en Kubernetes. GitHub recomienda ARC si el equipo que implementa tiene conocimientos y experiencia a nivel de experto en Kubernetes.

Para más información, consulta Acerca de Actions Runner Controller y Acerca de la compatibilidad con Actions Runner Controller.

Ejecutores efímeros para el escalado automático

GitHub recomienda implementar el autoescalamiento con ejecutores auto-hospedados efímeros; no se recomienda autoescalar con ejecutores auto-hospedados persistentes. En casos específicos, GitHub no puede garantizar que los jobs no se asignen a los ejecutores persistentes mientras están cerrados. Con los ejecutores efímeros, esto puede garantizarse, ya que GitHub solo asigna un job a un ejecutor.

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 se implementen ejecutores efímeros, 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 Monitoring and troubleshooting self-hosted runners.

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

El servicio de GitHub Actions entonces quitará el registro del ejecutor automáticamente después de que haya procesado un job. 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 de GitHub Actions requiere cambios tanto en el servicio de GitHub Actions como en el software del ejecutor. El ejecutor podría no ser capaz procesar correctamente los jobs que toman ventaja de las características nuevas en GitHub Actions sin una actualización de sfotware.

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 para las versiones del 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.

Requisitos de autenticación

Puede registrar y eliminar los ejecutores autohospedados del repositorio y la organización mediante la API. Para autenticarte en la API, tu implementación de auto-escalamiento puede utilizar un token de acceso o una app de GitHub.

Tu token de acceso necesitará el siguiente alcance:

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

Para autenticarte utilizando una App de GitHub, se le debe asignar los siguientes permisos:

  • 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

Ejecutores autohospedados conectas a tu instancia de GitHub Enterprise Server para recibir asignaciones de trabajos y para descargar nuevas versiones de la aplicación del 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 trabajos de GitHub Actions.
  • GitHub Enterprise Server debe aceptar conexiones entrantes desde tus ejecutores a través de HTTP(S) en el nombre de host de tu instancia de GitHub Enterprise Server y subdominio de la API, y tus ejecutores deben permitir conexiones salientes a través de HTTP(S) hacia el nombre de host de tu instancia de GitHub Enterprise Server y el subdominio de la API.
  • 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 auto-hospedados no necesitan conectarse a GitHub.com a menos de que hayas 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 deseas 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 por HTTPS, configure TLS para GitHub Enterprise Server. Consulta Configurar TLS.

Si habilitaste el acceso automático a las acciones de GitHub.com, entonces el ejecutor auto-hospedado se conectará directamente a GitHub.com para descargar las acciones. Debes asegurarte de que la máquina tiene el acceso a la red adecuado para comunicarte con las URL de GitHub listadas a continuación.

Shell
github.com
api.github.com
codeload.github.com
pkg.actions.githubusercontent.com

Puedes usar la API de REST para obtener la metainformación sobre GitHub, incluidas las direcciones IP y los detalles del dominio de los servicios de GitHub. La sección actions_inbound de la API admite dominios completos y 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.

Shell
github.com
*.github.com
*.githubusercontent.com
ghcr.io

Nota:

Algunos de los dominios que se enumeran antes se configuran mediante registros CNAME. Es posible que algunos firewalls necesiten agregar reglas de forma recursiva para todos los registros CNAME. Tenga en cuenta que es posible que los registros CNAME cambien en el futuro y que solo los dominios enumerados permanezcan constantes.