Das Erweitern des GitHub Actions Importers mit benutzerdefinierten Transformatoren

GitHub Actions Importer bietet die Möglichkeit, die integrierte Zuordnung zu erweitern.

In diesem Artikel

Informationen zu benutzerdefinierten Transformatoren

GitHub Actions Importer bietet die Möglichkeit, die integrierte Zuordnung durch die Erstellung von benutzerdefinierten Transformatoren zu erweitern. Benutzerdefinierte Transformatoren können für folgende Zwecke verwendet werden:

Verwenden von benutzerdefinierten Transformatoren mit GitHub Actions Importer

Ein benutzerdefinierter Transformator enthält Zuordnungslogik, mit der GitHub Actions Importer Sie Ihre Plug-Ins, Aufgaben, Läuferbezeichnungen oder Umgebungsvariablen transformieren können, um mit GitHub Actionsihnen zu arbeiten. Benutzerdefinierte Transformatoren werden in einer domänenspezifischen Sprache (DSL) auf Ruby-Basis geschrieben und in einer Datei mit der Dateierweiterung .rb definiert.

Anhand der CLI-Option --custom-transformers kannst du angeben, welche benutzerdefinierten Transformatordateien mit den Befehlen audit, dry-run und migrate verwendet werden sollen.

Wenn beispielsweise benutzerdefinierte Transformatoren in einer Datei mit dem Namen transformers.rbdefiniert sind, können Sie den folgenden Befehl verwenden, um sie mit GitHub Actions Importer:

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

Alternativ kannst du die Globmustersyntax verwenden, um mehrere benutzerdefinierte Transformatordateien anzugeben. Wenn sich z. B. mehrere benutzerdefinierte Transformatordateien in einem Verzeichnis namens transformersbefinden, können Sie sie mit GitHub Actions Importer dem folgenden Befehl bereitstellen:

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

Hinweis

Wenn du benutzerdefinierte Transformatoren verwendest, müssen sich die benutzerdefinierten Transformatordateien in demselben Verzeichnis (oder in einem Unterverzeichnis) befinden, von dem aus der Befehl gh actions-importer ausgeführt wird.

Erstellen benutzerdefinierter Transformatoren für Elemente

Sie können benutzerdefinierte Transformatoren erstellen, die GitHub Actions Importer beim Konvertieren vorhandener Buildschritte oder Trigger in ihre Entsprechung GitHub Actionsverwendet werden. Dies ist besonders in folgenden Fällen nützlich:

  • GitHub Actions Importer konvertiert ein Element nicht automatisch.
  • Sie möchten ändern, wie ein Element konvertiert wird.GitHub Actions Importer
  • Ihre vorhandenen Pipelines verwenden benutzerdefinierte oder proprietäre Erweiterungen, z. B. freigegebene Bibliotheken in Jenkins, und Sie müssen definieren, wie diese Schritte funktionieren GitHub Actionssollen.

GitHub Actions Importer verwendet benutzerdefinierte Transformatoren, die mit einem DSL definiert werden, das auf Ruby basiert. So erstellen Sie benutzerdefinierte Transformer für Build-Schritte und Trigger:

  • Jede benutzerdefinierte Transformatordatei muss mindestens eine transform-Methode enthalten.
  • Jede transform-Methode muss ein Hash, ein Array aus Hash-Elementen oder nil zurückgeben. Dieser zurückgegebene Wert entspricht einer in YAML definierten Aktion. Weitere Informationen zu Aktionen findest du unter Grundlegendes zu GitHub Actions.

Beispiel für einen benutzerdefinierten Transformator für einen Build-Schritt

Im folgenden Beispiel wird ein Buildschritt konvertiert, der den Bezeichner „buildJavascriptApp“ verwendet, um verschiedene npm-Befehle auszuführen:

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

Im obigen Beispiel wird der folgende GitHub Actions Workflowschritt ausgeführt. Es besteht aus konvertierten Buildschritten mit einem buildJavaScriptApp-Bezeichner:

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

Die transform-Methode verwendet den Bezeichner des Buildschritts aus deiner CI/CD-Quellinstanz in einem Argument. In diesem Beispiel heißt der Bezeichner buildJavaScriptLibrary. Du kannst auch durch Trennzeichen getrennte Werte verwenden, um mehrere Bezeichner an die transform-Methode zu übergeben. Beispiel: transform "buildJavaScriptApp", "buildTypeScriptApp" { |item| ... }.

Hinweis

Die Datenstruktur von item ist je nach CI/CD-Plattform und dem Typ des zu konvertierenden Elements unterschiedlich.

Erstellen benutzerdefinierter Transformatoren für Runner

Sie können die Zuordnung zwischen Läufern in Ihrer CI/CD-Quellinstanz und den entsprechenden GitHub Actions Läufern anpassen.

