{ "package_version": "skillsreview-install-package@1", "generated_at": "2026-05-12T12:48:39.673Z", "skill": { "id": "skill-77749a0a79b61f6e", "name": "Codex GitHub Action", "slug": "codex-github-action", "source_url": "https://github.com/openai/codex-action", "review_page_url": "https://bot-skills.com/en/skills/codex-github-action", "skill_md_download_url": "https://bot-skills.com/en/skills/codex-github-action/SKILL.md" }, "skillMd": "# Codex GitHub Action\n\nRun [Codex](https://github.com/openai/codex#codex-exec) 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](https://platform.openai.com/docs/api-reference/responses).\n\nUsers must provide an API key for their chosen provider (for example, [`OPENAI_API_KEY`](https://platform.openai.com/api-keys) or `AZURE_OPENAI_API_KEY` [if using Azure for OpenAI models](#azure)) as a [GitHub Actions secret](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) to use this action.\n\n## Example: Create Your Own Pull Request Bot\n\nWhile Codex cloud offers a [powerful code review tool](https://developers.openai.com/codex/cloud/code-review) 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.\n\nIn the following example, we define a workflow that is triggered whenever a user creates a pull request that:\n\n- Creates a shallow clone of the repo.\n- Ensures the `base` and `head` refs for the PR are available locally.\n- Runs Codex with a `prompt` that includes the details specific to the PR.\n- Takes the output from Codex and posts it as a comment on the PR.\n\nSee [`security.md`](./docs/security.md) for tips on using `openai/codex-action` securely.\n\n```yaml\nname: Perform a code review when a pull request is created.\non:\n pull_request:\n types: [opened]\n\njobs:\n codex:\n runs-on: ubuntu-latest\n permissions:\n contents: read\n outputs:\n final_message: ${{ steps.run_codex.outputs.final-message }}\n steps:\n - uses: actions/checkout@v5\n with:\n # Explicitly check out the PR's merge commit.\n ref: refs/pull/${{ github.event.pull_request.number }}/merge\n\n - name: Pre-fetch base and head refs for the PR\n env:\n PR_BASE_REF: ${{ github.event.pull_request.base.ref }}\n PR_NUMBER: ${{ github.event.pull_request.number }}\n run: |\n # Pass GitHub expressions through env and quote shell expansions.\n git fetch --no-tags origin \\\n \"$PR_BASE_REF\" \\\n \"+refs/pull/$PR_NUMBER/head\"\n\n # If you want Codex to build and run code, install any dependencies that\n # need to be downloaded before the \"Run Codex\" step because Codex's\n # default sandbox disables network access.\n\n - name: Run Codex\n id: run_codex\n uses: openai/codex-action@v1\n with:\n openai-api-key: ${{ secrets.OPENAI_API_KEY }}\n prompt: |\n This is PR #${{ github.event.pull_request.number }} for ${{ github.repository }}.\n\n Review ONLY the changes introduced by the PR, so consider:\n git log --oneline ${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}\n\n Suggest any improvements, potential bugs, or issues.\n Be concise and specific in your feedback.\n\n Pull request title and body:\n ----\n ${{ github.event.pull_request.title }}\n ${{ github.event.pull_request.body }}\n\n post_feedback:\n runs-on: ubuntu-latest\n needs: codex\n if: needs.codex.outputs.final_message != ''\n permissions:\n issues: write\n pull-requests: write\n steps:\n - name: Report Codex feedback\n uses: actions/github-script@v7\n env:\n CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}\n with:\n github-token: ${{ github.token }}\n script: |\n await github.rest.issues.createComment({\n owner: context.repo.owner,\n repo: context.repo.repo,\n issue_number: context.payload.pull_request.number,\n body: process.env.CODEX_FINAL_MESSAGE,\n });\n```\n\n## Inputs\n\n| Name | Description | Default |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `openai-api-key` | Secret used to start the Responses API proxy when you are using OpenAI (default). Store it in `secrets`. | `\"\"` |\n| `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. | `\"\"` |\n| `prompt` | Inline prompt text. Provide this or `prompt-file`. | `\"\"` |\n| `prompt-file` | Path (relative to the repository root) of a file that contains the prompt. Provide this or `prompt`. | `\"\"` |\n| `output-file` | File where the final Codex message is written. Leave empty to skip writing a file. | `\"\"` |\n| `working-directory` | Directory passed to `codex exec --cd`. Defaults to the repository root. | `\"\"` |\n| `sandbox` | Sandbox mode for Codex. One of `workspace-write` (default), `read-only` or `danger-full-access`. | `\"\"` |\n| `codex-version` | Version of `@openai/codex` to install. | `\"\"` |\n| `codex-args` | Extra arguments forwarded to `codex exec`. Accepts JSON arrays (`[\"--flag\", \"value\"]`) or shell-style strings. | `\"\"` |\n| `output-schema` | Inline schema contents written to a temp file and passed to `codex exec --output-schema`. Mutually exclusive with `output-schema-file`. | `\"\"` |\n| `output-schema-file` | Schema file forwarded to `codex exec --output-schema`. Leave empty to skip passing the option. | `\"\"` |\n| `model` | Model the agent should use. Leave empty to let Codex pick its default. | `\"\"` |\n| `effort` | Reasoning effort the agent should use. Leave empty to let Codex pick its default. | `\"\"` |\n| `codex-home` | Directory to use as the Codex CLI home (config/cache). Uses the CLI default when empty. | `\"\"` |\n| `safety-strategy` | Controls how the action restricts Codex privileges. See [Safety strategy](#safety-strategy). | `drop-sudo` |\n| `codex-user` | Username to run Codex as when `safety-strategy` is `unprivileged-user`. | `\"\"` |\n| `allow-users` | List of GitHub usernames who can trigger the action in addition to those who have write access to the repo. | `\"\"` |\n| `allow-bots` | Allow runs triggered by trusted GitHub bot accounts (`github-actions[bot]`) to bypass the write-access check. | `false` |\n| `allow-bot-users` | List of GitHub bot usernames that can bypass the write-access check. `*` is not supported; list trusted bots explicitly. | `\"\"` |\n\n## Safety Strategy\n\nThe `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.\n\nSee [Protecting your `OPENAI_API_KEY`](./docs/security.md#protecting-your-openai_api_key) on the Security page for important details on this topic.\n\n- **`drop-sudo` (default)** — On Linux and macOS runners, the action revokes the default user’s `sudo` membership before invoking Codex. Codex then runs as that user without superuser privileges. This change lasts for the rest of the job, so subsequent steps cannot rely on `sudo`. This is usually the safest choice on GitHub-hosted runners.\n- **`unprivileged-user`** — Runs Codex as the user provided via `codex-user`. Use this if you manage your own runner with a pre-created unprivileged account. Ensure the user can read the repository checkout and any files Codex needs. See [`unprivileged-user.yml`](./examples/unprivileged-user.yml) for an example of how to configure such an account on `ubuntu-latest`.\n- **`read-only`** — Executes Codex in a read-only sandbox. Codex can view files but cannot mutate the filesystem or access the network directly. The OpenAI API key still flows through the proxy, so Codex could read it if it can reach process memory.\n- **`unsafe`** — No privilege reduction. Codex runs as the default `runner` user (which typically has `sudo`). Only use this when you fully trust the prompt. On Windows runners this is the only supported choice and the action will fail if another option is provided.\n\n### Operating system support\n\n- **Windows**: GitHub-hosted Windows runners lack a supported sandbox. Set `safety-strategy: unsafe`. The action validates this and exits early otherwise.\n- **Linux/macOS**: All options for `safety-strategy` are supported. Again, if you pick `drop-sudo`, remember that later steps in your `job` that rely on `sudo` will fail. If you do need to run code that requires `sudo` after `openai/codex-action` has run, one option is to pipe the output of `openai/codex-action` to a fresh `job` on a new host and to continue your workflow from there.\n- **GitHub-hosted Linux runners**: The action enables unprivileged user namespaces during setup and clears Ubuntu's AppArmor gate when present. This avoids the `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` failure seen on newer hosted images, including workflows that use the action once to bootstrap Codex and then call `codex` in later steps. Self-hosted Linux runners still need equivalent kernel support configured ahead of time.\n\n## Outputs\n\n| Name | Description |\n| --------------- | --------------------------------------- |\n| `final-message` | Final message returned by `codex exec`. |\n\nAs we saw in the example above, we took the `final-message` output of the `run_codex` step and made it an output of the `codex` job in the workflow:\n\n```yaml\njobs:\n codex:\n # ...\n outputs:\n final_message: ${{ steps.run_codex.outputs.final-message }}\n```\n\n## Additional tips\n\n- Run this action after `actions/checkout@v5` so Codex has access to your repository contents.\n- To use a non-default Responses endpoint (for example Azure OpenAI), set `responses-api-endpoint` to the provider's URL while keeping `openai-api-key` populated; the proxy will still send `Authorization: Bearer ` upstream.\n- If you want Codex to have access to a narrow set of privileged functionality, consider running a local MCP server that can perform these actions and configure Codex to use it.\n- If you need more control over the CLI invocation, pass flags through `codex-args` or create a `config.toml` in `codex-home`.\n- Once `openai/codex-action` is run once with `openai-api-key`, you can also call `codex` from subsequent scripts in your job. (You can omit `prompt` and `prompt-file` from the action in this case.)\n\n## Azure\n\nTo configure the Action to use OpenAI models hosted on Azure, pay close attention to the following:\n\n- The `responses-api-endpoint` must be set to the full URL (including any required query parameters) that Codex will `POST` to for a Responses API request. For Azure, this might look like `https://YOUR_PROJECT_NAME.openai.azure.com/openai/v1/responses`. Note that [unlike when customizing a model provider in Codex](https://github.com/openai/codex/blob/main/docs/config.md#azure-model-provider-example), you must include the `v1/responses` suffix to the URL yourself, if appropriate.\n- The `openai-api-key` input must be a valid key that can be used with the `Authorization: Bearer ` header when making a `POST` request to your Responses API endpoint. (This is also true for the value of the [`env_key`](https://github.com/openai/codex/blob/main/docs/config.md#azure-model-provider-example) when setting a custom provider using the Codex CLI.)\n\nUltimately, your configured Action might look something like the following:\n\n```yaml\n- name: Start Codex proxy\n uses: openai/codex-action@v1\n with:\n openai-api-key: ${{ secrets.AZURE_OPENAI_API_KEY }}\n responses-api-endpoint: \"https://bolinfest-7804-resource.cognitiveservices.azure.com/openai/v1/responses\"\n prompt: \"Debug all the things.\"\n```\n\n## Version History\n\nSee the [`CHANGELOG`](./CHANGELOG.md) for details.\n\n## License\n\nThis project is licensed under the [Apache License 2.0](./LICENSE).", "skillFiles": [ { "kind": "skill_md", "label": "Primary skill instruction", "path": "SKILL.md", "size_bytes": 13337, "source_url": "https://github.com/openai/codex-action", "storage_key": "production/raw/skills/codex-github-action/snapshot-3742fa48fbce7089/SKILL.md" }, { "kind": "readme", "label": "Repository readme", "path": "README.md", "size_bytes": 13337, "source_url": "https://github.com/openai/codex-action" } ], "installTargets": [ { "create_directory_command": "mkdir -p ~/.codex/skills/codex-github-action", "directory": "~/.codex/skills/codex-github-action", "edit_command": "mkdir -p ~/.codex/skills/codex-github-action && ${EDITOR:-vi} ~/.codex/skills/codex-github-action/SKILL.md", "filename": "SKILL.md", "macos_clipboard_install_command": "mkdir -p ~/.codex/skills/codex-github-action && pbpaste > ~/.codex/skills/codex-github-action/SKILL.md", "path": "~/.codex/skills/codex-github-action/SKILL.md", "platform": "Codex", "reload_note": "Restart Codex or reload the skill list after saving.", "verify_command": "test -s ~/.codex/skills/codex-github-action/SKILL.md && echo \"installed: ~/.codex/skills/codex-github-action/SKILL.md\"" } ], "installCommand": null, "sourceContent": { "observed_at": "2026-05-12T12:48:26.537Z", "character_count": 13326, "is_truncated": false } }