How to run Codex in GitHub Actions

Codex belongs in GitHub Actions when a pull request review, release check, or repeatable repository task should run from CI instead of a developer laptop. A workflow file gives the run one trigger, one checkout, one prompt source, and one captured response that maintainers can review with the rest of the pull request.

The openai/codex-action@v1 action installs the Codex CLI, starts a Responses API proxy when an API key is provided, and runs codex exec with the inputs defined in the workflow. Keeping the prompt in .github/codex/prompts/ makes the CI task reviewable, while output-file and the final-message output give later workflow steps one handoff value.

Treat pull request text, branch names, commits, and repository instruction files as untrusted input whenever Codex reads them from a CI run. Keep the OpenAI key in a GitHub Actions secret, check out code with read-only permissions for review jobs, avoid unsafe safety mode on shared runners, and move any GitHub write action into a separate job that receives only the final Codex message.

1. Add an OpenAI API key as a repository Actions secret.

   $ gh secret set OPENAI_API_KEY --body "$OPENAI_API_KEY"
   ✓ Set Actions secret OPENAI_API_KEY for owner/example-app

   The command requires an authenticated GitHub CLI session with permission to edit repository secrets. Keep the secret value out of workflow files and logs.

2. Create .github/codex/prompts/review.md for the CI task.

   Review this pull request for correctness risks, missing tests, and security-sensitive changes.
   
   Focus on changes between the pull request branch and the base branch. Report only findings that a maintainer should review before merge. Do not modify files.

   Use a committed prompt file when maintainers should review changes to the CI task itself. Use the action's prompt input only for short inline instructions.

3. Create .github/workflows/codex-pr-review.yml with a pull request workflow that runs Codex with a read-only sandbox.

   name: Codex pull request review
   
   on:
     pull_request:
       types: [opened, synchronize, reopened]
   
   jobs:
     codex:
       runs-on: ubuntu-latest
       permissions:
         contents: read
       outputs:
         final_message: RUN_CODEX_FINAL_MESSAGE_OUTPUT
       steps:
         - uses: actions/checkout@v5
           with:
             persist-credentials: false
   
         - name: Run Codex
           id: run_codex
           uses: openai/codex-action@v1
           with:
             openai-api-key: REPOSITORY_OPENAI_API_KEY_SECRET
             prompt-file: .github/codex/prompts/review.md
             output-file: codex-output.md
             sandbox: read-only
             codex-args: '["--ephemeral"]'
   
     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
           env:
             GH_TOKEN: WORKFLOW_GITHUB_TOKEN
             PR_NUMBER: PULL_REQUEST_NUMBER
             CODEX_FINAL_MESSAGE: CODEX_JOB_FINAL_MESSAGE
           run: |
             gh pr comment "$PR_NUMBER" \
               --body "$CODEX_FINAL_MESSAGE"

   Replace RUN_CODEX_FINAL_MESSAGE_OUTPUT with the steps.run_codex.outputs.final-message expression, REPOSITORY_OPENAI_API_KEY_SECRET with the secrets.OPENAI_API_KEY expression, WORKFLOW_GITHUB_TOKEN with the github.token expression, PULL_REQUEST_NUMBER with the github.event.pull_request.number expression, and CODEX_JOB_FINAL_MESSAGE with the needs.codex.outputs.final_message expression before committing.

   The codex job keeps repository permissions read-only and exposes the action's final-message output. The post_feedback job receives GitHub write permissions only after Codex finishes.

4. Check the workflow file before committing it.

   $ actionlint .github/workflows/codex-pr-review.yml

   No output means actionlint did not find workflow syntax or expression errors. The check does not call OpenAI or GitHub.

5. Stage the prompt and workflow files.

   $ git add .github/codex/prompts/review.md \
     .github/workflows/codex-pr-review.yml

6. Commit the GitHub Actions change.

   $ git commit -m "Run Codex on pull requests"
   [feature/codex-review 6f4a7d2] Run Codex on pull requests
    2 files changed, 52 insertions(+)
    create mode 100644 .github/codex/prompts/review.md
    create mode 100644 .github/workflows/codex-pr-review.yml

7. Push the branch that contains the workflow.

   $ git push -u origin HEAD
   Enumerating objects: 8, done.
   Counting objects: 100% (8/8), done.
   Writing objects: 100% (5/5), 1.64 KiB | 1.64 MiB/s, done.
   branch 'feature/codex-review' set up to track 'origin/feature/codex-review'.

8. Open or update a pull request so the pull_request trigger starts the workflow.

   $ gh pr create --fill
   https://github.com/owner/example-app/pull/42

   If the pull request already exists, pushing another commit to the branch triggers the same workflow through the synchronize event.

9. Check that the newest Codex workflow run completed.

   $ gh run view 9812345670 \
     --json status,conclusion
   {"conclusion":"success","status":"completed"}

10. Inspect the completed run when the status is not success.

    $ gh run view 9812345670 --log-failed
    codex  Run Codex  responses-api-proxy started
    codex  Run Codex  codex exec completed
    post_feedback  Post Codex feedback  RequestError [HttpError]: Resource not accessible by integration

    The codex job can succeed while the feedback job fails if repository permissions or fork restrictions block pull request comments.

11. Confirm that the pull request received the Codex final message.

    $ gh pr view 42 --comments
    author: github-actions[bot]
    --
    Codex reviewed the pull request and found no blocking correctness issues.
    --

    The comment is posted from the final-message output. The configured output-file is written inside the runner job for the same final Codex message.