Extension GitHub Actions Importer avec des transformateurs personnalisés

GitHub Actions Importer offre la possibilité d’étendre son mappage intégré.

Dans cet article

Mentions légales

À propos des transformateurs personnalisés

GitHub Actions Importer offre la possibilité d’étendre son mappage intégré en créant des transformateurs personnalisés. Les transformateurs personnalisés peuvent être utilisés pour :

Utilisation de transformateurs personnalisés avec GitHub Actions Importer

Un transformateur personnalisé contient une logique de mappage que GitHub Actions Importer peut utiliser pour transformer vos plug-ins, tâches, étiquettes d’exécuteur ou variables d’environnement pour qu’ils fonctionnent avec GitHub Actions. Les transformateurs personnalisés sont écrits avec un langage spécifique au domaine (DSL) basé sur Ruby et sont définis dans un fichier avec l’extension de fichier .rb.

Vous pouvez utiliser l’option CLI --custom-transformers pour spécifier les fichiers de transformateur personnalisés à utiliser avec les commandes audit, dry-run et migrate.

Par exemple, si des transformateurs personnalisés sont définis dans un fichier nommé transformers.rb, vous pouvez utiliser la commande suivante pour les utiliser avec GitHub Actions Importer :

gh actions-importer ... --custom-transformers transformers.rb

Vous pouvez également utiliser la syntaxe du modèle Glob pour spécifier plusieurs fichiers de transformateur personnalisés. Par exemple, si plusieurs fichiers transformateurs personnalisés se trouvent dans un répertoire nommé transformers, vous pouvez tous les fournir à GitHub Actions Importer avec la commande suivante :

