Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Codex GitHub Action

Codex-Aktionen durch GitHub-Ereignisse auslösen

Mit der Codex GitHub Action (openai/codex-action@v1) kannst du in einem GitHub Actions-Workflow Codex in CI/CD-Jobs ausführen, Patches anwenden oder Reviews veröffentlichen. Die Action installiert die Codex CLI, startet den Proxy für die Responses API, wenn du einen API-Schlüssel angibst, und führt codex exec mit den von dir festgelegten Berechtigungen aus.

Verwende die Action, wenn du Folgendes tun möchtest:

  • Automatisch Feedback von Codex zu Pull Requests oder Releases einholen, ohne die CLI selbst zu verwalten.
  • Änderungen in deiner CI-Pipeline erst freigeben, wenn sie die Qualitätsprüfungen von Codex bestanden haben.
  • Wiederkehrende Aufgaben wie Codeprüfungen, Release-Vorbereitungen oder Migrationen über eine Workflow-Datei mit Codex ausführen.

Ein CI-Beispiel findest du im Abschnitt Nicht interaktiver Modus. Den Quellcode kannst du im Repository openai/codex-action ansehen.

Voraussetzungen

  • Speichere deinen OpenAI-API-Schlüssel als GitHub-Secret (zum Beispiel OPENAI_API_KEY) und verweise im Workflow darauf.
  • Führe den Job auf einem Runner mit Linux oder macOS aus. Unter Windows musst du safety-strategy: unsafe setzen.
  • Checke deinen Code aus, bevor du die Action aufrufst, damit Codex den Inhalt des Repositorys lesen kann.
  • Lege fest, welche Prompts du ausführen möchtest. Mit prompt kannst du den Text direkt angeben. Mit prompt-file kannst du auf eine im Repository eingecheckte Datei verweisen.

Beispiel-Workflow

Der folgende Workflow prüft neue Pull Requests, erfasst die Antwort von Codex und veröffentlicht sie als Kommentar zum jeweiligen Pull Request.

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 }}

Ersetze .github/codex/prompts/review.md durch den Pfad zu deiner eigenen Prompt-Datei oder gib den Text direkt über prompt an. Der Beispiel-Workflow schreibt die letzte Nachricht von Codex außerdem in codex-output.md, damit du sie später prüfen oder als Artefakt hochladen kannst.

codex exec konfigurieren

Mit den folgenden Eingabeparametern der Action legst du die Optionen für codex exec fest:

  • prompt oder prompt-file (wähle eine der beiden Optionen): Gib die Anweisungen für deine Aufgabe direkt als Text an oder verweise auf eine Markdown- oder Textdatei im Repository. Du kannst deine Prompts beispielsweise in .github/codex/prompts/ ablegen.
  • codex-args: Übergib zusätzliche CLI-Flags als JSON-Array (zum Beispiel ["--ephemeral"]) oder als Zeichenfolge für die Shell (--profile ci), um Sitzungen, Profile oder MCP-Einstellungen zu konfigurieren.
  • model und effort: Wähle das Modell und den Reasoning-Aufwand für den Codex-Agenten. Lass die Felder leer, um die Standardwerte zu verwenden.
  • sandbox: Wähle den Sandbox-Modus (workspace-write, read-only, danger-full-access) passend zu den Berechtigungen, die Codex für die Ausführung benötigt.
  • output-file: Speichere die letzte Nachricht von Codex in einer Datei, damit du sie in späteren Schritten hochladen oder mit einer anderen Version vergleichen kannst.
  • codex-version: Lege eine bestimmte CLI-Version fest. Lass das Feld leer, um die neueste veröffentlichte Version zu verwenden.
  • codex-home: Gib ein gemeinsames Codex-Home-Verzeichnis an, wenn du Konfigurationsdateien oder MCP-Setups in mehreren Schritten verwenden möchtest.

Berechtigungen verwalten

