Sichere Verwendung von pull_request_target

In diesem Leitfaden können Sie beurteilen, ob Ihr Workflow das pull_request_target Ereignis verwenden und die sicherheitsrelevanten Risiken verstehen soll. Außerdem wird erläutert, welche Schutzmaßnahmen GitHub standardmäßig auf diese Risiken anwendet und wie man diese Schutzmaßnahmen bei Bedarf abwählen kann.

Risiken von pull_request_target

Workflows, die durch pull_request_target ausgelöst werden, werden mit erhöhten Vertrauensrechten ausgeführt: Der Job erhält das GITHUB_TOKEN des Basis-Repositorys sowie Zugriff auf Repository- und Organisationsgeheimnisse. Dies ist dasselbe Vertrauen, das auch Ereignissen wie push entgegengebracht wird, die nur von Mitwirkenden ausgelöst werden können, und genau das macht pull_request_target nützlich für Automatisierungen, die auf Pull Requests aus Forks reagieren, etwa zum Zuweisen von Labels, zur Triage oder zum Veröffentlichen authentifizierter Statusprüfungen.

Um zu verstehen, warum dies standardmäßig sicher ist und wie diese Sicherheit häufig unterbrochen wird, überprüfen Sie pull_request_target auf pull_request.

Das pull_request Ereignis (zusammen mit pull_request_review und pull_request_review_comment) ist ungewöhnlich: Es führt die Workflowdatei aus dem Zusammenführungs-Commit der Pullanforderung aus. Bei einem Pull Request, der aus einem Fork erstellt wurde, stammt dieser Commit von jemandem, der keinen Schreibzugriff auf das Basis-Repository hat. Um nicht vertrauenswürdigen Workflow-Code sicher auszuführen, GitHub beschränkt diese Ereignisse auf ein schreibgeschütztes GITHUB_TOKEN, verweigert den Zugriff auf andere Geheimnisse und wendet Fork-Genehmigungsrichtlinien an, um den Missbrauch von Rechenressourcen zu verhindern. Standardmäßig checkt actions/checkout in einem pull_request-Workflow auch den Merge-Commit des Pull Requests aus, sodass der ausgecheckte Code und der ausgeführte Workflow übereinstimmen.

pull_request_target nimmt eine wichtige und subtile Änderung vor: Der Workflow und jeder nachfolgende actions/checkout-Aufruf, der keinen ref angibt, werden aus dem Standard-Branch des Basis-Repositorys und nicht aus dem Pull Request übernommen. Da nur vertrauenswürdiger Code aus dem Standard-Branch ausgeführt wird, ist es sicher, Geheimnisse und ein Token mit Lese- und Schreibzugriff zu gewähren. Standardmäßig wird kein Code aus dem Fork ausgeführt.

Sie gehen ein Risiko ein, wenn der Autor eines Workflows diesen Standardwert außer Kraft setzt, um den Code des Forks auszuführen. Entwickler wählen pull_request_target häufig aus, weil sie die Pullanforderung einer Verzweigung über CI ausführen möchten und Zugriff auf geheime Schlüssel haben, z. B. zum Ausführen von Tests, die eine private Registrierung benötigen. Dazu richten sie actions/checkout auf den Head des Pull Requests statt auf den Standard-Branch, was unsicher ist:

# INSECURE. Provided as an example only.
on:
  pull_request_target:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
      - name: Test
        run: make test

Der Auscheckschritt allein führt keinen nicht vertrauenswürdigen Code aus. Die Workflowdatei selbst stammt weiterhin aus dem Standard-Branch. Die Sicherheitsanfälligkeit wird durch den nächsten Schritt abgeschlossen, in dem Code ausgeführt wird, der im aktuellen Arbeitsverzeichnis ausgecheckt ist. Hier führt make test ein Makefile aus, das vom Head der Pull-Anfrage stammt. Ein Angreifer muss nur einen Pull Request aus einem Fork öffnen, dessen Makefile (oder Build-Skript, Testbefehl, Abhängigkeit oder Konfigurationsdatei) schädliche Befehle enthält. Diese Befehle werden dann mit den geheimen Schlüsseln und Token des Basis-Repositorys ausgeführt.

