Codex GitHub Action

Verwenden Sie die Codex GitHub Action (openai/codex-action@v1), um Codex in CI/CD-Jobs auszuführen, Patches anzuwenden oder Reviews aus einem GitHub Actions-Workflow zu veröffentlichen. Die Action installiert die Codex CLI, startet den Responses API-Proxy, wenn Sie einen API key angeben, und führt codex exec mit den von Ihnen festgelegten Berechtigungen aus.

Verwenden Sie die Action, wenn Sie Folgendes möchten:

• Codex-Feedback zu Pull Requests oder Releases automatisieren, ohne die CLI selbst verwalten zu müssen.
• Änderungen im Rahmen Ihrer CI-Pipeline von Codex-gestützten Qualitätsprüfungen abhängig machen.
• Wiederholbare Codex-Aufgaben (Code-Review, Release-Vorbereitung, Migrationen) über eine Workflow-Datei ausführen.

Ein CI-Beispiel finden Sie unter Nicht interaktiver Modus. Den Quellcode können Sie im Repository openai/codex-action ansehen.

Voraussetzungen

• Speichern Sie Ihren OpenAI-Schlüssel als GitHub-Secret (zum Beispiel OPENAI_API_KEY) und referenzieren Sie ihn im Workflow.
• Führen Sie den Job auf einem Linux- oder macOS-Runner aus. Legen Sie unter Windows safety-strategy: unsafe fest.
• Checken Sie Ihren Code aus, bevor Sie die Action aufrufen, damit Codex den Inhalt des Repositorys lesen kann.
• Entscheiden Sie, welche Prompts Sie ausführen möchten. Sie können Inline-Text über prompt bereitstellen oder mit prompt-file auf eine im Repository eingecheckte Datei verweisen.

Beispiel-Workflow

Der folgende Beispiel-Workflow prüft neue Pull Requests, erfasst die Antwort von Codex und veröffentlicht sie im PR.

name: Codex pull request review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
          fetch-depth: 0
          persist-credentials: false

      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          output-file: codex-output.md

  post_feedback:
    runs-on: ubuntu-latest
    needs: codex
    if: needs.codex.outputs.final_message != ''
    permissions:
      issues: write
      pull-requests: write
    steps:
      - name: Post Codex feedback
        uses: actions/github-script@v7
        with:
          github-token: ${{ github.token }}
          script: |
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.payload.pull_request.number,
              body: process.env.CODEX_FINAL_MESSAGE,
            });
        env:
          CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}

Ersetzen Sie .github/codex/prompts/review.md durch Ihre eigene Prompt-Datei oder verwenden Sie die Eingabe prompt für Inline-Text. Das Beispiel schreibt außerdem die abschließende Codex-Nachricht zur späteren Prüfung oder zum Hochladen als Artefakt in codex-output.md.

codex exec konfigurieren

Stimmen Sie die Ausführung von Codex präzise ab, indem Sie die Action-Eingaben festlegen, die den Optionen von codex exec entsprechen:

• prompt oder prompt-file (wählen Sie eine Option): Inline-Anweisungen oder ein Repository-Pfad zu einer Markdown- oder Textdatei mit Ihrer Aufgabe. Erwägen Sie, Prompts in .github/codex/prompts/ zu speichern.
• codex-args: Zusätzliche CLI-Flags. Geben Sie ein JSON-Array (zum Beispiel ["--ephemeral"]) oder eine Shell-Zeichenfolge (--profile ci) an, um Sitzungen, Profile oder MCP-Einstellungen zu konfigurieren.
• model und effort: Wählen Sie die gewünschte Codex-Agentenkonfiguration aus; lassen Sie die Felder leer, um die Standardwerte zu verwenden.
• sandbox: Stimmen Sie den Sandbox-Modus (workspace-write, read-only, danger-full-access) auf die Berechtigungen ab, die Codex während der Ausführung benötigt.
• output-file: Speichern Sie die abschließende Codex-Nachricht auf dem Datenträger, damit nachfolgende Schritte sie hochladen oder mit einer anderen Version vergleichen können.
• codex-version: Legen Sie eine bestimmte CLI-Version fest. Lassen Sie das Feld leer, um die neueste veröffentlichte Version zu verwenden.
• codex-home: Verweisen Sie auf ein gemeinsam genutztes Codex-Home-Verzeichnis, wenn Sie Konfigurationsdateien oder MCP-Einrichtungen schrittübergreifend wiederverwenden möchten.

Berechtigungen verwalten

