Extension de GitHub Actions Importer avec des transformateurs personnalisés

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

Dans cet article

À 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, libellés d’exécuteur ou variables d’environnement afin de fonctionner 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 de transformateur personnalisés se trouvent dans un répertoire nommé transformers, vous pouvez tous les fournir à GitHub Actions Importer à l’aide de 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 dans des sous-répertoires, à 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 qui GitHub Actions Importer seront utilisés 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, telles que des bibliothèques partagées dans Jenkins, et vous devez définir la façon dont ces étapes doivent fonctionner dans GitHub Actions.

GitHub Actions Importer utilise des transformateurs personnalisés définis à l’aide d’une DSL basée sur Ruby. Pour créer des transformateurs personnalisés pour les étapes de compilation 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 « Présentation des GitHub Actions ».

Exemple de transformateur personnalisé pour une étape de compilation

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 flux de travail suivante GitHub Actions . Il se compose d'étapes de compilation 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 runners

Vous pouvez personnaliser la correspondance entre les exécuteurs de votre instance CI/CD source et leurs exécuteurs GitHub Actions équivalents.

GitHub Actions Importer utilise des transformateurs personnalisés définis à l’aide d’une DSL basée sur Ruby. Pour créer des transformateurs personnalisés pour les coureurs :

  • 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 le libellé du runner de l’instance CI/CD source, et le deuxième paramètre est le libellé correspondant du runner GitHub Actions. Pour plus d’informations sur les GitHub Actions runners, consultez Exécuteurs hébergés par GitHub.

Exemples de transformateurs personnalisés pour les runners

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 flux de travail obtenu.

Ruby
runner "linux", "ubuntu-latest"

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

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

GitHub Actions Importer tente de faire correspondre au mieux le libellé du runner. 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 la correspondance entre les variables d’environnement dans vos pipelines CI/CD sources et leurs valeurs dans GitHub Actions.

GitHub Actions Importer utilise des transformateurs personnalisés définis à l’aide d’une DSL basée 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 deuxième paramètre 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 Stocker des informations dans des 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 GitHub Actions flux de travail. 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.