Uso de imágenes personalizadas

Imágenes personalizadas

Puede crear una imagen personalizada para definir el entorno exacto que usa Ejecutores más grandes hospedados en GitHub . Las imágenes personalizadas permiten preinstalar herramientas, dependencias y configuraciones para acelerar los flujos de trabajo y mejorar la coherencia entre los trabajos.

Cuando el ejecutor usa una imagen personalizada, actúa como un entorno "previamente caliente", lo que permite que los flujos de trabajo se completen más rápido, descargando paquetes y archivos binarios una vez durante la creación de imágenes en lugar de cada vez que se ejecuta un flujo de trabajo. Para obtener más información sobre las imágenes personalizadas, consulte Imágenes de ejecutor.

El proceso de uso de una imagen personalizada implica tres pasos principales: 1. Configuración de un ejecutor de generación de imágenes: cree un ejecutor más grande para compilar y almacenar la imagen personalizada. 1. Generación de una imagen personalizada: genere la imagen personalizada mediante la ejecución de un flujo de trabajo mediante el ejecutor de generación de imágenes. 1. Instalación de imágenes personalizadas: cree un ejecutor que use la imagen personalizada.

Prerrequisitos

Para poder crear imágenes personalizadas, asegúrese de que se cumplen los siguientes requisitos.

