Codex GitHub Action

Codex GitHub Action(openai/codex-action@v1)을 사용하면 GitHub Actions 워크플로우에서 CI/CD 작업의 일부로 Codex를 실행하거나, 패치를 적용하거나, 리뷰를 게시할 수 있습니다. 이 액션은 Codex CLI를 설치하고, API 키를 제공하면 Responses API 프록시를 시작한 다음, 지정한 권한으로 codex exec를 실행합니다.

다음과 같은 경우에 이 액션을 사용하세요.

• CLI를 직접 관리하지 않고도 pull requests나 릴리스에 대한 Codex 피드백을 자동화하려는 경우
• CI 파이프라인에서 Codex 품질 검사를 통과한 변경 사항만 반영하려는 경우
• 워크플로우 파일에서 코드 리뷰, 릴리스 준비, 마이그레이션 등의 Codex 작업을 반복해서 실행하려는 경우

CI 예시는 비대화형 모드에서, 소스 코드는 openai/codex-action 리포지터리에서 확인하세요.

사전 준비

• OpenAI 키를 GitHub 시크릿(예: OPENAI_API_KEY)으로 저장하고 워크플로우에서 참조하세요.
• Linux 또는 macOS 러너에서 작업을 실행하세요. Windows에서는 safety-strategy: unsafe로 설정하세요.
• Codex가 리포지터리 내용을 읽을 수 있도록 액션을 호출하기 전에 코드를 체크아웃하세요.
• 실행할 프롬프트를 정하세요. prompt에 텍스트를 직접 입력하거나 prompt-file로 리포지터리에 커밋된 파일을 지정할 수 있습니다.

워크플로우 예시

아래 워크플로우는 새 pull requests를 리뷰하고 Codex의 응답을 받아 해당 PR에 댓글로 게시합니다.

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

.github/codex/prompts/review.md를 사용할 프롬프트 파일의 경로로 바꾸거나 prompt에 텍스트를 직접 입력하세요. 이 예시는 Codex의 최종 메시지를 codex-output.md에도 저장하므로 나중에 내용을 확인하거나 아티팩트로 업로드할 수 있습니다.

codex exec 설정

codex exec 옵션에 대응하는 액션 입력값을 설정해 Codex의 실행 방식을 조정하세요.

• prompt 또는 prompt-file(둘 중 하나 선택): 작업 지침을 직접 입력하거나 지침이 담긴 Markdown 또는 텍스트 파일의 리포지터리 내 경로를 지정하세요. 프롬프트는 .github/codex/prompts/에 모아 두면 편리합니다.
• codex-args: 추가 CLI 플래그를 지정합니다. JSON 배열(예: ["--ephemeral"]) 또는 셸 문자열(--profile ci)로 세션, 프로필 또는 MCP 설정을 구성하세요.
• model과 effort: 원하는 Codex 에이전트 구성을 선택하세요. 비워 두면 기본값을 사용합니다.
• sandbox: Codex 실행에 필요한 권한에 맞춰 샌드박스 모드(workspace-write, read-only, danger-full-access)를 선택하세요.
• output-file: Codex의 최종 메시지를 디스크에 저장해 후속 단계에서 업로드하거나 차이를 비교할 수 있습니다.
• codex-version: CLI 버전을 특정 릴리스로 고정하세요. 비워 두면 배포된 최신 버전을 사용합니다.
• codex-home: 여러 단계에서 설정 파일이나 MCP 구성을 재사용하려면 공유 Codex 홈 디렉터리를 지정하세요.

권한 관리

GitHub 호스팅 러너에서는 별도로 제한하지 않는 한 Codex에 광범위한 접근 권한이 부여됩니다. 다음 입력값으로 접근 범위를 제한하세요.

