Informationen zu benutzerdefinierten Transformatoren
GitHub Actions Importer bietet die Möglichkeit, die integrierte Zuordnung durch die Erstellung benutzerdefinierter Transformatoren zu erweitern. Benutzerdefinierte Transformatoren können für folgende Zwecke verwendet werden:
- Konvertieren von Elementen, die von GitHub Actions Importer nicht automatisch konvertiert werden, oder Ändern der Konvertierung von Elementen. Weitere Informationen findest du unter Erstellen benutzerdefinierter Transformatoren für Elemente.
- Konvertieren von Verweisen in Runner, um unterschiedliche Runnerbezeichnungen zu verwenden. Weitere Informationen findest du unter Erstellen benutzerdefinierter Transformatoren für Runner.
- Konvertieren von Umgebungsvariablenwerten aus deinen vorhandenen Pipelines in GitHub Actions-Workflows. Weitere Informationen findest du unter Erstellen benutzerdefinierter Transformatoren für Umgebungsvariablen.
Verwenden benutzerdefinierter Transformatoren mit GitHub Actions Importer
Ein benutzerdefinierter Transformator enthält eine Zuordnungslogik, mit deren Hilfe GitHub Actions Importer deine Plug-Ins, Aufgaben, Runnerbezeichnungen oder Umgebungsvariablen so transformieren kann, dass sie mit GitHub Actions eingesetzt werden können. 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 benutzerdefinierte Transformatoren beispielsweise in einer Datei namens transformers.rb
definiert sind, kannst du sie über den folgenden Befehl mit GitHub Actions Importer verwenden:
gh actions-importer ... --custom-transformers transformers.rb
Alternativ kannst du die Globmustersyntax verwenden, um mehrere benutzerdefinierte Transformatordateien anzugeben. Wenn sich beispielsweise mehrere benutzerdefinierte Transformatordateien in einem Verzeichnis namens transformers
befinden, kannst du sie alle über den folgenden Befehl für GitHub Actions Importer 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
Du kannst benutzerdefinierte Transformatoren erstellen, die von GitHub Actions Importer beim Konvertieren vorhandener Buildschritte oder Trigger in ihr GitHub Actions-Äquivalent verwendet werden. Dies ist besonders in folgenden Fällen nützlich:
- Ein Element wird von GitHub Actions Importer nicht automatisch konvertiert.
- Du möchtest ändern, wie ein Element von GitHub Actions Importer konvertiert wird.
- Deine vorhandenen Pipelines verwenden benutzerdefinierte oder proprietäre Erweiterungen, z. B. freigegebene Bibliotheken in Jenkins, und du musst die Funktionsweise dieser Schritte in GitHub Actions definieren.
GitHub Actions Importer verwendet benutzerdefinierte Transformatoren, die mithilfe einer DSL auf Ruby-Basis definiert werden. So erstellst du benutzerdefinierte Transformatoren für Buildschritte und Trigger:
- Jede benutzerdefinierte Transformatordatei muss mindestens eine
transform
-Methode enthalten. - Jede
transform
-Methode muss einHash
, ein Array ausHash
-Elementen odernil
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 Buildschritt
Im folgenden Beispiel wird ein Buildschritt konvertiert, der den Bezeichner „buildJavascriptApp“ verwendet, um verschiedene npm
-Befehle auszuführen:
transform "buildJavaScriptApp" do |item| command = ["build", "package", "deploy"].map do |script| "npm run #{script}" end { name: "build javascript app", run: command.join("\n") } end
transform "buildJavaScriptApp" do |item|
command = ["build", "package", "deploy"].map do |script|
"npm run #{script}"
end
{
name: "build javascript app",
run: command.join("\n")
}
end
Das obige Beispiel führt zu dem folgenden GitHub Actions-Workflowschritt. 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
Du kannst die Zuordnung zwischen Runnern in deiner CI/CD-Quellinstanz und den entsprechenden GitHub Actions-Runnern anpassen.
GitHub Actions Importer verwendet benutzerdefinierte Transformatoren, die mithilfe einer DSL auf Ruby-Basis definiert werden. So erstellst du benutzerdefinierter Transformatoren für Runner:
- Die benutzerdefinierte Transformatordatei muss mindestens eine
runner
-Methode enthalten. - Die
runner
-Methode akzeptiert zwei Parameter. Der erste Parameter ist die Runnerbezeichnung der CI/CD-Quellinstanz, und der zweite Parameter ist die entsprechende GitHub Actions-Runnerbezeichnung. Weitere Informationen zu GitHub Actions-Runnern finden Sie unter Verwenden von auf GitHub gehosteten Runnern.
Beispiele für benutzerdefinierte Transformatoren für Runner
Das folgende Beispiel zeigt eine runner
-Methode, die eine Runnerbezeichnung in eine GitHub Actions-Runnerbezeichnung im resultierenden Workflow konvertiert.
runner "linux", "ubuntu-latest"
runner "linux", "ubuntu-latest"
Du kannst die runner
-Methode auch verwenden, um eine Runnerbezeichnung in mehrere GitHub Actions-Runnerbezeichnungen im resultierenden Workflow zu konvertieren.
runner "big-agent", ["self-hosted", "xl", "linux"]
runner "big-agent", ["self-hosted", "xl", "linux"]
GitHub Actions Importer versucht, die Runnerbezeichnung so gut wie möglich zuzuordnen. In Fällen, in denen dies nicht möglich ist, wird die ubuntu-latest
-Runnerbezeichnung 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
als Standardrunner zu verwenden.
runner :default, "macos-latest"
runner :default, "macos-latest"
Erstellen benutzerdefinierter Transformatoren für Umgebungsvariablen
Die Zuordnung zwischen Umgebungsvariablen in deinen CI/CD-Quellpipelines und deren Werten in GitHub Actions kann angepasst werden.
GitHub Actions Importer verwendet benutzerdefinierte Transformatoren, die mithilfe einer DSL auf Ruby-Basis definiert werden. 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 Umgebungsvariablen in der ursprünglichen Pipeline, und der zweite Parameter entspricht dem aktualisierten Wert für die Umgebungsvariable für GitHub Actions. Weitere Informationen zu GitHub Actions-Umgebungsvariablen findest du 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 aufCAT
festgelegt.Ruby env "OCTO", "CAT"
env "OCTO", "CAT"
Du kannst auch alle Instanzen einer bestimmten Umgebungsvariablen entfernen, damit 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
env "MONA_LISA", nil
-
Du kannst deine vorhandenen Umgebungsvariablen auch Geheimnissen zuordnen. Durch die folgende
env
-Methode wird z. B. eine Umgebungsvariable namensMONALISA
einem Geheimnis namensOCTOCAT
zugeordnet.Ruby env "MONALISA", secret("OCTOCAT")
env "MONALISA", secret("OCTOCAT")
Dadurch wird ein Verweis auf ein Geheimnis namens
OCTOCAT
im transformierten Workflow eingerichtet. Damit das Geheimnis funktioniert, musst du das Geheimnis in deinem GitHub-Repository erstellen. Weitere Informationen findest du 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
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)
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 ersteenv
-Transformator, der mit einem Umgebungsvariablennamen übereinstimmt, hat Vorrang vor nachfolgendenenv
-Methoden. Du solltest zuerst deine spezifischsten Umgebungsvariablentransformatoren definieren.
Rechtliche Hinweise
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.