logo

Codex GitHub Action

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

다음이 필요할 때 이 액션을 사용합니다.

  • CLI를 직접 관리하지 않고 pull request나 릴리스에 대한 Codex 피드백을 자동화합니다.
  • CI 파이프라인의 일부로 Codex 기반 품질 검사를 통과 조건에 포함합니다.
  • 코드 리뷰, 릴리스 준비, 마이그레이션 같은 반복 가능한 Codex 작업을 워크플로 파일에서 실행합니다.

CI 예시는 비대화형 모드를 참고하고, 소스는 openai/codex-action 저장소에서 확인할 수 있습니다.

사전 요구 사항

  • OpenAI 키를 GitHub secret으로 저장하고, 예를 들어 OPENAI_API_KEY, 워크플로에서 참조합니다.
  • 작업은 Linux 또는 macOS runner에서 실행합니다. Windows에서는 safety-strategy: unsafe를 설정합니다.
  • Codex가 저장소 내용을 읽을 수 있도록 액션을 호출하기 전에 코드를 checkout합니다.
  • 실행할 프롬프트를 정합니다. prompt로 인라인 텍스트를 제공하거나, prompt-file로 저장소에 커밋된 파일을 지정할 수 있습니다.

예시 워크플로

아래 예시 워크플로는 새 pull request를 리뷰하고, Codex의 응답을 캡처한 뒤, PR에 다시 게시합니다.

name: Codex pull request review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge

      - name: Pre-fetch base and head refs
        run: |
          git fetch --no-tags origin \
            ${{ github.event.pull_request.base.ref }} \
            +refs/pull/${{ github.event.pull_request.number }}/head

      - 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
          safety-strategy: drop-sudo
          sandbox: workspace-write

  post_feedback:
    runs-on: ubuntu-latest
    needs: codex
    if: needs.codex.outputs.final_message != ''
    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 플래그입니다. 편집, 스트리밍, MCP 구성을 허용하려면 JSON 배열, 예: ["--json"], 또는 셸 문자열, 예: --sandbox workspace-write --json, 을 제공합니다.
  • model과 effort: 원하는 Codex 에이전트 구성을 선택합니다. 비워 두면 기본값을 사용합니다.
  • sandbox: 실행 중 Codex에 필요한 권한에 맞춰 샌드박스 모드(workspace-write, read-only, danger-full-access)를 선택합니다.
  • output-file: 이후 단계에서 업로드하거나 diff할 수 있도록 최종 Codex 메시지를 디스크에 저장합니다.
  • codex-version: 특정 CLI 릴리스를 고정합니다. 비워 두면 게시된 최신 버전을 사용합니다.
  • codex-home: 여러 단계에서 구성 파일이나 MCP 설정을 재사용하려면 공유 Codex 홈 디렉터리를 지정합니다.

권한 관리

제한하지 않으면 Codex는 GitHub 호스팅 runner에서 넓은 접근 권한을 가집니다. 다음 입력으로 노출 범위를 제어합니다.

  • safety-strategy: 기본값은 drop-sudo이며, Codex를 실행하기 전에 sudo를 제거합니다. 이 동작은 해당 작업에서 되돌릴 수 없고 메모리의 비밀 정보를 보호합니다. Windows에서는 safety-strategy: unsafe를 설정해야 합니다.
  • unprivileged-user: safety-strategy: unprivileged-user와 codex-user를 함께 사용해 특정 계정으로 Codex를 실행합니다. 해당 사용자가 저장소 checkout을 읽고 쓸 수 있어야 합니다. 소유권 수정 예시는 .cache/codex-action/examples/unprivileged-user.yml을 참고하십시오.
  • read-only: Codex가 파일을 변경하거나 네트워크를 사용하지 못하게 하지만, 여전히 높은 권한으로 실행됩니다. 비밀 정보 보호를 read-only에만 의존하지 마십시오.
  • sandbox: Codex 내부의 파일 시스템과 네트워크 접근을 제한합니다. 작업을 완료할 수 있는 가장 좁은 옵션을 선택합니다.
  • allow-users와 allow-bots: 워크플로를 트리거할 수 있는 주체를 제한합니다. 기본적으로 쓰기 권한이 있는 사용자만 액션을 실행할 수 있습니다. 추가 신뢰 계정은 명시적으로 나열하거나, 기본 동작을 원하면 비워 둡니다.

출력 캡처

액션은 마지막 Codex 메시지를 final-message 출력으로 내보냅니다. 위 예시처럼 작업 출력에 매핑하거나 이후 단계에서 직접 처리합니다. runner의 전체 transcript를 수집하려면 output-file과 아티팩트 업로드 기능을 함께 사용합니다. 구조화된 데이터가 필요하면 codex-args를 통해 --output-schema를 전달해 JSON 형태를 강제합니다.

보안 체크리스트

  • 워크플로를 시작할 수 있는 사람을 제한합니다. 누구나 저장소에서 Codex를 실행하게 하는 대신, 신뢰할 수 있는 이벤트나 명시적 승인을 선호하십시오.
  • 프롬프트 인젝션을 피하려면 pull request, 커밋 메시지, 이슈 본문에서 오는 프롬프트 입력을 정리합니다. Codex에 전달하기 전에 HTML 주석이나 숨겨진 텍스트를 검토합니다.
  • safety-strategy를 drop-sudo로 유지하거나 Codex를 비권한 사용자로 옮겨 OPENAI_API_KEY를 보호합니다. 다중 테넌트 runner에서 액션을 unsafe 모드로 두지 마십시오.
  • 이후 단계가 예상치 못한 상태 변경을 상속하지 않도록 Codex를 작업의 마지막 단계로 실행합니다.
  • 프록시 로그나 액션 출력이 비밀 정보를 노출했다고 의심되면 즉시 키를 교체합니다.

문제 해결

  • prompt와 prompt-file을 모두 설정한 경우: 입력을 하나만 제공하도록 중복 입력을 제거합니다.
  • responses-api-proxy가 서버 정보를 쓰지 않은 경우: API 키가 있고 유효한지 확인합니다. 프록시는 openai-api-key를 제공할 때만 시작됩니다.
  • sudo 제거를 예상했지만 sudo가 성공한 경우: 이전 단계가 sudo를 복원하지 않았는지, runner OS가 Linux 또는 macOS인지 확인합니다. 새 작업으로 다시 실행합니다.
  • drop-sudo 이후 권한 오류가 발생하는 경우: 액션 실행 전에 쓰기 권한을 부여합니다. 예를 들어 chmod -R g+rwX "$GITHUB_WORKSPACE"를 사용하거나 unprivileged-user 패턴을 사용합니다.
  • 승인되지 않은 트리거가 차단된 경우: 기본 쓰기 권한 협업자 외에 서비스 계정을 허용해야 한다면 allow-users 또는 allow-bots 입력을 조정합니다.
Previous
MCP Server