Codex verfügt auf von GitHub gehosteten Runnern über weitreichenden Zugriff, sofern Sie ihn nicht einschränken. Verwenden Sie diese Eingaben, um den Zugriff zu kontrollieren:

• safety-strategy (Standardwert: drop-sudo) entfernt sudo, bevor Codex ausgeführt wird. Dies kann für den Job nicht rückgängig gemacht werden und schützt Geheimnisse im Arbeitsspeicher. Unter Windows müssen Sie safety-strategy: unsafe festlegen.
• unprivileged-user kombiniert safety-strategy: unprivileged-user mit codex-user, um Codex unter einem bestimmten Konto auszuführen. Stellen Sie sicher, dass der Benutzer den Repository-Checkout lesen und schreiben kann (eine Korrektur der Eigentumsrechte finden Sie im Beispiel für unprivileged-user).
• read-only verhindert, dass Codex Dateien ändert oder das Netzwerk verwendet; Codex wird dabei jedoch weiterhin mit erhöhten Berechtigungen ausgeführt. Verlassen Sie sich zum Schutz von Geheimnissen nicht allein auf read-only.
• sandbox beschränkt den Datei- und Netzwerkzugriff innerhalb von Codex selbst. Wählen Sie die restriktivste Option, mit der die Aufgabe noch abgeschlossen werden kann.
• allow-users und allow-bots schränken ein, wer den Workflow auslösen kann. Standardmäßig können nur Benutzer mit Schreibzugriff die Action ausführen. Führen Sie zusätzliche vertrauenswürdige Konten ausdrücklich auf oder lassen Sie das Feld leer, um das Standardverhalten zu verwenden.

Ausgaben erfassen

Die Action gibt die letzte Codex-Nachricht über die Ausgabe final-message aus. Ordnen Sie sie einer Job-Ausgabe zu (wie oben gezeigt) oder verarbeiten Sie sie direkt in späteren Schritten. Kombinieren Sie output-file mit der Funktion zum Hochladen von Artefakten, wenn Sie lieber das vollständige Transkript vom Runner erfassen möchten. Wenn Sie strukturierte Daten benötigen, übergeben Sie --output-schema über codex-args, um eine JSON-Struktur vorzugeben.

Sicherheitscheckliste

• Beschränken Sie, wer den Workflow starten kann. Bevorzugen Sie vertrauenswürdige Ereignisse oder ausdrückliche Genehmigungen, statt allen die Ausführung von Codex für Ihr Repository zu erlauben.
• Bereinigen Sie Prompt-Eingaben aus Pull Requests, Commit-Nachrichten oder Issue-Beschreibungen, um Prompt-Injection zu verhindern. Prüfen Sie HTML-Kommentare oder verborgenen Text, bevor Sie die Inhalte an Codex übergeben.
• Schützen Sie Ihr OPENAI_API_KEY, indem Sie safety-strategy auf drop-sudo belassen oder Codex unter einem Benutzer ohne besondere Berechtigungen ausführen. Belassen Sie die Action auf mandantenfähigen Runnern niemals im Modus unsafe.
• Führen Sie Codex als letzten Schritt eines Jobs aus, damit spätere Schritte keine unerwarteten Zustandsänderungen übernehmen.
• Rotieren Sie Schlüssel unverzüglich, wenn Sie vermuten, dass Proxy-Protokolle oder die Action-Ausgabe geheime Daten offengelegt haben.

Fehlerbehebung

• Sie haben sowohl prompt als auch prompt-file festgelegt: Entfernen Sie die doppelte Eingabe, sodass Sie genau eine Quelle angeben.
• responses-api-proxy hat keine Serverinformationen geschrieben: Vergewissern Sie sich, dass der API key vorhanden und gültig ist; der Proxy startet nur, wenn Sie openai-api-key angeben.
• Entfernung von sudo erwartet, aber sudo war erfolgreich: Stellen Sie sicher, dass kein früherer Schritt sudo wiederhergestellt hat und dass als Runner-Betriebssystem Linux oder macOS verwendet wird. Führen Sie den Workflow mit einem neuen Job erneut aus.
• Berechtigungsfehler nach drop-sudo: Gewähren Sie Schreibzugriff, bevor die Action ausgeführt wird (zum Beispiel mit chmod -R g+rwX "$GITHUB_WORKSPACE" oder mithilfe des Musters für Benutzer ohne besondere Berechtigungen).
• Nicht autorisierter Auslöser blockiert: Passen Sie die Eingaben allow-users oder allow-bots an, wenn Sie neben den standardmäßig zugelassenen Mitwirkenden mit Schreibzugriff auch Dienstkonten zulassen müssen.