Auf von GitHub gehosteten Runnern hat Codex weitreichende Berechtigungen, sofern du sie nicht einschränkst. Mit diesen Eingabeparametern steuerst du den Zugriff:

  • safety-strategy (Standardwert drop-sudo) entfernt sudo, bevor Codex startet. Das lässt sich für diesen Job nicht rückgängig machen und schützt Secrets im Arbeitsspeicher. Unter Windows musst du safety-strategy: unsafe setzen.
  • unprivileged-user: Kombiniere safety-strategy: unprivileged-user mit codex-user, um Codex unter einem bestimmten Konto auszuführen. Stelle sicher, dass das Konto Lese- und Schreibzugriff auf das ausgecheckte Repository hat. Das Beispiel für unprivileged-user zeigt, wie du die Eigentumsrechte anpasst.
  • read-only führt Codex ohne Schreibzugriff auf Dateien und ohne Netzwerkzugriff aus. Codex läuft jedoch weiterhin mit erhöhten Berechtigungen. Verlass dich beim Schutz von Secrets nicht allein auf read-only.
  • sandbox beschränkt den Zugriff auf das Dateisystem und das Netzwerk innerhalb von Codex. Wähle die Option mit den geringsten Berechtigungen, die für die Aufgabe ausreichen.
  • allow-users und allow-bots legen fest, wer den Workflow auslösen darf. Standardmäßig können nur Personen mit Schreibzugriff die Action ausführen. Gib weitere vertrauenswürdige Konten ausdrücklich an oder lass das Feld leer, um das Standardverhalten beizubehalten.

Ausgaben erfassen

Die Action stellt die letzte Nachricht von Codex über die Ausgabe final-message bereit. Weise sie wie oben gezeigt einer Job-Ausgabe zu oder verarbeite sie direkt in späteren Schritten. Wenn du das vollständige Protokoll vom Runner abrufen möchtest, kombiniere output-file mit dem Artefakt-Upload. Wenn du strukturierte Daten benötigst, übergib --output-schema über codex-args, damit die JSON-Ausgabe dem vorgegebenen Schema entspricht.

Sicherheitscheckliste

  • Schränke ein, wer den Workflow starten darf. Nutze vertrauenswürdige Ereignisse oder verlange eine ausdrückliche Genehmigung, statt allen zu erlauben, Codex in deinem Repository auszuführen.
  • Bereinige Prompt-Eingaben aus Pull Requests, Commit-Nachrichten oder Issue-Beschreibungen, um Prompt Injection zu vermeiden. Prüfe HTML-Kommentare und verborgenen Text, bevor du sie an Codex übergibst.
  • Schütze deinen OPENAI_API_KEY, indem du safety-strategy auf drop-sudo belässt oder Codex unter einem Konto ohne erhöhte Berechtigungen ausführst. Lass die Action auf Runnern, die sich mehrere Mandanten teilen, niemals im Modus unsafe laufen.
  • Führe Codex als letzten Schritt eines Jobs aus, damit sich unerwartete Zustandsänderungen nicht auf spätere Schritte auswirken.
  • Tausche die Schlüssel sofort aus, wenn du vermutest, dass die Proxy-Protokolle oder die Ausgabe der Action vertrauliche Daten offengelegt haben.

Fehlerbehebung

  • Du hast sowohl prompt als auch prompt-file angegeben: Entferne eine der beiden Angaben, sodass genau eine Quelle übrig bleibt.
  • responses-api-proxy hat keine Serverinformationen geschrieben: Prüfe, ob der API-Schlüssel vorhanden und gültig ist. Der Proxy startet nur, wenn du openai-api-key angibst.
  • sudo sollte entfernt sein, aber sudo lässt sich weiterhin ausführen: Stelle sicher, dass kein vorheriger Schritt sudo wiederhergestellt hat und dass der Runner Linux oder macOS verwendet. Starte einen neuen Job.
  • Berechtigungsfehler nach drop-sudo: Erteile Schreibzugriff, bevor die Action startet, zum Beispiel mit chmod -R g+rwX "$GITHUB_WORKSPACE" oder wie im Beispiel für unprivileged-user.
  • Unberechtigter Workflow-Start blockiert: Passe allow-users oder allow-bots an, wenn du neben den standardmäßig zugelassenen Personen mit Schreibzugriff auch Dienstkonten den Start erlauben möchtest.