Ausführen von Skripts vor oder nach einem Auftrag

Skripts können direkt vor oder nach einem Auftrag automatisch auf einem selbstgehosteten Runner ausgeführt werden.

In diesem Artikel

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 im Folgenden unter Auslösen der Skripts.

Die folgenden Skriptsprachen werden unterstützt:

  • Bash: Verwendet bash und kann auf sh zurückgreifen. Wird ausgeführt, indem -e {pathtofile} ausgeführt wird.
  • PowerShell: Verwendet pwsh und kann auf powershell zurückgreifen. Wird ausgeführt, indem -command \". '{pathtofile}'\" ausgeführt wird.

Schreiben der Skripts

Deine benutzerdefinierten Skripts können die folgenden Features verwenden:

Deine Skriptdateien müssen eine Dateierweiterung für die entsprechende Sprache verwenden, z. B. .sh oder .ps1, um erfolgreich ausgeführt zu werden.

Hinweis: Vermeide die Verwendung 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.

Hinweis: Die ausgelösten Skripts werden synchron verarbeitet, sodass sie die Auftragsausführung während ihrer Ausführung 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

Hinweis: Das in ACTIONS_RUNNER_HOOK_JOB_COMPLETED definierte Skript wird am Ende des Auftrags ausgeführt, bevor der Auftrag 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

Informationen zur Verwendung von Workflows zum Ausführen von Skripts finden Sie 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.