openai/codex-action

openai/codex-action

Language: TypeScript

License: Apache-2.0

Stars: 1057

Forks: 130

Open issues: 26

Created: 2025-10-01T20:58:28Z

Pushed: 2026-05-26T04:30:02Z

Default branch: main

Fork: no

Archived: no

README:

Codex GitHub Action

Run Codex from a GitHub Actions workflow while keeping tight control over the privileges available to Codex. This action handles installing the Codex CLI and configuring it with a secure proxy to the Responses API.

Users must provide an API key for their chosen provider (for example, `OPENAI_API_KEY` or AZURE_OPENAI_API_KEY [if using Azure for OpenAI models](#azure)) as a GitHub Actions secret to use this action.

Example: Create Your Own Pull Request Bot

While Codex cloud offers a powerful code review tool that you can use today, here is an example of how you can build your own code review workflow with openai/codex-action if you want to have more control over the experience.

In the following example, we define a workflow that is triggered whenever a user creates a pull request that:

• Creates a shallow clone of the repo.
• Ensures the base and head refs for the PR are available locally.
• Runs Codex with a prompt that includes the details specific to the PR.
• Takes the output from Codex and posts it as a comment on the PR.

See [security.md](./docs/security.md) for tips on using openai/codex-action securely.

name: Perform a code review when a pull request is created.
on:
pull_request:
types: [opened]

jobs:
codex:
runs-on: ubuntu-latest
permissions:
contents: read
outputs:
final_message: ${{ steps.run_codex.outputs.final-message }}
steps:
- uses: actions/checkout@v5
with:
# Explicitly check out the PR's merge commit.
ref: refs/pull/${{ github.event.pull_request.number }}/merge
persist-credentials: false

- name: Pre-fetch base and head refs for the PR
env:
PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
PR_NUMBER: ${{ github.event.pull_request.number }}
run: |
# Pass GitHub expressions through env and quote shell expansions.
git fetch --no-tags origin \
"$PR_BASE_REF" \
"+refs/pull/$PR_NUMBER/head"

# If you want Codex to build and run code, install any dependencies that
# need to be downloaded before the "Run Codex" step because Codex's
# default sandbox disables network access.

- name: Run Codex
id: run_codex
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
prompt: |
This is PR #${{ github.event.pull_request.number }} for ${{ github.repository }}.

Review ONLY the changes introduced by the PR, so consider:
git log --oneline ${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}

Suggest any improvements, potential bugs, or issues.
Be concise and specific in your feedback.

Pull request title and body:
----
${{ github.event.pull_request.title }}
${{ github.event.pull_request.body }}

post_feedback:
runs-on: ubuntu-latest
needs: codex
if: needs.codex.outputs.final_message != ''
permissions:
issues: write
pull-requests: write
steps:
- name: Report Codex feedback
uses: actions/github-script@v7
env:
CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}
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,
});

Inputs

| Name | Description | Default | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | openai-api-key | Secret used to start the Responses API proxy when you are using OpenAI (default). Store it in secrets. | "" | | responses-api-endpoint | Optional Responses API endpoint override, e.g. https://example.openai.azure.com/openai/v1/responses. Leave empty to use the proxy's default. | "" | | prompt | Inline prompt text. Provide this or prompt-file. | "" | | prompt-file | Path (relative to the repository root) of a file that contains the prompt. Provide this or prompt. | "" | | output-file | File where the final Codex message is written. Leave empty to skip writing a file. | "" | | working-directory | Directory passed to codex exec --cd. Defaults to the repository root. | "" | | sandbox | Sandbox mode for Codex. One of workspace-write (default), read-only or danger-full-access. | "" | | codex-version | Version of @openai/codex to install. | "" | | codex-args | Extra arguments forwarded to codex exec. Accepts JSON arrays (["--flag", "value"]) or shell-style strings. | "" | | output-schema | Inline schema contents written to a temp file and passed to codex exec --output-schema. Mutually exclusive with output-schema-file. | "" | | output-schema-file | Schema file forwarded to codex exec --output-schema. Leave empty to skip passing the option. | "" | | model | Model the agent should use. Leave empty to let Codex pick its default. | "" | | effort | Reasoning effort the agent should use. Leave empty to let Codex pick its default. | "" | | codex-home | Directory to use as the Codex CLI home (config/cache). Uses the CLI default when empty. | "" | | safety-strategy | Controls how the action restricts Codex privileges. See [Safety strategy](#safety-strategy). | drop-sudo | | codex-user | Username to run Codex as when safety-strategy is unprivileged-user. | "" | | allow-users | List of GitHub usernames who can trigger the action in addition to those who have write access to the repo. | "" | | allow-bots | Allow runs triggered by trusted GitHub bot accounts (github-actions[bot]) to bypass the write-access check. | false | | allow-bot-users | List of GitHub bot usernames that can bypass the write-access check. * is not supported; list trusted bots explicitly. | "" |

Safety Strategy

The safety-strategy input determines how much access Codex receives on the runner. Choosing the right option is critical, especially when sensitive secrets (like your OpenAI API key) are present.

See [Protecting your…