Dieses Muster wird als "pwn-Anforderung" bezeichnet und ist die Ursache mehrerer Lieferkettenkompromittierungen. Weitere Informationen finden Sie unter Verhindern von Pwn-Anfragen im GitHub Security Lab. Zu den gängigen verwundbaren Formen gehören:

• Auschecken des Head- oder Merge-Commits eines Pull Requests in actions/checkout (ref: ${{ github.event.pull_request.head.sha }}, ref: refs/pull/${{ github.event.pull_request.number }}/merge) und anschließendes Erstellen, Testen oder anderweitiges Ausführen des Ergebnisses.
• repository: auf den Fork (repository: ${{ github.event.pull_request.head.repo.full_name }}) festlegen, um den Branch des Forks direkt abzurufen.
• Abrufen des Codes des Pull Requests außerhalb von actions/checkout (zum Beispiel mit git fetch, gh pr checkout oder durch Herunterladen eines Artefakts aus einem pull_request-Lauf eines Forks) und anschließendes Ausführen.

Pwn-Anfragen sind auch nicht auf pull_request_target beschränkt. Jedes Ereignis, das mit geheimen Schlüsseln ausgeführt wird, kann eine pwn-Anforderung einführen, wenn es nicht vertrauenswürdigen Code auscheckt oder herunterlädt und ausführt. Beispielsweise ist ein issue_comment oder workflow_run Workflow, der den Code eines Pull Requests eines Forks abruft und ausführt, auf die gleiche Weise anfällig. Ein workflow_run Workflow sollte Artefakte, die von anderen Workflows hochgeladen wurden, als nicht vertrauenswürdige Daten behandeln, da ihr Inhalt aus einem Fork stammen kann.

Standardrichtlinie für pull_request_target

Um Ihre Workflows vor nicht vertrauenswürdigen Pullanforderungen zu schützen, stellt eine Standardereignisrichtlinie bereit, GitHub die das pull_request_target Ereignis in öffentlichen Repositorys blockiert.

Funktionsweise der Standardrichtlinie

Für öffentliche Repositorys, die noch nicht über eine entsprechende Aktionsereignisrichtlinie verfügen, fügt GitHub eine Standardrichtlinie hinzu, die Workflows blockiert, die durch pull_request_targetausgelöst werden. Weitere Informationen zu Richtlinien finden Sie unter Informationen zu den Actions-Richtlinien.

Die Standardrichtlinie:

• Gilt nicht für private oder interne Repositorys.
• Ersetzt keine anwendbare Ereignisrichtlinie, die Sie bereits konfiguriert haben.
• Wird derzeit im Auswertungsmodus ausgeführt. In diesem Modus werden Workflowausführungen weiterhin ausgeführt, Sie können jedoch mithilfe von Richtlinienerkenntnissen Ausführungen identifizieren, die nach der Durchsetzung blockiert würden.

Am 2. November 2026 erzwingt GitHub die Standardrichtlinie für betroffene Repositorys, die die Standardrichtlinie pull_request_target vor der allgemeinen Verfügbarkeit verwendet haben.

Überprüfen der Auswirkungen vor der Durchsetzung

Während sich die Richtlinie im Auswertungsmodus befindet, überprüfen Sie die Erkenntnisse zu Ihrer Richtlinie, um Workflows zu identifizieren, die pull_request_target verwenden und bei Durchsetzung der Richtlinie blockiert würden.

Entscheiden Sie für jeden betroffenen Workflow, ob pull_request_target noch erforderlich ist:

• Wenn der Workflow pull_request_target nicht benötigt, aktualisieren Sie ihn, damit er gegebenenfalls ein sichereres Ereignis verwendet, z. B. pull_request.
• Wenn der Workflow weiterhin pull_request_target verwenden muss, erstellen oder aktualisieren Sie eine entsprechende Actions-Ereignisrichtlinie, die pull_request_target ausdrücklich zulässt.
• Wenn Sie pull_request_target nicht zulassen möchten, behalten Sie die Standardrichtlinie bei. Nach der Erzwingung blockiert GitHub Workflows, die durch dieses Ereignis ausgelöst werden.

Weitere Informationen zum Konfigurieren von Ereignisrichtlinien und zum Anzeigen von Einblicken finden Sie unter Steuern, wer GitHub ActionsWorkflows ausführen kann. Informationen zum programmgesteuerten Verwalten von Richtlinien finden Sie unter REST-API-Endpunkte für GitHub Actions-Richtlinien.

Entscheiden, ob pull_request_target verwendet werden soll

Einige Workflows müssen den Code von Pull Requests aus Forks mit erhöhtem Vertrauensniveau auschecken, und genau deshalb wurde pull_request_target überhaupt erst geschaffen. Zum Beispiel das Erstellen von Coverage-Berichten, die eine private Artefakt-Registry erfordern, oder das Erstellen und Ausführen authentifizierter Prüfungen für die durch den Pull Request eingeführten Änderungen. Berücksichtigen Sie die folgenden Fragen, bevor Sie pull_request_target verwenden oder das allow-unsafe-pr-checkout-Flag in actions/checkout aktivieren.

• Können Sie stattdessen verwenden pull_request ? pull_request wird durch dieselben Ereignisse ausgelöst wie pull_request_target und führt den Workflow-Code aus dem Merge-Branch pull_request aus. Dies erfolgt bei Pull Requests aus Forks auf sichere Weise und mit den oben beschriebenen Schutzmaßnahmen. Wenn kein zusätzlicher geheimer Zugriff erforderlich ist, verwenden Sie pull_request. Komplexere Workflows können neu strukturiert werden, um die potenziell gefährliche Behandlung von Pull-Anforderungscode vom Zugriff auf geheime Schlüssel zu trennen. Weitere Informationen finden Sie unter Verhindern von Pwn-Anfragen im GitHub Security Lab.

• Wird der ausgecheckte Code jemals ausgeführt? Dies ist der Fehler, der pwn-Anforderungsrisiken einführt. Am häufigsten geschieht dies mit actions/checkout, indem Sie den Head eines Pull-Requests in das Arbeitsverzeichnis auschecken und ihn anschließend ausführen. Wenn die path Eingabe nicht festgelegt ist, actions/checkout wird der Code in das $GITHUB_WORKSPACE Verzeichnis geschrieben, das in der Regel das Arbeitsverzeichnis ist, in dem nachfolgende Befehle ausgeführt werden. Die Ausführung ist nicht auf Ihre eigenen Schritte beschränkt: Build- und Testbefehle wie npm install und npm run build, sowie Konfigurationsdateien und Abhängigkeiten, die der Code mit sich bringt, können alle vom Angreifer gesteuerten Code ausführen. Für die Ausführung ist kein offensichtlicher Buildschritt erforderlich. Sie müssen sicherstellen, dass der ausgecheckte Code nur als Daten überprüft und nie vor der Verwendung eines pull_request_target Ereignisses ausgeführt wird.

Härtung eines pull_request_target Workflows

Wenn Sie bestätigt haben, dass Sie dies benötigen pull_request_target, wenden Sie diese Steuerelemente an, um die Auswirkungen dieses risikoreichen Ereignisses einzuschränken. Dies gilt unabhängig davon, ob Ihr Workflow Pull-Request-Code auscheckt.

• Schränken Sie geheime Schlüssel ein. Vergewissern Sie sich, dass für GITHUB_TOKEN nur die geringstmöglichen Berechtigungen festgelegt sind und dass für den Workflow nur die erforderlichen Repository- und Organisationsgeheimnisse verwendet werden. Weitere Informationen findest du unter Verwenden von GITHUB_TOKEN für die Authentifizierung in Workflows.

