action.yml

name: "Codex Exec Action"
description: "Run `codex exec` with a prompt."
author: "OpenAI"
inputs:
  prompt:
    description: "Prompt to pass to Codex. `prompt` or `prompt-file` must be provided."
    required: false
    default: ""
  prompt-file:
    description: "Path to file that contains the prompt to pass to Codex. `prompt` or `prompt-file` must be provided."
    required: false
    default: ""
  output-file:
    description: "File where the final Codex message is written. Leave empty to skip writing a file."
    required: false
    default: ""
  openai-api-key:
    description: "OpenAI API key used by Codex."
    required: false
    default: ""
  responses-api-endpoint:
    description: "Optional Responses API endpoint override, e.g. https://example.openai.azure.com/openai/v1/responses. Defaults to the proxy's built-in endpoint when empty."
    required: false
    default: ""
  codex-auth-json-b64:
    description: "Base64-encoded contents of Codex auth.json (ChatGPT subscription auth)."
    required: false
    default: ""
  working-directory:
    description: "Working directory that Codex should use. Defaults to the repository root."
    required: false
    default: ""
  sandbox:
    description: |
      Sandbox mode for Codex. One of `workspace-write` (default), `read-only` or `danger-full-access`.
    required: false
    default: "workspace-write"
  codex-version:
    description: "Version of `@openai/codex` to install."
    required: false
    default: "0.104.0"
  codex-args:
    description: "Additional args to pass through to `codex exec`. If this value starts with `[`, it will be parsed as a JSON array; otherwise, it will be parsed as a shell-like string."
    required: false
    default: ""
  pass-through-env:
    description: |
      Optional list of environment variable names that should be forwarded to the Codex subprocess.
      Accepts newline-separated or comma-separated values. Use with caution because any forwarded
      variables (including secrets) become accessible to Codex.
    required: false
    default: ""
  output-schema:
    description: "Inline schema contents to use with `codex exec --output-schema`."
    required: false
    default: ""
  output-schema-file:
    description: "File path to the schema that should be passed to `codex exec --output-schema`."
    required: false
    default: ""
  model:
    description: "Model the agent should use. Defaults to `gpt-5.3-codex`; set to an empty string to defer to the Codex CLI/provider default."
    required: false
    default: "gpt-5.3-codex"
  effort:
    description: "Reasoning effort the agent should use."
    required: false
    default: ""
  codex-home:
    description: "Directory to use as the Codex home directory. If empty, the default Codex home directory will be used."
    required: false
    default: ""
  safety-strategy:
    description: |
      Specify one of the following options (on Windows, the only supported option is `unsafe`):

      * `drop-sudo` (default, IRREVERSIBLE) Drop sudo privileges (if any) from
        the default user before running Codex, and run Codex as that user. This
        is only supported on Linux and macOS runners. This option is
        irreversible: if the default user has sudo privileges, they will be
        removed permanently for the duration of the job.
      * `unprivileged-user` Run Codex as the specified user specified by the
        `codex-user` option (the user must already exist). Note the caller is
        responsible for ensuring the specified user has the privileges it needs
        to perform the requested actions. For example, the copy of the repo
        created by `actions/checkout` is not world-readable by default.
      * `read-only` Run Codex in a sandbox that can read any file on disk,
        but cannot write to disk or access the network. Note Codex will still
        run as the default user for this Action, which likely has sudo
        privileges, so it could read `openai-api-key` from memory and reveal it
        by printing it to the output of the GitHub Action.
      * `unsafe` (NOT RECOMMENDED) Do not try to restrict Codex's privileges at all.
        This is extremely dangerous, as the default user for this Action likely
        has sudo privileges, which means it can read secrets stored in memory
        (such as the value of `openai-api-key`) and print them to the output
        of the GitHub Action or exfiltrate them in other ways.
    required: false
    default: "drop-sudo"
  codex-user:
    description: "If `safety-strategy` is set to `unprivileged-user`, this specifies the UNIX username to run Codex as."
    required: false
    default: ""
  allow-users:
    description: "Comma-separated list of GitHub usernames who can run this action, or '*' to allow all users. Note users who have write access to the GitHub repo have access by default and do not need to be listed here."
    required: false
    default: ""
  allow-bots:
    description: "Allow runs triggered by GitHub Apps/bot accounts to bypass the write-access check."
    required: false
    default: "false"
  capture-json-events:
    description: "Capture codex exec JSON event stream (`codex exec --json`) for metadata extraction."
    required: false
    default: "false"
  json-events-file:
    description: "Optional file path where raw codex exec JSONL events should be written."
    required: false
    default: ""
  write-step-summary:
    description: "Write execution metadata and a final message preview to the GitHub step summary."
    required: false
    default: "true"
  trigger-phrase:
    description: "Optional phrase that must appear in issue/PR/comment text for this action to run."
    required: false
    default: ""
  label-trigger:
    description: "Optional issue/PR label name that triggers execution."
    required: false
    default: ""
  assignee-trigger:
    description: "Optional issue/PR assignee username that triggers execution."
    required: false
    default: ""
  track-progress:
    description: "Create/update a progress comment on issue/PR events while Codex runs."
    required: false
    default: "false"
  use-sticky-comment:
    description: "When tracking progress, reuse a single marker-based comment when possible."
    required: false
    default: "false"
  sanitize-github-context:
    description: "Sanitize untrusted GitHub payload text before deriving prompts from trigger events."
    required: false
    default: "true"
