소속팀: AI플랫폼엔지니어링 작성자: 손재홍
안녕하세요. AI 플랫폼 엔지니어링팀 손재홍입니다.
최근 OpenAI Codex GitHub Actions와 PR 리뷰 자동화 흐름을 다시 봤습니다. PDP에 OpenAI Codex GitHub Actions 연동 및 PR 리뷰 자동화를 통한 팀 개발 워크플로우 효율화로 기록해두었습니다. 이전에 Codex CLI와 AGENTS.md를 보면서 개인 개발 환경에서 규칙을 맞추는 방식은 어느 정도 이해했습니다. 여기서는 한 단계 더 나아가 PR이 올라온 뒤 팀 단위로 자동 리뷰를 붙이는 방법을 중심으로 봤습니다.
처음에는 단순히 PR이 올라오면 AI가 코멘트를 달아주는 기능 정도로 생각했습니다. 그런데 공식 Codex 매뉴얼을 보니 흐름이 두 갈래로 나뉘었습니다. 하나는 GitHub PR에서 `@codex review`를 호출하거나 자동 리뷰를 켜는 방식입니다. 다른 하나는 `openai/codex-action@v1`을 GitHub Actions workflow에 넣어서 CI/CD 단계에서 Codex를 실행하는 방식입니다. 둘 다 PR 리뷰에 쓸 수 있지만, 운영 관점에서는 목적과 통제 지점이 조금 다릅니다.
두 가지 흐름을 구분해서 보기
Codex code review in GitHub 문서에서는 Codex가 pull request diff를 리뷰하고, repository guidance를 따르며, serious issue 중심의 GitHub code review를 남긴다고 설명합니다. 사용 방식은 비교적 간단합니다. Codex Cloud를 repository에 설정하고, code review 설정을 켠 뒤, PR comment에 `@codex review`를 남기면 됩니다. 자동 리뷰를 켜면 새 PR이 review 상태로 열릴 때 Codex가 자동으로 리뷰를 남길 수 있습니다.
반면 Codex GitHub Action 문서는 `openai/codex-action@v1`을 사용해 CI/CD job 안에서 Codex를 실행하는 방식을 설명합니다. 이 action은 Codex CLI를 설치하고, OpenAI API key를 제공하면 Responses API proxy를 시작하며, 지정한 permission으로 `codex exec`를 실행합니다. PR 리뷰, release prep, migration, quality check 같은 반복 작업을 workflow 파일로 정의할 수 있습니다.
`@codex review`는 GitHub PR에서 리뷰어처럼 Codex를 호출하는 흐름에 가깝습니다. Codex GitHub Action은 CI/CD pipeline 안에 Codex 작업을 넣는 흐름입니다. 전자는 팀 리뷰 보조에 가깝고, 후자는 자동화 job에 가깝습니다. 두 방식이 겹치기는 하지만, 운영 기준은 다르게 잡아야 합니다.
PR 자동 리뷰를 목표로 한다면 먼저 `@codex review`와 automatic review를 검토할 수 있습니다. 특정 prompt와 output 처리, artifact upload, gate 조건, release task까지 넣고 싶다면 GitHub Action 쪽이 더 적합합니다. 이번 학습에서 저는 GitHub Action을 단순 PR 코멘트 도구가 아니라 CI 작업 안에서 Codex를 통제해서 실행하는 방법으로 이해했습니다.
PR 리뷰에서 Codex가 맡을 수 있는 범위
공식 문서에서는 Codex code review가 high-signal review pass를 제공하고, GitHub에서는 P0와 P1 이슈만 flag한다고 설명합니다. 이 부분이 좋았습니다. 자동 리뷰가 모든 사소한 문제를 다 지적하면 팀이 금방 피로해집니다. Typo, 사소한 스타일, 개인 취향에 가까운 코멘트가 많으면 오히려 리뷰 품질이 떨어집니다.
PR 리뷰 자동화에서 Codex가 맡기 좋은 범위는 심각한 버그, 보안 회귀, 인증/권한 누락, 데이터 손상 가능성, 테스트 누락 같은 부분입니다. 문서에서도 AGENTS.md의 Review guidelines를 통해 repository-specific review guidance를 줄 수 있다고 되어 있습니다. 예를 들어 PII를 log에 남기지 말라거나, 인증 middleware가 모든 route를 감싸는지 확인하라는 식입니다.
데이터 플랫폼 코드에 대입하면 review guideline은 조금 다르게 잡을 수 있습니다. 예를 들어 batch job에서 target overwrite 범위가 과도하지 않은지, partition filter가 빠져 full scan이 발생하지 않는지, retry가 중복 적재를 만들지 않는지, secret이 코드에 들어가지 않았는지, 장애 시 알림이 남는지 등을 볼 수 있습니다.
중요한 것은 Codex에게 모든 것을 맡기지 않는 것입니다. Codex review는 사람 리뷰를 대체하기보다 사람이 놓치기 쉬운 위험을 한 번 더 보는 장치로 보는 편이 맞습니다. 특히 데이터 파이프라인은 운영 맥락을 모르면 false positive나 false negative가 생길 수 있습니다. 자동 리뷰는 merge 전 마지막 안전장치 중 하나로 두고, 최종 판단은 reviewer가 해야 합니다.
GitHub Action workflow의 기본 구조
Codex GitHub Action 공식 예시는 pull_request 이벤트에서 시작합니다. PR이 opened, synchronize, reopened 될 때 job이 실행되고, `actions/checkout`으로 PR merge ref를 checkout한 뒤, base와 head ref를 fetch합니다. 이후 `openai/codex-action@v1`을 호출하고, `prompt-file`로 `.github/codex/prompts/review.md` 같은 파일을 넘깁니다. 마지막으로 action의 `final-message` output을 GitHub comment로 게시합니다.
이 흐름을 단순화하면 다음과 같습니다.
- PR 이벤트 발생
- GitHub runner에서 repository checkout
- base/head diff를 볼 수 있게 ref 준비
- Codex Action 실행
- prompt-file 기준으로 Codex가 review 수행
- final-message를 PR comment로 게시
여기서 마음에 들었던 부분은 prompt를 workflow에 바로 넣지 않고 파일로 둘 수 있다는 점입니다. Prompt를 `.github/codex/prompts/` 같은 위치에 두면 리뷰 기준을 코드처럼 관리할 수 있습니다. 팀에서 review guideline을 바꿀 때 workflow YAML을 직접 만지는 대신 prompt 파일을 수정하면 됩니다.
또 `output-file`을 지정하면 Codex의 final message를 파일로 저장할 수 있습니다. 나중에 artifact로 올리거나, 다른 step에서 처리하거나, 로그를 남기는 데 쓸 수 있습니다. 단순히 댓글만 남기는 것보다 운영 관점에서는 output을 보존하는 쪽이 좋습니다.
prompt-file을 어떻게 잡을지
Codex Action 문서에서는 `prompt` 또는 `prompt-file` 중 하나를 제공하라고 합니다. 저는 팀 운영에서는 prompt-file이 더 낫다고 봅니다. Inline prompt는 빠르게 테스트하기 좋지만, 리뷰 기준이 길어지면 관리가 어렵습니다. Prompt-file은 변경 이력을 남기기 쉽고, PR에서 리뷰 기준 변경도 같이 검토할 수 있습니다.
PR review prompt에는 너무 많은 요구사항을 넣지 않는 편이 좋습니다. 예를 들어 아래 정도가 현실적입니다.
- PR diff에서 P0/P1 수준의 문제를 우선 확인
- 데이터 삭제, overwrite, schema 변경, 권한 변경은 더 엄격하게 확인
- 테스트 누락이 실제 장애로 이어질 수 있는 경우만 지적
- 스타일 취향이나 사소한 문구는 지적하지 않음
- 불확실하면 단정하지 말고 확인 질문으로 남김
- 내부 URL, secret, 개인정보가 output에 노출되지 않도록 주의
이렇게 기준을 좁혀야 Codex comment가 유용합니다. 리뷰 자동화가 실패하는 흔한 이유는 너무 많은 것을 보게 해서 결과가 산만해지는 것입니다. Codex가 모든 관점에서 리뷰하려고 하면 comment가 길어지고, reviewer는 실제 중요한 이슈를 놓칠 수 있습니다.
AGENTS.md와 prompt-file의 역할도 구분해야 합니다. AGENTS.md는 repository 전체 또는 하위 디렉터리별 지속 규칙에 가깝습니다. Prompt-file은 이번 workflow에서 어떤 작업을 수행할지 지시하는 파일에 가깝습니다. 예를 들어 AGENTS.md에는 “배치 job은 idempotent해야 한다” 같은 규칙을 두고, review prompt에는 “이번 PR diff에서 idempotency 위반 가능성을 확인하라”고 쓸 수 있습니다.
권한을 최소화해야 함
GitHub Actions에서 자동화를 붙일 때 가장 먼저 봐야 할 것은 권한입니다. 공식 예시에서도 Codex 실행 job은 `contents: read`로 두고, comment를 게시하는 별도 job에는 `issues: write`, `pull-requests: write`를 둡니다. 이 분리는 중요합니다. Codex가 리뷰만 하면 되는 단계에서는 repository 쓰기 권한이 필요하지 않습니다.
PR comment 게시 단계도 마찬가지입니다. Codex 실행과 GitHub comment posting을 분리하면 어느 step이 어떤 권한을 쓰는지 명확합니다. 나중에 이슈가 생겼을 때 권한 범위를 좁히기 쉽습니다.
또 checkout 단계에서 `persist-credentials: false`를 사용하는 것도 의미가 있습니다. GitHub token이 checkout 후 git config에 남는 것을 줄이려는 목적입니다. 자동화에서 중요한 것은 되도록 필요한 순간에 필요한 권한만 쓰는 것입니다.
OpenAI API key는 GitHub secret에 저장하고 workflow에서 `OPENAI_API_KEY` 같은 secret을 참조해야 합니다. Action 문서에서도 OpenAI key를 GitHub secret으로 저장하라고 설명합니다. 이 key가 로그나 output에 노출되지 않도록 해야 합니다. 특히 PR에서 들어온 text를 prompt에 직접 넣는 경우 prompt injection과 secret 노출 가능성을 같이 봐야 합니다.
sandbox와 safety-strategy
Codex GitHub Action 문서에서 가장 중요하게 본 부분은 privilege 관리였습니다. 문서에서는 Codex가 GitHub-hosted runner에서 broad access를 가질 수 있으므로 `safety-strategy`, `sandbox`, `allow-users`, `allow-bots` 같은 입력으로 exposure를 통제하라고 설명합니다.
기본 `safety-strategy`는 `drop-sudo`입니다. 문서에 따르면 이 설정은 Codex 실행 전에 sudo를 제거해서 memory에 있는 secret 보호에 도움을 줍니다. Linux나 macOS runner에서는 이 기본값을 유지하는 것이 좋습니다. Windows에서는 `safety-strategy: unsafe`가 필요하다고 되어 있지만, 일반적인 PR 리뷰 workflow라면 Linux runner를 쓰는 편이 더 단순합니다.
`sandbox`는 Codex 내부에서 filesystem과 network access를 제한하는 설정입니다. Action input으로 `workspace-write`, `read-only`, `danger-full-access`를 선택할 수 있습니다. PR review만 하는 경우라면 read-only 또는 최소 권한에 가깝게 시작하는 것이 맞습니다. 파일을 수정하거나 patch를 적용하는 workflow라면 workspace-write가 필요할 수 있지만, review comment만 남기는 작업에 danger-full-access는 과합니다.
공식 security checklist에서도 workflow를 시작할 수 있는 사람을 제한하고, PR body나 commit message 같은 입력을 sanitize하며, unsafe mode를 피하고, Codex를 job의 마지막 단계로 실행하라고 설명합니다. 이 내용은 실무 도입 시 거의 그대로 체크리스트로 쓸 수 있습니다.
자동 리뷰 트리거를 조심해야 함
PR 리뷰 자동화를 만들 때 `pull_request` 이벤트와 `pull_request_target` 이벤트를 구분해야 합니다. 공식 예시는 `pull_request` 이벤트를 사용합니다. 외부 fork PR까지 다루는 public repository라면 secret 노출 위험을 더 조심해야 합니다. private repository라도 PR 작성자가 누구인지, bot 계정이 trigger할 수 있는지 기준이 필요합니다.
Codex Action에는 `allow-users`와 `allow-bots` 입력이 있습니다. 문서에서는 기본적으로 write access가 있는 사용자만 action을 실행할 수 있고, 추가로 신뢰할 계정을 명시할 수 있다고 설명합니다. 이 기능은 운영 관점에서 중요합니다. 아무나 prompt를 바꿔 Codex를 실행하게 하면 비용과 보안 리스크가 커집니다.
또 PR에서 가져온 text를 그대로 prompt로 넘기면 prompt injection 이슈가 생길 수 있습니다. 공식 security checklist에서도 PR, commit message, issue body 등에서 온 prompt input을 sanitize하라고 합니다. 리뷰 자동화에서 가장 쉬운 실수는 “PR 설명을 같이 읽고 리뷰해줘”라고 하면서 PR body를 그대로 주는 것입니다. PR body에는 사람이 의도적으로 넣은 숨은 지시가 있을 수 있습니다.
그래서 처음 도입할 때는 PR diff와 repository rules 중심으로 시작하고, PR body나 issue comment를 넣어야 한다면 별도 입력 정돈 과정을 두는 것이 좋습니다. 자동화가 편해질수록 입력 관리가 더 중요해집니다.
결과를 어떻게 남길지
Codex Action은 마지막 Codex message를 `final-message` output으로 제공합니다. 예시 workflow에서는 이 값을 다음 job의 environment variable로 넘기고 `actions/github-script`로 PR comment를 작성합니다. 이 방식은 단순하지만 운영에 필요한 최소 흐름을 보여줍니다.
저는 여기서 comment 형식을 정해두는 것이 필요하다고 봅니다. 예를 들어 아래처럼 구성할 수 있습니다.
- 리뷰 범위
- 발견한 P0/P1 이슈
- 확인 필요 사항
- 테스트 또는 로그 확인 제안
- 자동 리뷰 한계
이렇게 구조를 고정하면 reviewer가 빠르게 읽을 수 있습니다. Codex가 긴 설명을 늘어놓으면 자동화의 장점이 줄어듭니다. PR comment는 짧고 확인 가능한 형태가 좋습니다.
또 output-file을 같이 남기면 나중에 debugging에 도움이 됩니다. PR comment는 수정되거나 사라질 수 있고, GitHub UI에서 찾기 번거로울 수 있습니다. Output artifact나 job log로 남겨두면 자동 리뷰 품질을 개선할 때 참고할 수 있습니다. 다만 output에 민감정보가 들어가지 않도록 prompt에서 제한하고, workflow에서도 artifact 공개 범위를 확인해야 합니다.
자동 리뷰와 사람 리뷰의 경계
Codex 리뷰가 유용하다고 해서 바로 merge gate로 쓰는 것은 조심해야 합니다. 처음에는 comment-only로 시작하는 편이 낫습니다. Codex가 남긴 의견을 사람이 보고 실제로 맞는지 확인하고, false positive와 missed case를 모아야 합니다. 몇 주 정도 쌓인 뒤에 특정 유형만 gate로 바꾸는 것이 안전합니다.
예를 들어 secret 노출, PII logging, destructive migration, test 없는 schema 변경 같은 항목은 gate 후보가 될 수 있습니다. 반대로 코드 스타일, 네이밍, 일반적인 성능 조언은 gate로 쓰기 어렵습니다. 자동 리뷰는 확실한 위험부터 좁게 시작해야 합니다.
사람 리뷰와의 경계도 명확해야 합니다. Codex는 “이 부분을 확인하라”고 알려주는 보조 reviewer입니다. 최종 merge 판단, 업무 맥락 판단, 장애 영향도 판단은 사람이 해야 합니다. 특히 데이터 플랫폼 업무에서는 운영 배포 일정, 외부 요청 배경, 기존 장애 이력 같은 context가 PR diff만으로 보이지 않을 수 있습니다.
데이터 플랫폼 업무에 대입한 적용 방식
데이터 플랫폼 코드에 Codex PR 리뷰 자동화를 붙인다면 저는 처음부터 넓게 보지 않고 세 가지 범위로 시작할 것 같습니다.
첫째, 위험한 데이터 변경 감지입니다. Delete, truncate, overwrite, merge 조건 변경, partition filter 제거, schema 변경, null 처리 변경은 운영 영향이 큽니다. Codex가 이런 diff를 보고 reviewer에게 확인 포인트를 남기면 도움이 됩니다.
둘째, 운영성 확인입니다. 배치 job 변경에 retry, alert, logging, idempotency, backfill 고려가 있는지 봅니다. 특히 “실패 후 재실행해도 중복 적재가 생기지 않는가”는 데이터 엔지니어링 리뷰에서 자주 확인해야 하는 지점입니다.
셋째, 보안과 권한 확인입니다. Secret hardcoding, 과도한 IAM permission, 민감정보 log 출력, 외부 endpoint 호출, 권한 없는 table 접근 가능성을 봅니다. 이 부분은 Codex review guideline에 명시하기 좋습니다.
처음 운영 기준은 comment-only로 두고, 일정 기간 동안 사람이 comment 품질을 평가합니다. 실제로 맞았던 지적, 틀렸던 지적, 놓친 지적을 모아 prompt-file과 AGENTS.md를 수정합니다. 그 다음 특정 항목만 필수 확인으로 올릴 수 있습니다.
도입 순서
실무 도입 순서는 아래처럼 잡는 것이 좋아 보였습니다.
- repository에 AGENTS.md review guideline 추가
- `.github/codex/prompts/review.md` 작성
- pull_request 이벤트에서 Codex Action 실행
- Codex job은 read 권한 중심으로 제한
- final-message를 PR comment로 게시
- 첫 단계는 comment-only로 운영
- false positive와 missed case를 모아 prompt 개선
- 충분히 안정된 항목만 gate 후보로 검토
이 순서가 좋은 이유는 자동화를 작게 시작할 수 있기 때문입니다. 처음부터 merge block을 걸면 반발이 생길 수 있습니다. 반대로 comment-only로 시작하면 팀이 부담 없이 품질을 볼 수 있습니다. 자동화는 팀이 신뢰할 수 있을 때 조금씩 강해져야 합니다.
이번 학습에서 남은 기준
이번 학습에서 가장 크게 남은 것은 Codex GitHub Actions가 단순한 AI 리뷰 기능이 아니라는 점입니다. PR 이벤트, checkout, prompt-file, Codex 실행, output, comment posting, permission, sandbox, trigger 제한이 모두 연결된 workflow입니다.
기준은 다음과 같이 볼 수 있습니다.
- `@codex review`와 Codex GitHub Action은 목적이 다름
- PR 리뷰는 P0/P1 중심으로 좁게 시작하는 것이 좋음
- AGENTS.md는 지속 규칙, prompt-file은 workflow별 작업 지시로 분리
- workflow 권한은 Codex 실행과 comment posting을 분리
- `safety-strategy: drop-sudo`와 좁은 sandbox를 기본으로 검토
- PR body, commit message, issue body를 prompt로 쓸 때 injection을 조심
- 처음에는 comment-only로 운영하고, gate는 충분히 검증 후 적용
- 자동 리뷰는 사람 리뷰를 대체하지 않고 위험 신호를 먼저 보여주는 역할
Codex GitHub Actions는 PR 리뷰를 자동화하는 도구이면서 동시에 팀 개발 프로세스에 AI 검토 단계를 넣는 방법입니다. 실무에 적용하려면 “자동으로 코멘트를 달 수 있다”보다 “어떤 권한으로, 어떤 입력을 받아, 어떤 기준으로, 어떤 결과를 남길 것인가”를 먼저 정해야 합니다. 이 기준이 있어야 자동 리뷰가 방해가 아니라 팀 생산성을 높이는 장치가 될 수 있습니다.
참고 자료
- OpenAI Codex code review in GitHub: https://developers.openai.com/codex/integrations/github
- OpenAI Codex GitHub Action: https://developers.openai.com/codex/github-action
- OpenAI Codex Agent approvals and security: https://developers.openai.com/codex/agent-approvals-security
- OpenAI Codex Custom instructions with AGENTS.md: https://developers.openai.com/codex/concepts/customization#agents-guidance
핵심 키워드 태그
#OpenAI #Codex #GitHubActions #PRReview #CI #CodeReview #DataEngineering #PDP #LND