Utilisation d’images personnalisées

Créez, gérez et utilisez des images personnalisées pour Environnements d'exécution plus grands hébergés par GitHub votre organisation ou votre entreprise.

Qui peut utiliser cette fonctionnalité ?

Environnements d'exécution plus grands hébergés par GitHub are only available for organizations and enterprises using the GitHub Team or GitHub Enterprise Cloud plans.
Sign up for GitHub Actions

Dans cet article

Images personnalisées

Vous pouvez créer une image personnalisée pour définir l’environnement exact que vous Environnements d'exécution plus grands hébergés par GitHub utilisez. Les images personnalisées vous permettent de préinstaller des outils, des dépendances et des configurations pour accélérer les flux de travail et améliorer la cohérence entre les travaux.

Lorsque votre exécuteur utilise une image personnalisée, il agit comme un environnement « préchauffé », ce qui permet aux flux de travail de se terminer plus rapidement, en téléchargeant des packages et des fichiers binaires une fois lors de la création d’images au lieu de chaque exécution d’un flux de travail. Pour plus d’informations sur les images personnalisées, consultez images Runner.

Le processus d’utilisation d’une image personnalisée implique trois étapes principales : 1. Configuration d’un exécuteur de génération d’images : créez une exécuteur plus grand image pour générer et stocker votre image personnalisée. 1. Génération d’une image personnalisée : générez votre image personnalisée en exécutant un workflow à l’aide de l’exécuteur de génération d’images. 1. Installation d’images personnalisées : créez un exécuteur qui utilise votre image personnalisée.

Prerequisites

Avant de pouvoir créer des images personnalisées, vérifiez que les exigences suivantes sont remplies.

  • Stratégie : les images personnalisées doivent être activées pour votre organisation ou votre entreprise. Les propriétaires d’entreprise peuvent gérer l’accès aux images personnalisées et définir des stratégies de rétention dans les paramètres de stratégie Actions. Pour plus d’informations, consultez « Application de stratégies pour GitHub Actions dans votre entreprise ».

  • Autorisations : pour créer et gérer des images personnalisées, vous devez être propriétaire d’une organisation ou d’entreprise, ou avoir le CI/CD Admin rôle, ou avoir un rôle avec les autorisations affinées suivantes.

    • Afficher les images personnalisées de runners hébergés d'organisation
    • Gérer les images personnalisées de runners hébergés d'organisation
    • Gérer les runners hébergés d'organisation et les groupes de runners

    Pour plus d’informations, consultez « Autorisations des rôles d’organisation personnalisés ».

Configuration d’un exécuteur de génération d’images

Pour créer une image personnalisée, vous devez d’abord configurer un exécuteur de génération d’images. Lorsque vous créez l’exécuteur, la plateforme que vous sélectionnez pour votre exécuteur doit correspondre à la plateforme de l’image que vous souhaitez générer. La plateforme de l’exécuteur peut être Linux x64, Linux ARM64 ou Windows x64.

  1. Créez un exécuteur plus grand :
  2. Lorsque vous configurez l’exécuteur, sélectionnez les configurations suivantes pour votre exécuteur de génération d’images :
    • Plateforme : sélectionnez une plateforme prise en charge qui correspond à la plateforme de l’image que vous envisagez de créer (Linux x64, Linux ARM64 ou Windows x64).
    • Image : sélectionnez une image à générer, puis activez la case à cocher Activer cet exécuteur pour générer des images personnalisées.
      • Vous pouvez commencer à partir d’une image détenue par GitHub ou choisir une image de base pour démarrer avec un système d’exploitation vierge.
      • Pour les plateformes ARM64, vous pouvez également sélectionner une image gérée par ARM avec des outils préinstallés.
    • Groupe d’exécuteurs : sélectionnez le groupe dont votre exécuteur doit être membre. Une fois l'image personnalisée créée, seuls les runners de ce groupe de runners peuvent générer de nouvelles versions de cette image.

Génération d’une image personnalisée

Après avoir créé un exécuteur de génération d’images, exécutez un workflow qui inclut le snapshot mot clé pour générer une image personnalisée.

