Informationen zu Skripts vor und nach einem Auftrag
Du kannst Skripts automatisch auf einem selbstgehosteten Runner ausführen, entweder vor einer Auftragsausführung oder nach Abschluss der Ausführung eines Auftrags. Diese Skripts können verwendet werden, um die Anforderungen des Auftrags zu unterstützen (z. B. das Erstellen oder Bereinigen einer Runnerumgebung oder das Bereinigen von Verzeichnissen). Du kannst diese Skripts auch verwenden, um Telemetriedaten dazu nachzuverfolgen, wie deine Runner verwendet werden.
Die benutzerdefinierten Skripts werden automatisch ausgelöst, wenn eine bestimmte Umgebungsvariable für den Runner festgelegt wird. Die Umgebungsvariable muss den absoluten Pfad zum Skript enthalten. Weitere Informationen findest du unter Auslösen der Skripts weiter unten.
Die folgenden Skriptsprachen werden unterstützt:
- Bash: Verwendet
bash
und kann aufsh
zurückgreifen. Wird ausgeführt, indem-e {pathtofile}
ausgeführt wird. - PowerShell: Verwendet
pwsh
und kann aufpowershell
zurückgreifen. Wird ausgeführt, indem-command \". '{pathtofile}'\"
ausgeführt wird.
Schreiben der Skripts
Deine benutzerdefinierten Skripts können die folgenden Features verwenden:
- Variablen: Über Skripts kann auf die Standardvariablen zugegriffen werden. Die vollständigen Webhook-Ereignisnutzdaten findest du in
GITHUB_EVENT_PATH
. Weitere Informationen finden Sie unter Speichern von Informationen in Variablen. - Workflowb-Befehle: Skripts können Workflow-Befehle verwenden. Weitere Informationen finden Sie unter Workflow commands for GitHub Actions (Workflowbefehle für GitHub Actions). Skripts können auch Umgebungsdateien verwenden. Weitere Informationen findest du unter Umgebungsdateien.
Deine Skriptdateien müssen eine Dateierweiterung für die entsprechende Sprache verwenden, z. B. .sh
oder .ps1
, um erfolgreich ausgeführt zu werden.
Note
Vermeide das Verwenden deiner Skripts zum Ausgeben vertraulicher Informationen in die Konsole, da jede Person mit Lesezugriff auf das Repository möglicherweise die Ausgabe in den Benutzeroberflächenprotokollen anzeigen kann.
Behandeln von Exitcodes
Bei Skripts vor Aufträgen gibt der Exitcode 0
an, dass das Skript erfolgreich abgeschlossen wurde, und der Auftrag wird dann ausgeführt. Wenn ein anderer Exitcode vorhanden ist, wird der Auftrag nicht ausgeführt und als fehlerhaft markiert. Um die Ergebnisse deiner Skripts vor Aufträgen anzuzeigen, überprüfe die Protokolle auf Set up runner
-Einträge. Weitere Informationen zum Überprüfen der Protokolle findest du unter Verwenden von Workflowausführungsprotokollen.
Die continue-on-error
-Einstellung wird für die Verwendung durch diese Skripts nicht unterstützt.
Auslösen der Skripts
Die benutzerdefinierten Skripts müssen sich auf dem Runner befinden, sollten aber nicht im Anwendungsverzeichnis actions-runner
gespeichert werden. Die Skripts werden im Sicherheitskontext des Dienstkontos ausgeführt, das den Runnerdienst ausführt.
Note
Die ausgelösten Skripts werden synchron verarbeitet, sodass sie die Auftragsausführung während dem Ausführen blockieren.
Die Skripts werden automatisch ausgeführt, wenn der Runner über die folgenden Umgebungsvariablen verfügt, die einen absoluten Pfad zum Skript enthalten:
ACTIONS_RUNNER_HOOK_JOB_STARTED
: Das in dieser Umgebungsvariablen definierte Skript wird ausgelöst, wenn einem Runner ein Auftrag zugewiesen wurde, aber bevor die Ausführung des Auftrags gestartet wird.ACTIONS_RUNNER_HOOK_JOB_COMPLETED
: Das in dieser Umgebungsvariable definierte Skript wird am Ende des Auftrags ausgelöst, nachdem alle im Workflow definierten Schritte ausgeführt wurden.
Um diese Umgebungsvariablen festzulegen, können Sie sie entweder dem Betriebssystem oder einer Datei mit dem Namen .env
im selbstgehosteten Runner-Anwendungsverzeichnis hinzufügen (d. h. dem Verzeichnis, in das Sie die Runner-Software heruntergeladen und entpackt haben). Beispielsweise führt der folgende .env
-Eintrag dazu, dass der Runner automatisch ein Skript ausführt, das als /opt/runner/cleanup_script.sh
auf dem Runner-Computer gespeichert wird, bevor jeder Job ausgeführt wird:
ACTIONS_RUNNER_HOOK_JOB_STARTED=/opt/runner/cleanup_script.sh
Note
Das in ACTIONS_RUNNER_HOOK_JOB_COMPLETED
definierte Skript wird am Ende des Auftrags ausgeführt, bevor er abgeschlossen wird. Dadurch wird es ungeeignet für Anwendungsfälle, die einen Runner unterbrechen können, z. B. durch Löschen des Runner-Computers im Rahmen einer Implementierung zur automatischen Skalierung.
Problembehandlung
Berechtigung verweigert
Wenn Sie beim Versuch, ein Skript auszuführen, die Fehlermeldung „Berechtigung verweigert“ erhalten, stellen Sie sicher, dass das Skript ausführbar ist. Beispielsweise können Sie in einem Terminal unter Linux oder MacOS den folgenden Befehl verwenden, um eine Datei ausführbar zu machen.
chmod +x PATH/TO/FILE
Weitere Informationen zum Verwenden von Workflows zum Ausführen von Skripts findest du unter Hinzufügen von Skripts zu deinem Workflow.
Keine Timeouteinstellung
Es ist derzeit keine Timeouteinstellung für Skripts verfügbar, die von ACTIONS_RUNNER_HOOK_JOB_STARTED
oder ACTIONS_RUNNER_HOOK_JOB_COMPLETED
ausgeführt werden. Du könntest daher in Erwägung ziehen, deinem Skript Timeoutverarbeitung hinzuzufügen.
Überprüfen des Workflow-Ausführungsprotokolls
Um zu bestätigen, dass deine Skripts ausgeführt werden, kannst du die Protokolle für diesen Auftrag überprüfen. Die Skripts werden in separaten Schritten für Set up runner
oder Complete runner
aufgeführt, je nachdem, welche Umgebungsvariable das Skript auslöst. Weitere Informationen zum Überprüfen der Protokolle findest du unter Verwenden von Workflowausführungsprotokollen.