• Verstehen sie die Auswirkungen auf das Zwischenspeichern. Um das Risiko einer Cache-Vergiftung zu verringern, haben Workflows, die durch pull_request_target ausgelöst werden, im Geltungsbereich des Standard-Branches nur Lesezugriff auf den Cache. Diese Workflows können vorhandene Cacheeinträge wiederherstellen, aber sie können nicht erstellen oder überschreiben, sodass sie sich nicht auf die Ausführung anderer, nicht verknüpfter Workflows über den freigegebenen Cache auswirken können. Wenn ein solcher Workflow versucht, einen Cache zu speichern, schlägt die Speicherung fehl, aber der Schritt und der Auftrag wird fortgesetzt, und der Fehler wird als Warnung im Workflowprotokoll gemeldet. Wenn Ihr Workflow den Cache füllen muss, speichern Sie ihn in einem Workflow, der mit einem vertrauenswürdigen Trigger ausgeführt wird, wie z. B. push. Ein Workflow oder Job kann von dieser schreibgeschützten Einschränkung ausgenommen werden, indem er explizit ein schreibfähiges cache-mode deklariert. Bei einem pull_request_target-Workflow führt dies jedoch das Risiko einer Cache-Vergiftung wieder ein, das durch diese Einschränkung verhindert werden soll. Weitere Informationen findest du unter Referenz zum Zwischenspeichern von Abhängigkeiten.

• Stellen Sie sicher, dass die zugrunde liegende Berechnung isoliert und kurzlebig ist. Wenn selbstgehostete Runner verwendet werden, müssen Sie bestätigen, dass die Runner-Umgebung ordnungsgemäß gegenüber internen Ressourcen abgeschottet ist und nicht über mehrere GitHub Actions Ausführungen hinweg wiederverwendet wird. Weitere Informationen findest du unter Referenz zur sicheren Verwendung.

• Setzen Sie GitHub Actions bewährte Sicherheitsverfahren durch. Neben den spezifischen Risiken von pwn-Anforderungen können andere häufige Sicherheitsrisiken, z. B. die Einfügung von Befehlen, vorhanden sein und sich auf den code auswirken, der in diesem privilegierten Ereignis ausgeführt wird. Weitere Informationen finden Sie unter "Schützen Ihrer GitHub Actions und Workflows: Nicht vertrauenswürdige Eingaben aus der GitHub Security Lab. Aktivieren Sie GitHub Actions für CodeQL, um allgemeine GitHub Actions Schwachstellen zu identifizieren und sich proaktiv davor zu schützen. Weitere Informationen findest du unter Konfigurieren des Standardsetups für das Code-Scanning.

Abmelden von integrierten Schutzfunktionen

Wenn Sie die oben genannten Fragen durchgearbeitet und bestätigt haben, dass Ihr Workflow pull_request_target erfordert und diese sicher verwendet, können Sie die standardmäßige Ereignisrichtlinie und den actions/checkoutSchutz deaktivieren.

Wenn allow-unsafe-pr-checkout: true als actions/checkout festgelegt wird, können Head-Refs von Pull Requests aus Forks ausgecheckt werden. Tun Sie dies nur, nachdem Sie bestätigt haben, dass der ausgecheckte Code niemals ausgeführt wird. Die Eingabe wird absichtlich benannt, um in der Codeüberprüfung und statischen Analyse leicht zu erkennen.

Dieser Schutz gilt nur für Fork-Pull-Request-Referenzen. Das Auschecken anderer nicht vertrauenswürdiger Code, z. B. ein nicht verwandtes Drittanbieterrepository, das Abrufen von Code mit git fetch oder gh pr checkoutoder das Ausführen eines heruntergeladenen Artefakts, wird von den actions/checkout Prüfungen nicht abgedeckt.