Pour configurer un flux de travail pour la génération d’images :

  • Définissez la valeur runs-on sur le nom du runner de génération d'images que vous avez créé.
  • Ajoutez le snapshot mot clé au travail, à l’aide de la syntaxe de chaîne ou de la syntaxe de mappage indiquée ci-dessous.
    • Chaque travail qui inclut le snapshot mot clé crée une image distincte. Pour générer une seule image ou version d’image, incluez toutes les étapes de flux de travail dans un seul travail.
    • Chaque exécution réussie d’un travail qui inclut le snapshot mot clé crée une nouvelle version de cette image.

Remarque

          GitHub recommande de configurer la génération d’images en tant que flux de travail planifié chaque semaine. Cette approche garantit que les dépendances restent up-to-date et disposent des derniers correctifs de sécurité. Pour plus d’informations, consultez « [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#schedule) ».

Il peut prendre un certain temps pour que votre image soit entièrement générée et prête à être utilisée une fois le flux de travail terminé. Le délai d’approvisionnement varie en fonction de la taille et de la configuration du runner, et peut prendre plusieurs heures pour les larger runners.

L’image est générée uniquement lorsque le travail se termine correctement. Cela empêche la création de nouvelles versions d’images lorsqu’un flux de travail échoue ou se termine dans un état incomplet.

Une fois l’image générée, elle est disponible pour être utilisée dans vos flux de travail. Pour plus d’informations sur la gestion des images personnalisées, consultez Gestion des images personnalisées.

Syntaxe de chaîne

Vous pouvez utiliser la syntaxe de chaîne avec snapshot pour définir le nom de l'image. Cette méthode crée une image ou ajoute une nouvelle version à une image existante portant le même nom. Vous ne pouvez pas spécifier un numéro de version à l’aide de cette syntaxe.

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

Syntaxe de mappage

Vous pouvez utiliser la syntaxe de mappage avec snapshot pour définir à la fois le image-name et l'optionnel version. Lorsque vous spécifiez une version majeure, la version mineure s'incrémente automatiquement si cette version principale existe déjà. Les versions de correctifs ne sont pas prises en charge.

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

Gestion des versions

Lorsque vous générez des images personnalisées, GitHub attribue automatiquement des numéros de version pour vous aider à gérer les mises à jour et à suivre l’historique des images.

Comportement par défaut

Si une image portant le nom spécifié n’existe pas dans votre organisation ou entreprise, GitHub crée-la avec un numéro de version initial de 1.0.0. Si une image portant le même nom existe déjà, GitHub crée une nouvelle version en incrémentant le numéro de version mineure (par exemple, 1.1.0, 1.2.0, etc.).

Si vous ne spécifiez pas de version dans votre fichier YAML, la génération d’images utilise ce comportement par défaut.

Spécification d’une version dans votre flux de travail

Si vous incluez une version dans le mappage YAML, GitHub vérifiez d’abord le numéro de version principal.

  • Si la version principale spécifiée existe déjà, la nouvelle image utilise la version mineure suivante (par exemple, la version 1.0 devient 1.1).
  • Si la version principale n’existe pas, GitHub crée une nouvelle version majeure (par exemple, 2.0).

Les versions de correctifs ne sont pas prises en charge.

Dernier tag

La dernière exécution de workflow pour une image est toujours étiquetée comme "latest". Si vous spécifiez une version principale antérieure dans YAML (par exemple, version : 1.* lorsqu’une version 2.0 existe), GitHub génère une nouvelle version mineure sous l’ancienne version principale et la marque comme la plus récente.

Remarque

          Exécuteur plus volumineux hébergé par GitHub la création ne prend pas en charge les caractères génériques dans la sélection des versions d'image.

Facturation et stockage pour les images personnalisées

Les tâches qui utilisent des images personnalisées sont facturées au même tarif à la minute que le exécuteur plus grand qui utilise l’image. Le stockage des images personnalisées est facturé séparément via le stockage GitHub Actions.

Si vous régénérez fréquemment des images et conservez des versions antérieures, votre utilisation du stockage peut croître rapidement, car chaque travail de workflow réussi qui inclut le snapshot mot clé crée une nouvelle version d’image. Pour plus d’informations, consultez « Facturation des actions GitHub » et « Application de stratégies pour GitHub Actions dans votre entreprise ».

Gestion des images personnalisées

Vous pouvez afficher des informations détaillées sur chaque image, supprimer des images inutilisées ou des versions spécifiques et suivre les versions d’images au fil du temps.

  1. Sur GitHub, accédez à la page principale de l’organisation.

  2. Sous le nom de votre organisation, cliquez sur Settings. Si vous ne voyez pas l’onglet « Paramètres », sélectionnez le menu déroulant , puis cliquez sur Paramètres.

    Capture d’écran des onglets dans le profil d’une organisation. L’onglet « Paramètres » est présenté en orange foncé.

  3. Dans la barre latérale gauche, cliquez sur Actions, puis cliquez sur Images personnalisées.

  4. Dans la page « Images personnalisées », vous pouvez afficher toutes les images personnalisées créées dans votre organisation ou entreprise.

  5. Pour afficher des détails sur une image spécifique, cliquez sur le nom de l’image.

Installation d’images personnalisées

Une fois votre image personnalisée prête, vous pouvez l’installer sur un nouveau Exécuteur plus volumineux hébergé par GitHub.

  1. Suivez les étapes de création d’un exécuteur plus grand:

  2. Lors de la configuration du runner :

    • Plateforme : sélectionnez la même plateforme que celle que vous avez utilisée pour générer l’image (Linux x64, Linux ARM64 ou Windows x64).
    • Image : sélectionnez l’onglet Personnalisé , puis choisissez votre image personnalisée dans la liste.
      • Si vous ne voyez pas votre image, vérifiez que vous avez sélectionné la plateforme appropriée et que vous créez l’exécuteur au même niveau (organisation ou entreprise) où l’image a été générée.
    • Version de l'image : choisissez Dernière version pour utiliser automatiquement la version la plus récente, ou sélectionnez un numéro de version spécifique pour épingler le runner à cette version.
      • Si vous sélectionnez Dernière version, votre exécuteur est automatiquement mis à jour lorsqu’une nouvelle version de l’image devient disponible. Si vous épinglez le runner à une version spécifique, vous devrez modifier le runner manuellement pour effectuer une mise à niveau ultérieurement.
    • Taille : choisissez une taille de runner avec un stockage égal ou supérieur à la taille de votre image. Par exemple, si l’image a été générée sur un exécuteur de 8 cœurs, sélectionnez un 8 cœurs ou plus pour exécuter cette image.
    • Groupe d’exécuteurs : affectez l’exécuteur à un groupe d’exécuteurs partagé avec les référentiels qui doivent utiliser cette image.

  3. Dans votre GitHub Actions tâche de flux de travail, définissez la runs-on clé sur le nom de votre exécuteur.

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

  4. Exécutez votre flux de travail pour vérifier qu’il se termine correctement. Les journaux des tâches afficheront le nom et la version de l’image dans la section « Configurer la tâche ».

Meilleures pratiques de sécurité pour les images personnalisées

Pour empêcher les modifications non autorisées apportées à vos images, suivez ces bonnes pratiques.

  • Utilisez des groupes d’exécuteurs dédiés pour la génération d’images. Les exécuteurs qui génèrent des images de production doivent rester dans un groupe d’exécuteurs dédié. Ne partagez pas de groupes d’exécuteurs entre les référentiels de production et de développement ou de test, car toute personne ayant accès à un dépôt de développement ou de test peut injecter du code malveillant dans une image de production.
  • N’autorisez pas les dépôts publics à accéder aux exécuteurs de génération d’images. Limitez les dépôts qui peuvent utiliser des exécuteurs de génération d'images uniquement à ceux qui le nécessitent et examinez régulièrement l'accès.
  • Appliquez le privilège minimum aux référentiels. Évitez d’accorder un accès write à l’échelle de l’organisation aux référentiels qui ont accès aux runners de génération d’images. Étant donné que les images peuvent être générées à partir de n’importe quelle branche, toute personne disposant d’un accès en écriture peut créer une branche avec du code arbitraire et déclencher la génération d’images.