GitHub Actions Importer verwendet benutzerdefinierte Transformatoren, die mit einem DSL definiert werden, das auf Ruby basiert. So erstellst du benutzerdefinierte Transformatoren für Runner:

  • Die benutzerdefinierte Transformatordatei muss mindestens eine runner-Methode enthalten.
  • Die runner-Methode akzeptiert zwei Parameter. Der erste Parameter ist die Läuferbezeichnung der Quell-CI/CD-Instanz, und der zweite Parameter ist die entsprechende GitHub Actions Läuferbezeichnung. Weitere Informationen zu GitHub Actions Läufern finden Sie unter Von GitHub gehostete Runner.

Beispiele für benutzerdefinierte Transformatoren für Runner

Das folgende Beispiel zeigt eine Methode, die eine runner Läuferbezeichnung in eine GitHub Actions Läuferbezeichnung im resultierenden Workflow konvertiert.

Ruby
runner "linux", "ubuntu-latest"

Sie können die runner Methode auch verwenden, um eine Läuferbezeichnung in mehrere GitHub Actions Läuferbeschriftungen im resultierenden Workflow zu konvertieren.

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

GitHub Actions Importer versucht, die Beschriftung der Läufer so zuzuordnen, dass dies am besten möglich ist. In Fällen, in denen dies nicht möglich ist, wird das ubuntu-latest-Runner-Label als Standard verwendet. Dieser Standardwert lässt sich mit der runner-Methode über ein spezielles Schlüsselwort steuern. Der folgende benutzerdefinierte Transformator weist GitHub Actions Importer z. B. an macos-latest , anstelle von ubuntu-latest.

Ruby
runner :default, "macos-latest"

Erstellen benutzerdefinierter Transformatoren für Umgebungsvariablen

Sie können die Zuordnung zwischen Umgebungsvariablen in Ihren Quell-CI/CD-Pipelines an ihre Werte anpassen in GitHub Actions.

GitHub Actions Importer verwendet benutzerdefinierte Transformatoren, die mit einem DSL definiert werden, das auf Ruby basiert. So erstellst du benutzerdefinierte Transformatoren für Umgebungsvariablen:

  • Die benutzerdefinierte Transformatordatei muss mindestens eine env-Methode enthalten.
  • Die env-Methode akzeptiert zwei Parameter. Der erste Parameter ist der Name der Umgebungsvariable in der ursprünglichen Pipeline, und der zweite Parameter ist der aktualisierte Wert für die Umgebungsvariable für GitHub Actions. Weitere Informationen zu GitHub Actions Umgebungsvariablen finden Sie unter Speichern von Informationen in Variablen.

Beispiele für benutzerdefinierte Transformatoren für Umgebungsvariablen

Es gibt mehrere Möglichkeiten zum Einrichten benutzerdefinierter Transformatoren für die Zuordnung deiner Umgebungsvariablen.

  • Im folgenden Beispiel wird der Wert aller vorhandenen Umgebungsvariablen namens OCTO beim Transformieren einer Pipeline auf CAT festgelegt.

    Ruby
    env "OCTO", "CAT"

    Sie können auch alle Instanzen einer bestimmten Umgebungsvariable entfernen, sodass sie nicht in einen GitHub Actions Workflow transformiert werden. Im folgenden Beispiel werden alle Umgebungsvariablen mit dem Namen MONA_LISA entfernt.

    Ruby
    env "MONA_LISA", nil

  • Du kannst deine vorhandenen Umgebungsvariablen auch Geheimnissen zuordnen. Durch die folgende env-Methode wird z. B. eine Umgebungsvariable namens MONALISA einem Geheimnis namens OCTOCAT zugeordnet.

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

    Dadurch wird ein Verweis auf ein Geheimnis namens OCTOCAT im transformierten Workflow eingerichtet. Damit der geheime Schlüssel funktioniert, müssen Sie den geheimen Schlüssel in Ihrem GitHub Repository erstellen. Weitere Informationen finden Sie unter Verwenden von Geheimnissen in GitHub-Aktionen.

  • Du kannst auch reguläre Ausdrücke verwenden, um die Werte mehrerer Umgebungsvariablen gleichzeitig zu aktualisieren. Der folgende benutzerdefinierte Transformator entfernt beispielsweise alle Umgebungsvariablen aus dem konvertierten Workflow:

    Ruby
    env /.*/, nil

    Im folgenden Beispiel wird eine Übereinstimmungsgruppe für reguläre Ausdrücke verwendet, um Umgebungsvariablenwerte in dynamisch generierte Geheimnisse zu transformieren.

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

    Hinweis

    Die Reihenfolge, in der env-Methoden definiert werden, ist bei der Verwendung regulärer Ausdrücke relevant. Der erste env-Transformator, der mit einem Umgebungsvariablennamen übereinstimmt, hat Vorrang vor nachfolgenden env-Methoden. Du solltest zuerst deine spezifischsten Umgebungsvariablentransformatoren definieren.

Teile wurden von https://github.com/github/gh-actions-importer/ unter der MIT-Lizenz übernommen:

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.