• safety-strategy의 기본값인 drop-sudo는 Codex를 실행하기 전에 sudo를 제거합니다. 이렇게 하면 메모리에 있는 시크릿을 보호할 수 있으며, 해당 작업이 끝날 때까지 이 조치를 되돌릴 수 없습니다. Windows에서는 반드시 safety-strategy: unsafe로 설정하세요.
• unprivileged-user 방식에서는 safety-strategy: unprivileged-user와 codex-user를 함께 지정해 특정 계정으로 Codex를 실행합니다. 해당 계정에 체크아웃한 리포지터리의 읽기 및 쓰기 권한이 있는지 확인하세요. 파일 소유권을 조정하는 방법은 unprivileged-user 예시를 참고하세요.
• read-only는 Codex의 파일 변경과 네트워크 사용을 차단하지만 Codex 자체는 여전히 높은 권한으로 실행됩니다. 시크릿 보호를 read-only에만 의존하지 마세요.
• sandbox는 Codex 내부에서 파일 시스템과 네트워크 접근을 제한합니다. 작업을 완료하는 데 필요한 최소 권한만 허용하는 옵션을 선택하세요.
• allow-users와 allow-bots는 워크플로우를 시작할 수 있는 계정을 제한합니다. 기본적으로 쓰기 권한이 있는 사용자만 액션을 실행할 수 있습니다. 추가로 허용할 계정이 있으면 신뢰할 수 있는 계정만 명시하세요. 기본 설정을 사용하려면 입력란을 비워 두세요.

출력 수집

액션은 final-message 출력값으로 Codex의 마지막 메시지를 반환합니다. 위 예시처럼 작업 출력값에 연결하거나 후속 단계에서 직접 처리하세요. 러너에서 전체 실행 기록을 수집하려면 output-file과 아티팩트 업로드 기능을 함께 사용하세요. 구조화된 데이터가 필요하면 --output-schema를 codex-args로 전달해 출력이 지정한 JSON 구조를 따르도록 하세요.

보안 체크리스트

• 워크플로우를 시작할 수 있는 사용자를 제한하세요. 누구나 리포지터리에서 Codex를 실행하도록 허용하기보다 신뢰할 수 있는 이벤트로 실행을 제한하거나 명시적인 승인을 요구하세요.
• 프롬프트 인젝션을 방지하려면 pull requests, 커밋 메시지 또는 이슈 본문에서 가져온 프롬프트 입력을 정제하세요. Codex에 전달하기 전에 HTML 주석이나 숨겨진 텍스트도 검토하세요.
• OPENAI_API_KEY를 보호하려면 safety-strategy를 drop-sudo로 유지하거나 관리자 권한이 없는 사용자 계정으로 Codex를 실행하세요. 여러 테넌트가 공유하는 러너에서는 절대로 액션을 unsafe 모드로 두지 마세요.
• 예기치 않은 상태 변경이 후속 단계에 영향을 주지 않도록 Codex를 작업의 마지막 단계에서 실행하세요.
• 프록시 로그나 액션 출력에 시크릿이 노출된 것으로 의심되면 즉시 키를 교체하세요.

문제 해결

• prompt와 prompt-file을 모두 지정한 경우: 프롬프트를 한 곳에서만 가져오도록 두 입력값 중 하나를 제거하세요.
• responses-api-proxy가 서버 정보를 기록하지 않은 경우: API 키가 입력되어 있고 유효한지 확인하세요. 프록시는 openai-api-key를 제공한 경우에만 시작됩니다.
• sudo가 제거되어야 하는데 sudo 실행에 성공한 경우: 이전 단계에서 sudo를 복원한 적이 없는지, 러너의 운영 체제가 Linux 또는 macOS인지 확인하세요. 새 작업에서 다시 실행하세요.
• drop-sudo 적용 후 권한 오류가 발생한 경우: 액션을 실행하기 전에 쓰기 권한을 부여하세요. 예를 들어 chmod -R g+rwX "$GITHUB_WORKSPACE"를 실행하거나 unprivileged-user 방식을 사용하세요.
• 권한이 없는 계정의 워크플로우 실행 요청이 차단된 경우: 쓰기 권한이 있는 협업자 외에 서비스 계정에도 실행을 허용하려면 allow-users 또는 allow-bots 입력값을 조정하세요.