•         **Directiva**: las imágenes personalizadas deben estar habilitadas para su organización o empresa. Los propietarios de empresas pueden administrar el acceso a imágenes personalizadas y establecer políticas de retención en la configuración de la política de acciones. Para más información, consulta [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#custom-images).
  

•         **Permisos**: para crear y administrar imágenes personalizadas, debe ser propietario de una organización o empresa, o tener el rol de `CI/CD Admin`, o tener un rol con los siguientes permisos detallados.  
  

  • Visualización de imágenes personalizadas del ejecutor alojado por la organización
  • Administración de imágenes personalizadas del ejecutor hospedado por la organización
  • Administración de ejecutores y grupos de ejecutores de la organización

  Para más información, consulta Permisos de roles de organización personalizados.

Configuración de un ejecutor de generación de imágenes

Para crear una imagen personalizada, primero debe configurar un ejecutor de generación de imágenes. Al crear el ejecutor, la plataforma que seleccione para el ejecutor debe coincidir con la plataforma de la imagen que desea crear. La plataforma del ejecutor puede ser Linux x64, Linux ARM64 o Windows x64.

1. Crear un ejecutor más grande:
   • Para las organizaciones, consulte Agregar un corredor más grande a una organización.
   • Para empresas, consulte Añadir un corredor más grande a una empresa.
2. Al configurar el ejecutor, seleccione las siguientes configuraciones para el ejecutor de generación de imágenes: * Plataforma: seleccione una plataforma compatible que coincida con la plataforma de la imagen que planea crear (Linux x64, Linux ARM64 o Windows x64). * Imagen: seleccione una imagen en la que compilar y, a continuación, habilite la casilla Habilitar este ejecutor para generar imágenes personalizadas.
   • Puede empezar desde una imagen de propiedad de GitHub o elegir una imagen base para comenzar con un sistema operativo limpio.
   • En el caso de las plataformas ARM64, también puede seleccionar una imagen mantenida por ARM con herramientas preinstaladas.

   •      **Grupo de runners**: Seleccione el grupo para que su runner sea miembro. Una vez creada la imagen personalizada, solo los runners de este grupo de runners pueden generar nuevas versiones de esa imagen.
     

Generación de una imagen personalizada

Después de crear un ejecutor de generación de imágenes, ejecute un flujo de trabajo que incluya la snapshot palabra clave para generar una imagen personalizada.

Para configurar un flujo de trabajo para la generación de imágenes:

• Establezca el valor de runs-on con el nombre del ejecutor de generación de imágenes que creó.
• Agregue la snapshot palabra clave en el trabajo, utilizando la sintaxis de cadena de texto o la sintaxis de mapeo que se muestra a continuación.
  • Cada trabajo que incluye la snapshot palabra clave crea una imagen independiente. Para generar solo una imagen o versión de imagen, incluya todos los pasos de flujo de trabajo en un solo trabajo.
  • Cada ejecución correcta de un trabajo que incluye la snapshot palabra clave crea una nueva versión de esa imagen.

          GitHub recomienda configurar la generación de imágenes como un flujo de trabajo programado semanalmente. Este enfoque garantiza que las dependencias permanezcan up-to-date y tengan las revisiones de seguridad más recientes. Para más información, consulta [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#schedule).

La imagen puede tardar algún tiempo en generarse completamente y estar lista para su uso una vez completado el flujo de trabajo. El tiempo de aprovisionamiento varía en función del tamaño y la configuración del ejecutor, y puede tardar varias horas en ejecutores más grandes.

La imagen solo se genera cuando el trabajo se completa correctamente. Esto impide que se creen nuevas versiones de imagen cuando se produce un error en un flujo de trabajo o finaliza en un estado incompleto.

Una vez generada la imagen, está disponible para su uso en los flujos de trabajo. Para obtener más información sobre cómo administrar imágenes personalizadas, consulte Administración de imágenes personalizadas.

Sintaxis de cadena

Puede usar la sintaxis de cadena con snapshot para definir el nombre de la imagen. Este método crea una nueva imagen o agrega una nueva versión a una imagen existente con el mismo nombre. No se puede especificar un número de versión con esta sintaxis.

jobs: 
  build:
    runs-on: my-image-generation-runner
    snapshot: my-custom-image
    steps:
      # Add any steps to download and setup any dependencies here

Sintaxis de mapeo

Puede usar la sintaxis de asignación con snapshot para definir tanto image-name como la version opcional. Al especificar una versión principal, la versión secundaria se incrementa automáticamente si esa versión principal ya existe. No se admiten versiones de revisión.

jobs: 
  build:
    runs-on: my-image-generation-runner
    snapshot: 
        image-name: my-custom-image
        version: 2.*
    steps:
      # Add any steps to download and setup any dependencies here

Control de versiones

Al generar imágenes personalizadas, GitHub asigna automáticamente números de versión para ayudarle a administrar las actualizaciones y realizar un seguimiento del historial de imágenes.

Comportamiento predeterminado

Si una imagen con el nombre especificado no existe en su organización o empresa, GitHub la crea con un número de versión inicial de 1.0.0. Si ya existe una imagen con el mismo nombre, GitHub crea una nueva versión incrementando el número de versión secundaria (por ejemplo, 1.1.0, 1.2.0, etc.).

Si no especifica una versión en el archivo YAML, la generación de imágenes usa este comportamiento predeterminado.

Especificación de una versión en el flujo de trabajo

Si incluye una versión en la asignación de YAML, GitHub comprueba primero el número de versión principal.

• Si la versión principal especificada ya existe, la nueva imagen usa la siguiente versión secundaria (por ejemplo, 1.0 se convierte en 1.1).
• Si la versión principal no existe, GitHub crea una nueva versión principal (por ejemplo, 2.0).

No se admiten versiones de revisión.

Etiqueta más reciente

La ejecución más reciente del flujo de trabajo para una imagen siempre se etiqueta como actualizada. Si especifica una versión principal anterior en YAML (por ejemplo, versión: 1.* cuando existe una versión 2.0), GitHub genera una nueva versión secundaria en la versión principal anterior y la marca como más reciente.

          Ejecutor de mayor tamaño hospedado en GitHub la creación no admite caracteres comodín en la selección de la versión de la imagen.

Facturación y almacenamiento para imágenes personalizadas

Los trabajos que utilizan imágenes personalizadas se facturan al mismo precio por minuto que el ejecutor más grande que usa la imagen. El almacenamiento de imágenes personalizadas se factura por separado a través del GitHub Actions almacenamiento.

Si vuelve a generar imágenes con frecuencia y conserva versiones anteriores, el uso del almacenamiento puede crecer rápidamente porque cada tarea de flujo de trabajo exitosa que incluye la palabra clave snapshot crea una nueva versión de la imagen. Para obtener más información, vea facturación de GitHub Actions y Aplicación de directivas para GitHub Actions en la empresa.

Administración de imágenes personalizadas

Puede ver información detallada sobre cada imagen, eliminar imágenes sin usar o versiones específicas y realizar un seguimiento de las versiones de imagen a lo largo del tiempo.

1. En GitHub, navega a la página principal de tu organización.

2. Debajo del nombre de la organización, haz clic en Settings. Si no puedes ver la pestaña "Configuración", selecciona el menú desplegable y, a continuación, haz clic en Configuración.

   

3. En la barra lateral izquierda, haga clic en Actions y, a continuación, haga clic en Imágenes personalizadas.

4. En la página "Imágenes personalizadas", puede ver todas las imágenes personalizadas que se han creado en su organización o empresa.

5. Para ver detalles sobre una imagen específica, haga clic en el nombre de la imagen.

Instalación de imágenes personalizadas

Una vez que la imagen personalizada esté lista, puede instalarla en un nuevo Ejecutor de mayor tamaño hospedado en GitHub.

1. Siga los pasos para crear un ejecutor más grande:

   • Para las organizaciones, consulte Agregar un corredor más grande a una organización.
   • Para empresas, consulte Añadir un corredor más grande a una empresa.

2. Al configurar el ejecutor: * Plataforma: seleccione la misma plataforma que usó para generar la imagen (Linux x64, Linux ARM64 o Windows x64). * Imagen: seleccione la pestaña Personalizado y elija la imagen personalizada de la lista.

   • Si no ve la imagen, asegúrese de haber seleccionado la plataforma correcta y de que está creando el ejecutor en el mismo nivel (organización o empresa) donde se generó la imagen.

   •      **Versión de imagen**: elija **Latest (Más reciente)** para usar automáticamente la versión más reciente o seleccione un número de versión específico para anclar el ejecutor a esa versión.
     

     • Si selecciona Latest (Más reciente), el ejecutor se actualiza automáticamente cuando hay disponible una nueva versión de la imagen. Si ancla el ejecutor a una versión específica, deberá editar el ejecutor manualmente para actualizarlo más adelante.

   •      **Tamaño**: elija un tamaño de ejecutor con almacenamiento igual o mayor que el tamaño de la imagen. Por ejemplo, si la imagen se generó en un ejecutor de 8 núcleos, seleccione un 8 núcleo o mayor para ejecutar esta imagen.
     

   •      **Grupo de ejecutores**: asigne el ejecutor a un grupo de ejecutores que se comparte con los repositorios que necesitan usar esta imagen.
     

3. En el GitHub Actions flujo de trabajo, establezca la runs-on clave en el nombre del ejecutor.

   jobs: 
     build:
       runs-on: my-custom-runner
       steps:
       # Add any steps for your workflow here
   

4. Ejecute el flujo de trabajo para comprobar que se completa correctamente. Los registros de trabajo mostrarán el nombre y la versión de la imagen en la sección "Configurar trabajo".

Procedimientos recomendados de seguridad para imágenes personalizadas

Para evitar cambios no autorizados en las imágenes, siga estos procedimientos recomendados.

•         **Utilice grupos de ejecutores dedicados para la generación de imágenes.** Los ejecutores que generan imágenes de producción deben permanecer en un grupo de ejecutores dedicado. No comparta grupos de ejecutores entre repositorios de producción y desarrollo o de prueba, ya que cualquier persona con acceso a un repositorio de desarrollo o prueba podría insertar código malintencionado en una imagen de producción.
  

•         **No permita que los repositorios públicos accedan a los ejecutores de generación de imágenes.** Limite los repositorios que pueden usar ejecutores de generación de imágenes solo a aquellos que lo requieran y revise el acceso periódicamente.
  

•         **Aplique privilegios mínimos a los repositorios.** Evite dar acceso a toda la organización `write` en repositorios que tengan acceso a unidades de procesamiento de imágenes. Dado que las imágenes se pueden generar desde cualquier rama, cualquier persona con acceso de escritura podría crear una rama con código arbitrario y desencadenar la generación de imágenes.