gh actions-importer ... --custom-transformers transformers/*.rb

Remarque : Lorsque vous utilisez des transformateurs personnalisés, les fichiers de transformateur personnalisés doivent résider dans le même répertoire (ou un de ses sous-répertoires) que celui à partir duquel la commande gh actions-importer est exécutée.

Création de transformateurs personnalisés pour les éléments

Vous pouvez créer des transformateurs personnalisés que GitHub Actions Importer utilisera lors de la conversion des étapes de génération ou des déclencheurs existants en leur équivalent dans GitHub Actions. Cela est particulièrement utile dans les cas suivants :

  • GitHub Actions Importer ne convertit pas automatiquement un élément.
  • Vous souhaitez modifier la façon dont un élément est converti par GitHub Actions Importer.
  • Vos pipelines existants utilisent des extensions personnalisées ou propriétaires, comme des bibliothèques partagées dans Jenkins, et vous devez définir le fonctionnement de ces étapes dans GitHub Actions.

GitHub Actions Importer utilise des transformateurs personnalisés qui sont définis à l’aide d’un DSL basé sur Ruby. Pour créer des transformateurs personnalisés pour les étapes de génération et les déclencheurs :

  • Chaque fichier de transformateur personnalisé doit contenir au moins une méthode transform.
  • Chaque méthode transform doit retourner un Hash, un tableau de Hash, ou nil. Cette valeur retournée correspond à une action définie dans YAML. Pour plus d’informations sur les actions, consultez « Comprendre GitHub Actions ».

Exemple de transformateur personnalisé pour une étape de génération

L’exemple suivant convertit une étape de génération qui utilise l’identificateur « buildJavaScriptApp » pour exécuter différentes commandes npm :

Ruby
transform "buildJavaScriptApp" do |item|
  command = ["build", "package", "deploy"].map do |script|
    "npm run #{script}"
  end

  {
    name: "build javascript app",
    run: command.join("\n")
  }
end

L’exemple ci-dessus entraîne l’étape de workflow GitHub Actions. Il se compose d’étapes de génération converties qui avaient un identificateur buildJavaScriptApp :

- name: build javascript app
  run: |
    npm run build
    npm run package
    npm run deploy

La méthode transform utilise l’identificateur de l’étape de génération de votre instance CI/CD source dans un argument. Dans cet exemple, l’identificateur est buildJavaScriptLibrary. Vous pouvez également utiliser des valeurs séparées par des virgules pour passer plusieurs identificateurs à la méthode transform. Par exemple : transform "buildJavaScriptApp", "buildTypeScriptApp" { |item| ... }.

Remarque : La structure des données de item sera différente en fonction de la plateforme CI/CD et du type d’élément en cours de conversion.

Création de transformateurs personnalisés pour les exécuteurs

Vous pouvez personnaliser le mappage entre les exécuteurs dans votre instance CI/CD source et leurs exécuteurs GitHub Actions équivalents.

GitHub Actions Importer utilise des transformateurs personnalisés qui sont définis à l’aide d’un DSL basé sur Ruby. Pour créer des transformateurs personnalisés pour les exécuteurs :

  • Le fichier de transformateur personnalisé doit avoir au moins une méthode runner.
  • La méthode runner accepte deux paramètres. Le premier paramètre est l’étiquette d’exécuteur de l’instance CI/CD source, et le second est l’étiquette d’exécuteur GitHub Actions correspondante. Pour plus d’informations sur les exécuteurs GitHub Actions, consultez la section « Utilisation des exécuteurs hébergés par GitHub ».

Exemples de transformateurs personnalisés pour les exécuteurs

L’exemple suivant montre une méthode runner qui convertit une étiquette d’exécuteur en une étiquette d’exécuteur GitHub Actions dans le workflow résultant.

Ruby
runner "linux", "ubuntu-latest"

Vous pouvez également utiliser la méthode runner pour convertir une étiquette d’exécuteur en plusieurs étiquettes d’exécuteur GitHub Actions dans le workflow résultant.

Ruby
runner "big-agent", ["self-hosted", "xl", "linux"]

GitHub Actions Importer tente de mapper au mieux l’étiquette de l’exécuteur. Dans les cas où cela n’est pas possible, l’étiquette d’exécuteur ubuntu-latest est utilisée comme valeur par défaut. Vous pouvez utiliser un mot clé spécial avec la méthode runner pour contrôler cette valeur par défaut. Par exemple, le transformateur personnalisé suivant indique à GitHub Actions Importer d’utiliser macos-latest comme exécuteur par défaut au lieu de ubuntu-latest.

Ruby
runner :default, "macos-latest"

Création de transformateurs personnalisés pour les variables d’environnement

Vous pouvez personnaliser le mappage entre les variables d’environnement de vos pipelines CI/CD sources avec leurs valeurs dans GitHub Actions.

GitHub Actions Importer utilise des transformateurs personnalisés qui sont définis à l’aide d’un DSL basé sur Ruby. Pour créer des transformateurs personnalisés pour les variables d’environnement :

  • Le fichier de transformateur personnalisé doit avoir au moins une méthode env.
  • La méthode env accepte deux paramètres. Le premier paramètre est le nom de la variable d’environnement dans le pipeline d’origine, et le second est la valeur mise à jour de la variable d’environnement pour GitHub Actions. Pour plus d’informations sur les variables d’environnement GitHub Actions, consultez « Variables ».

Exemples de transformateurs personnalisés pour les variables d’environnement

Il existe plusieurs façons de configurer des transformateurs personnalisés pour mapper vos variables d’environnement.

  • L’exemple suivant définit la valeur de toutes les variables d’environnement existantes nommées OCTO, sur CAT, lors de la transformation d’un pipeline.

    Ruby
    env "OCTO", "CAT"

    Vous pouvez également supprimer toutes les instances d’une variable d’environnement spécifique afin qu’elles ne soient pas transformées en workflows GitHub Actions. L’exemple suivant supprime toutes les variables d’environnement portant le nom MONA_LISA.

    Ruby
    env "MONA_LISA", nil

  • Vous pouvez également mapper vos variables d’environnement existantes aux secrets. Par exemple, la méthode env suivante mappe une variable d’environnement nommée MONALISA à un secret nommé OCTOCAT.

    Ruby
    env "MONALISA", secret("OCTOCAT")

    Cette opération configure une référence à un secret nommé OCTOCAT dans le workflow transformé. Pour que le secret fonctionne, vous devez créer le secret dans votre dépôt GitHub. Pour plus d’informations, consultez « Utilisation de secrets dans GitHub Actions ».

  • Vous pouvez également utiliser des expressions régulières pour mettre à jour les valeurs de plusieurs variables d’environnement à la fois. Par exemple, le transformateur personnalisé suivant supprime toutes les variables d’environnement du workflow converti :

    Ruby
    env /.*/, nil

    L’exemple suivant utilise un groupe de correspondances d’expression régulière pour transformer les valeurs des variables d’environnement en secrets générés dynamiquement.

    Ruby
    env /^(.+)_SSH_KEY/, secret("%s_SSH_KEY)

    Remarque : L’ordre dans lequel les méthodes env sont définies est important lors de l’utilisation d’expressions régulières. Le premier transformateur env qui correspond à un nom de variable d’environnement est prioritaire sur les méthodes env suivantes. Vous devez d’abord définir vos transformateurs de variables d’environnement les plus spécifiques.

Certaines parties ont été adaptées à partir de https://github.com/github/gh-actions-importer/ sous la licence MIT :

MIT License

Copyright (c) 2022 GitHub

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.