outputs:
  final-message:
    description: "Raw output emitted by `codex exec`."
    value: ${{ steps.run_codex.outputs['final-message'] }}
  structured-output:
    description: "Structured JSON output (stringified) when output-schema is used and the final message is valid JSON."
    value: ${{ steps.run_codex.outputs['structured-output'] }}
  usage-json:
    description: "Token usage metadata extracted from codex exec JSON events."
    value: ${{ steps.run_codex.outputs['usage-json'] }}
  execution-file:
    description: "Path to the raw codex exec JSONL event log when capture-json-events is enabled."
    value: ${{ steps.run_codex.outputs['execution-file'] }}
  session-id:
    description: "Session/thread ID extracted from codex exec JSON events (diagnostic only)."
    value: ${{ steps.run_codex.outputs['session-id'] }}
  conclusion:
    description: "Run conclusion from the codex step (`success` or `failure`)."
    value: ${{ steps.run_codex.outputs['conclusion'] }}
  triggered:
    description: "Whether trigger conditions matched and the action proceeded."
    value: ${{ steps.detect_trigger.outputs.triggered }}
  tracking-comment-id:
    description: "Issue/PR comment ID used for progress tracking when enabled."
    value: ${{ steps.progress_start.outputs['comment-id'] }}
runs:
  using: "composite"
  steps:
    - name: Validate Windows safety strategy
      if: ${{ runner.os == 'Windows' }}
      shell: bash
      run: |
        if [ "${{ inputs['safety-strategy'] }}" != "unsafe" ]; then
          echo "On Windows, inputs['safety-strategy'] must be 'unsafe'" >&2
          echo "because no viable sandboxing options are available at this time." >&2
          exit 1
        fi

    - name: Ensure Node.js available
      # Pin to a commit hash because some repositories require it:
      # https://github.com/openai/codex-action/issues/43
      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
      with:
        node-version: "20"

    - name: Detect trigger
      id: detect_trigger
      shell: bash
      run: |
        node "${{ github.action_path }}/dist/main.js" detect-trigger \
          --trigger-phrase "${{ inputs['trigger-phrase'] }}" \
          --label-trigger "${{ inputs['label-trigger'] }}" \
          --assignee-trigger "${{ inputs['assignee-trigger'] }}" \
          --sanitize-github-context "${{ inputs['sanitize-github-context'] }}"

    - name: Check repository write access
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' }}
      env:
        GITHUB_TOKEN: ${{ github.token }}
      shell: bash
      run: |
        node "${{ github.action_path }}/dist/main.js" check-write-access \
          --allow-bots "${{ inputs['allow-bots'] }}" \
          --allow-users "${{ inputs['allow-users'] }}"

    - name: Install Codex CLI
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' }}
      shell: bash
      run: |
        version="${{ inputs['codex-version'] }}"
        if [ -n "$version" ]; then
          npm install -g "@openai/codex@$version"
        else
          npm install -g "@openai/codex"
        fi

    - name: Install Codex Responses API proxy
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' }}
      shell: bash
      run: |
        version="${{ inputs['codex-version'] }}"
        if [ -n "$version" ]; then
          npm install -g "@openai/codex-responses-api-proxy@$version"
        else
          npm install -g "@openai/codex-responses-api-proxy"
        fi

    - name: Resolve Codex home
      id: resolve_home
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' }}
      shell: bash
      run: |
        node "${{ github.action_path }}/dist/main.js" resolve-codex-home \
          --codex-home-override "${{ inputs['codex-home'] }}" \
          --safety-strategy "${{ inputs['safety-strategy'] }}" \
          --codex-user "${{ inputs['codex-user'] }}" \
          --github-run-id "${{ github.run_id }}"

    - name: Determine server info path
      id: derive_server_info
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' }}
      shell: bash
      run: |
        server_info_file="${{ steps.resolve_home.outputs.codex-home }}/${{ github.run_id }}.json"
        echo "server_info_file=$server_info_file" >> "$GITHUB_OUTPUT"

    - name: Check server info file presence
      id: check_server_info
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' }}
      shell: bash
      run: |
        server_info_file="${{ steps.derive_server_info.outputs.server_info_file }}"
        if [ -s "$server_info_file" ]; then
          echo "exists=true" >> "$GITHUB_OUTPUT"
        else
          echo "exists=false" >> "$GITHUB_OUTPUT"
        fi

    - name: Probe existing Responses API proxy
      id: probe_proxy
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' && inputs['openai-api-key'] != '' }}
      shell: bash
      run: |
        server_info_file="${{ steps.derive_server_info.outputs.server_info_file }}"
        node "${{ github.action_path }}/dist/main.js" probe-proxy "$server_info_file"

    - name: Write Codex auth.json (subscription auth)
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' && inputs['codex-auth-json-b64'] != '' }}
      env:
        CODEX_AUTH_JSON_B64: ${{ inputs['codex-auth-json-b64'] }}
      shell: bash
      run: |
        node "${{ github.action_path }}/dist/main.js" write-auth-json \
          --codex-home "${{ steps.resolve_home.outputs.codex-home }}" \
          --safety-strategy "${{ inputs['safety-strategy'] }}" \
          --codex-user "${{ inputs['codex-user'] }}"

    # This is its own step to minimize the runtime logic that has access to the
    # API key. Note we use `env -u PROXY_API_KEY` to ensure extra copies of the
    # key do not end up in the memory of the `codex-responses-api-proxy`
    # process where environment variables are stored.
    - name: Start Responses API proxy
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' && inputs['openai-api-key'] != '' && steps.probe_proxy.outputs.healthy != 'true' }}
      env:
        PROXY_API_KEY: ${{ inputs['openai-api-key'] }}
      shell: bash
      run: |
        upstream_url="${{ inputs['responses-api-endpoint'] }}"
        server_info_file="${{ steps.derive_server_info.outputs.server_info_file }}"

        rm -f "$server_info_file"

        args=(
          codex-responses-api-proxy
          --http-shutdown
          --server-info "$server_info_file"
        )

        if [ -n "$upstream_url" ]; then
          args+=(--upstream-url "$upstream_url")
        fi

        (
          printenv PROXY_API_KEY | env -u PROXY_API_KEY "${args[@]}"
        ) &

    - name: Wait for Responses API proxy
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' && inputs['openai-api-key'] != '' && steps.probe_proxy.outputs.healthy != 'true' }}
      shell: bash
      run: |
        server_info_file="${{ steps.derive_server_info.outputs.server_info_file }}"
        for _ in {1..15}; do
          if [ -s "$server_info_file" ] && \
            node "${{ github.action_path }}/dist/main.js" probe-proxy "$server_info_file" --fail-unhealthy >/dev/null 2>&1; then
            break
          fi
          sleep 1
        done

        if ! node "${{ github.action_path }}/dist/main.js" probe-proxy "$server_info_file" --fail-unhealthy; then
          echo "responses-api-proxy failed health check" >&2
          exit 1
        fi

        if [ "${RUNNER_OS}" != "Windows" ]; then
          sudo chmod 444 "$server_info_file"
          sudo chown root "$server_info_file"
        fi

    # This step has an output named `port`.
    - name: Read server info
      id: read_server_info
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' && (inputs['openai-api-key'] != '' || steps.check_server_info.outputs.exists == 'true') }}
      shell: bash
      run: node "${{ github.action_path }}/dist/main.js" read-server-info "${{ steps.derive_server_info.outputs.server_info_file }}"

    - name: Write Codex proxy config
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' && inputs['openai-api-key'] != '' }}
      shell: bash
      run: |
        node "${{ github.action_path }}/dist/main.js" write-proxy-config \
          --codex-home "${{ steps.resolve_home.outputs.codex-home }}" \
          --port "${{ steps.read_server_info.outputs.port }}" \
          --safety-strategy "${{ inputs['safety-strategy'] }}"

    - name: Drop sudo privilege, if appropriate
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' && inputs['safety-strategy'] == 'drop-sudo' && (inputs['openai-api-key'] != '' || inputs['codex-auth-json-b64'] != '') }}
      shell: bash
      run: |
        case "${RUNNER_OS}" in
          Linux)
            node "${{ github.action_path }}/dist/main.js" drop-sudo --user runner --group sudo
            ;;
          macOS)
            node "${{ github.action_path }}/dist/main.js" drop-sudo --user runner --group admin
            ;;
          *)
            echo "Unsupported OS for drop-sudo: ${RUNNER_OS}" >&2
            exit 1
            ;;
        esac

    - name: Verify sudo privilege removed
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' && inputs['safety-strategy'] == 'drop-sudo' && (inputs['openai-api-key'] != '' || inputs['codex-auth-json-b64'] != '') }}
      shell: bash
      run: |
        if sudo -n true 2>/dev/null; then
          echo "Expected sudo to be disabled, but sudo succeeded." >&2
          exit 1
        fi
        echo "Confirmed sudo privilege is disabled."

    - name: Start progress comment
      id: progress_start
      if: ${{ inputs['track-progress'] == 'true' && steps.detect_trigger.outputs.triggered == 'true' && (inputs.prompt != '' || inputs['prompt-file'] != '' || steps.detect_trigger.outputs['derived-prompt-file'] != '') }}
      env:
        GITHUB_TOKEN: ${{ github.token }}
      shell: bash
      run: |
        node "${{ github.action_path }}/dist/main.js" update-progress-comment \
          --mode "start" \
          --use-sticky-comment "${{ inputs['use-sticky-comment'] }}" \
          --comment-id "" \
          --conclusion ""

    - name: Run codex exec
      id: run_codex
      if: ${{ steps.detect_trigger.outputs.triggered == 'true' && (inputs.prompt != '' || inputs['prompt-file'] != '' || steps.detect_trigger.outputs['derived-prompt-file'] != '') }}
      env:
        CODEX_PROMPT: ${{ inputs.prompt }}
        CODEX_PROMPT_FILE: ${{ inputs['prompt-file'] }}
        CODEX_DERIVED_PROMPT_FILE: ${{ steps.detect_trigger.outputs['derived-prompt-file'] }}
        CODEX_OUTPUT_FILE: ${{ inputs['output-file'] }}
        CODEX_HOME: ${{ steps.resolve_home.outputs.codex-home }}
        CODEX_WORKING_DIRECTORY: ${{ inputs['working-directory'] || github.workspace }}
        CODEX_SANDBOX: ${{ inputs.sandbox }}
        CODEX_ARGS: ${{ inputs['codex-args'] }}
        CODEX_OUTPUT_SCHEMA: ${{ inputs['output-schema'] }}
        CODEX_OUTPUT_SCHEMA_FILE: ${{ inputs['output-schema-file'] }}
        CODEX_MODEL: ${{ inputs.model }}
        CODEX_EFFORT: ${{ inputs.effort }}
        CODEX_SAFETY_STRATEGY: ${{ inputs['safety-strategy'] }}
        CODEX_USER: ${{ inputs['codex-user'] }}
        CODEX_PASS_THROUGH_ENV: ${{ inputs['pass-through-env'] }}
        CODEX_CAPTURE_JSON_EVENTS: ${{ inputs['capture-json-events'] }}
        CODEX_JSON_EVENTS_FILE: ${{ inputs['json-events-file'] }}
        CODEX_WRITE_STEP_SUMMARY: ${{ inputs['write-step-summary'] }}
        FORCE_COLOR: 1
      shell: bash
      run: |
        resolved_prompt_file="$CODEX_PROMPT_FILE"
        if [ -z "$CODEX_PROMPT" ] && [ -z "$resolved_prompt_file" ] && [ -n "$CODEX_DERIVED_PROMPT_FILE" ]; then
          resolved_prompt_file="$CODEX_DERIVED_PROMPT_FILE"
        fi

        node "${{ github.action_path }}/dist/main.js" run-codex-exec \
            --prompt "${CODEX_PROMPT}" \
            --prompt-file "${resolved_prompt_file}" \
            --output-file "$CODEX_OUTPUT_FILE" \
            --codex-home "$CODEX_HOME" \
            --cd "$CODEX_WORKING_DIRECTORY" \
            --extra-args "$CODEX_ARGS" \
            --output-schema "$CODEX_OUTPUT_SCHEMA" \
            --output-schema-file "$CODEX_OUTPUT_SCHEMA_FILE" \
            --sandbox "$CODEX_SANDBOX" \
            --model "$CODEX_MODEL" \
            --effort "$CODEX_EFFORT" \
            --safety-strategy "$CODEX_SAFETY_STRATEGY" \
            --codex-user "$CODEX_USER" \
            --pass-through-env "$CODEX_PASS_THROUGH_ENV" \
            --capture-json-events "$CODEX_CAPTURE_JSON_EVENTS" \
            --json-events-file "$CODEX_JSON_EVENTS_FILE" \
            --write-step-summary "$CODEX_WRITE_STEP_SUMMARY"

    - name: Finalize progress comment
      if: ${{ always() && inputs['track-progress'] == 'true' && steps.detect_trigger.outputs.triggered == 'true' && steps.progress_start.outputs['comment-id'] != '' && (inputs.prompt != '' || inputs['prompt-file'] != '' || steps.detect_trigger.outputs['derived-prompt-file'] != '') }}
      env:
        GITHUB_TOKEN: ${{ github.token }}
        CODEX_FINAL_MESSAGE: ${{ steps.run_codex.outputs['final-message'] }}
      shell: bash
      run: |
        node "${{ github.action_path }}/dist/main.js" update-progress-comment \
          --mode "finish" \
          --use-sticky-comment "${{ inputs['use-sticky-comment'] }}" \
          --comment-id "${{ steps.progress_start.outputs['comment-id'] }}" \
          --conclusion "${{ steps.run_codex.outcome }}"