Chapter 15. 깃허브 워크플로 통합

Codex를 혼자만 잘 쓰는 개발자는 금방 빠르다고 느낍니다. 하지만 팀은 다릅니다. 팀은 속도보다 흐름을 봅니다. 이슈가 들어오고, 누가 먼저 보고, PR이 올라오고, 리뷰가 달리고, 수정이 다시 반영되고, 최종 승인과 머지까지 이어지는 그 긴 줄 위에 Codex가 올라타지 못하면 결국 이렇게 말하게 됩니다.

좋은 데모였고, 우리 팀 일하는 방식이랑은 안 맞네.

이 장의 목표는 간단합니다. Codex를 멋진 장난감이 아니라 팀의 기본 루틴으로 바꾸는 것입니다. 핵심은 세 가지입니다. GitHub 안에서 자동으로 움직이게 만들고, Slack에서 작업을 시작할 수 있게 하고, 마지막 검토는 사람이 잡는 구조를 만드는 것입니다.

협업 루프는 이렇게 만든다

실무에서 가장 잘 굴러가는 Codex 협업 루프는 대체로 아래 순서로 흘러갑니다.

• 이슈가 열리면 Codex가 먼저 읽고 요약한다.

• PR이 올라오면 Codex가 1차 리뷰를 맡는다.

• 사람이 /codex 지시로 재수정이나 후속 작업을 요청한다.

• 팀 대화는 Slack에서 시작하고, 무거운 실행은 Codex 클라우드나 CI가 맡는다.

• 최종 승인과 머지는 사람이 한다.

이 구조의 장점은 분명합니다. 사람이 제일 비싼 시간인 처음 읽기, 반복 지적, 사소한 수정 재요청에서 빠져나옵니다. 대신 설계 판단, 배포 위험, 비즈니스 의도 검증 같은 진짜 사람 일이 남습니다.

openai/codex-action은 기본 블록이다

GitHub Actions에 Codex를 올리는 가장 기본적인 방법은 공식 액션인 openai/codex-action@v1을 쓰는 것입니다. 이 액션은 러너에서 Codex CLI를 준비하고, API 키가 있으면 필요한 프록시를 띄운 뒤, 지정한 권한 안에서 Codex 작업을 실행하는 식으로 동작합니다.¹

중요한 점은 이 액션이 완성된 제품이라기보다 기본 블록에 가깝다는 것입니다. 즉, 무엇을 리뷰할지, 어떤 형식으로 결과를 남길지, 이후에 PR 댓글을 달지, 라벨을 붙일지까지 팀이 설계해야 합니다. 대신 그만큼 유연합니다.

가장 먼저 넣을 만한 PR 자동 리뷰 워크플로는 아래처럼 시작하면 됩니다.

name: codex-pr-review

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run Codex review
        id: codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          sandbox: read-only
          safety-strategy: drop-sudo
          prompt: |
            Review this pull request diff.
            Focus on correctness, auth flow, migrations, and test gaps.
            Follow Review guidelines in AGENTS.md.

여기서 포인트는 세 가지입니다. fetch-depth: 0으로 diff 문맥을 충분히 가져오고, 기본은 read-only로 시작하고, 프롬프트에는 팀이 정말 중요하게 보는 검토 축만 넣는 것입니다. 한 번에 너무 많은 걸 보라고 하면, 사람 리뷰처럼 Codex도 잔소리 머신이 됩니다.

이슈 자동 트리아지: 받은편지함을 먼저 정리하라

협업 루프에서 생각보다 큰 병목은 PR이 아닙니다. 그보다 앞단인 이슈 입력창입니다. 버그 제보, 기능 요청, 고객 문의, 재현 안 되는 스크린샷이 한 바구니에 들어오면 팀은 개발보다 분류를 더 오래 하게 됩니다.

이 단계에서 Codex는 놀랄 만큼 쓸모가 있습니다. 해야 할 일은 어렵지 않습니다. 새 이슈가 열리면 Codex가 내용을 읽고 다음 네 가지를 정리하게 하면 됩니다.

• 한 줄 요약

• 누락된 정보

• 추천 라벨

• 우선순위

예를 들어 Next.js + Supabase 프로젝트라면 버그를 auth, billing, schema, ui, docs 중 하나로 분류하게 만들 수 있습니다. Express + MongoDB 백엔드라면 validation, query, index, security, ops 같은 식으로 팀 언어에 맞추면 됩니다.

아래처럼 시작하면 충분합니다.

name: codex-issue-triage

on:
  issues:
    types: [opened]

permissions:
  contents: read
  issues: write

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Triage issue with Codex
        id: triage
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          sandbox: read-only
          prompt: |
            Read the new GitHub issue.
            Return:
            1. short summary
            2. missing reproduction info
            3. suggested label
            4. severity
            Use the repository conventions in AGENTS.md.

이슈 트리아지의 묘미는 정확도 100%가 아닙니다. 사람이 처음 읽는 비용을 줄이는 데 있습니다. 아침에 GitHub 이슈 17개가 쌓여 있어도, 팀 리드는 이미 달린 요약만 읽고 우선순위를 잡을 수 있습니다. AI가 엉뚱한 라벨을 한두 개 붙여도 괜찮습니다. 받은편지함을 비우는 속도가 훨씬 빨라지기 때문입니다.

PR 자동 리뷰는 두 갈래로 생각하자

PR 리뷰에 Codex를 붙이는 방법은 크게 두 갈래입니다.

첫 번째는 GitHub 쪽 네이티브 흐름입니다. PR에 @codex review를 남기거나 자동 리뷰를 켜 두면, Codex가 PR을 읽고 인라인 코멘트를 답니다. 이때 저장소의 AGENTS.md에 있는 Review guidelines가 리뷰 기준에 반영되므로, 팀이 중요하게 보는 위험을 Codex가 더 잘 집어냅니다.³

두 번째는 Actions 중심 흐름입니다. 이쪽은 더 엔지니어링스럽습니다. 리뷰 타이밍, 모델, 프롬프트, 출력 형식, 후속 스텝을 직접 제어할 수 있습니다. 즉시 도입은 네이티브 방식이 쉽고, 재현성과 조직 표준화는 Actions 방식이 강합니다.

실무에서는 둘을 이렇게 나누면 좋습니다.

• 소규모 팀, 빠른 도입: 네이티브 @codex review

• 팀 규칙이 복잡함, 보안 요구 높음: Actions 기반 자동 리뷰

• PR에서 바로 수정까지 이어가고 싶음: 리뷰 액터 추가

특히 리뷰 품질은 프롬프트보다 AGENTS.md에서 더 오래갑니다. 프롬프트는 워크플로 파일마다 흩어지지만, AGENTS.md는 저장소의 습관이 됩니다. 예를 들어 Supabase를 쓰는 팀이라면 이런 규칙이 꽤 강력합니다.

## Review guidelines
- Supabase RLS 정책 변경은 항상 마이그레이션과 테스트를 함께 확인한다.
- Next.js 서버 액션에서 service_role 키 사용은 P0로 본다.
- 공개 API 응답 구조 변경은 changelog 누락 여부를 확인한다.
- 결제 로직에서 idempotency 키 누락은 P1로 본다.

이 규칙이 있으면 Codex는 단순히 코드 예쁘네요를 말하는 도우미가 아니라, 우리 팀에서 자주 터지는 사고를 먼저 보는 리뷰어가 됩니다.

PR 자동 리뷰 + CI 자동 수정 루프 만들기

팀이 정말 편해지는 지점은 리뷰까지만이 아닙니다. 리뷰 뒤의 재요청까지 자동화될 때입니다. 이때 유용한 것이 gersmann/codex-review-action@v1 같은 PR 리뷰 전용 액션입니다. 이 액션은 리뷰 모드에서는 인라인 코멘트와 PR 요약을 남기고, 액트 모드에서는 신뢰된 사용자가 PR 댓글에 /codex ...를 남겼을 때 실제 수정까지 수행하도록 설계되어 있습니다.²

가장 현실적인 패턴은 이렇습니다.

1. PR이 열리면 Codex가 자동 리뷰를 단다.

2. 사람이 그중 맞는 지적만 고른다.

3. 리뷰어가 /codex unresolved review comments만 반영하고 테스트까지 돌려줘라고 댓글을 단다.

4. Codex가 브랜치를 checkout하고 수정 후 다시 push한다.

5. CI가 다시 돌고, 사람은 최종 diff만 확인한다.

핵심은 누구나 이 루프를 발동시키면 안 된다는 점입니다. 해당 액션은 MEMBER, OWNER, COLLABORATOR 같은 GitHub author association 기반 허용 목록을 둘 수 있고, 워크플로 수준에서도 한 번 더 막을 수 있습니다.²

아래 예시는 최소 구성의 느낌을 보여줍니다.

name: codex-act-on-comment

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  act:
    if: >-
      github.actor != 'dependabot[bot]'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ secrets.REPO_ACCESS_TOKEN }}

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - run: npm test -- --runInBand

      - name: Codex autonomous edits
        uses: gersmann/codex-review-action@v1
        with:
          mode: act
          openai_api_key: ${{ secrets.OPENAI_API_KEY }}
          allowed_commenter_associations: MEMBER,OWNER,COLLABORATOR

여기서 절대 빼먹지 말아야 할 문장이 있습니다. Give the agent a working environment. 다시 말해, Codex가 코드를 고치기만 하고 테스트를 못 돌리면 팀은 결국 더 불안해집니다. 의존성 설치, 시드 데이터, 마이그레이션, 테스트 실행까지 액션 안에 넣어 두어야 진짜 업무가 줄어듭니다.²

슬랙에서 @Codex로 작업을 시작하기

실무에서 코딩 작업은 GitHub보다 Slack에서 먼저 시작되는 경우가 많습니다. PM이 버그를 던지고, 디자이너가 스크린샷을 올리고, 운영팀이 고객 문의를 붙이고, 개발자가 그 스레드에서 맥락을 이어받습니다. Codex의 Slack 통합은 바로 이 지점을 노립니다. 채널이나 스레드에서 @Codex를 멘션하면 Codex가 클라우드 태스크를 만들고 결과를 다시 답합니다.⁴

이 기능이 좋은 이유는 GitHub 이슈를 대체해서가 아닙니다. 오히려 GitHub로 들어가기 전의 애매한 말들을 작업 가능한 요청으로 바꿔 주기 때문입니다.

예를 들어 #prod-alerts 채널에서 이런 식으로 쓸 수 있습니다.

@Codex 어젯밤부터 카카오 로그인 콜백에서 간헐적으로 500이 납니다.
관련 PR은 #182이고, 재현은 모바일 웹에서 더 잘 됩니다.
원인 후보를 정리하고, 핫픽스 PR 초안까지 만들어줘.

이 한 줄의 장점은 큽니다. 담당 개발자가 노트북을 열기 전에도 탐색이 시작됩니다. 특히 시차가 있는 팀이나, 한국 스타트업처럼 오전 회의 전에 이슈를 빠르게 정리해야 하는 조직에서 체감이 큽니다.

다만 Slack은 편한 만큼 조심할 점도 있습니다. Slack에서 Codex 요청에 쓰인 메시지와 관련 문맥은 Codex 작업의 일부로 저장될 수 있으므로, 민감한 코드 조각이나 고객 개인정보를 무심코 붙이는 습관은 버려야 합니다.⁵ 보안이 중요한 팀이라면 다음 원칙을 먼저 정하세요.

• 민감 정보가 오가는 채널에서는 @Codex 사용 금지

• 고객 식별 정보는 마스킹 후 전달

• 운영 사고 분석은 요약본만 전달하고 원문 로그는 승인된 도구에서 조회

Slack 연동은 편의 기능이 아니라 업무 시작점을 바꾸는 기능입니다. 그러니 도입 전에 보안 규칙부터 같이 넣어야 오래 갑니다.

모바일 검토 루프: 출근길에 승인까지 끝내기

모바일에서 코드를 직접 고치는 것은 아직도 불편합니다. 하지만 모바일에서 판단하는 일은 충분히 가능합니다. 이 차이를 이해하면 Codex 모바일 활용이 아주 선명해집니다.

실무적으로 가장 안전한 패턴은 이렇습니다.

아침 출근길에 ChatGPT 앱에서 Codex가 남긴 PR 요약과 핵심 코멘트를 확인합니다. 심각한 보안 이슈나 테스트 실패 가능성만 먼저 봅니다. 추가 질문이 있으면 Codex에 성능 회귀만 다시 봐줘, 인증 흐름만 집중해서 재검토해줘처럼 짧게 던집니다. 그리고 최종 머지 버튼은 GitHub 모바일 앱이나 브라우저에서 누릅니다.

이 흐름이 좋은 이유는 모바일의 약점을 피하기 때문입니다. 작은 화면에서는 긴 diff를 처음부터 끝까지 읽기 어렵습니다. 대신 Codex가 먼저 위험 구역을 정리해 두면 사람은 승인할 수 있는가만 결정하면 됩니다. 출근길 20분이 PR 대기열을 줄이는 시간으로 바뀌는 셈입니다.

특히 팀 리드에게 유용합니다. 한 명이 모든 코드를 직접 뜯어보기는 어렵지만, Codex가 이미 1차 리뷰를 해 두면 리드는 결제 로직, 인증, 데이터 마이그레이션 같은 고위험 부분만 골라 판단할 수 있습니다.

사람 리뷰어와 Codex의 역할을 분리하라

Codex를 GitHub에 붙였다고 해서 사람 리뷰가 필요 없어지는 것은 아닙니다. 오히려 역할이 더 선명해집니다.

• Codex는 반복적이고 기계적인 위험 탐지에 강합니다.

• 사람은 제품 의도, 설계 방향, 조직 맥락 판단에 강합니다.

• 최종 승인권은 사람이 가져야 팀이 안심합니다.

예를 들어 Codex는 이 라우트에 인증 미들웨어가 빠졌습니다를 잘 잡습니다. 하지만 이번 분기에는 속도보다 출시가 우선이므로 이 설계 부채를 이번엔 허용하자 같은 판단은 못 합니다. 반대로 사람은 이런 전략적 판단을 잘하지만, 매번 비슷한 널 체크 누락과 에러 핸들링 누락을 다 찾아내는 일에는 쉽게 지칩니다.

그래서 가장 좋은 팀은 사람 리뷰를 없애는 팀이 아니라, 사람 리뷰를 비싸고 중요한 질문에만 쓰는 팀입니다.

실전 예시: Next.js + Supabase 팀의 하루

가상의 팀이 아니라, 한국에서 정말 많이 만들 법한 조합으로 생각해 봅시다. 서비스는 Next.js + Supabase로 만든 멤버십 SaaS입니다. 결제는 외부 PG를 붙였고, 관리자 페이지는 내부 운영팀도 같이 씁니다.

월요일 오전 9시 10분, 운영팀이 Slack에 글을 남깁니다. 신규 가입 후 매직 링크 로그인에서 일부 사용자가 대시보드로 안 넘어갑니다. 개발팀은 바로 @Codex를 태그해 원인 후보 탐색과 관련 PR 추적을 부탁합니다. Codex는 최근 인증 관련 PR 둘을 엮어 보고, redirectTo 처리 변경과 RLS 정책 수정이 의심된다고 정리합니다.

오전 9시 25분, 담당 개발자가 GitHub 이슈를 열면 트리아지 워크플로가 자동으로 돌아갑니다. 라벨은 auth, 우선순위는 high, 누락 정보로는 브라우저 종류, 모바일 웹 여부, 재현 계정 유무가 정리됩니다.

오전 10시, 수정 PR이 올라옵니다. Codex 자동 리뷰가 먼저 달립니다. redirect 파라미터 검증 누락, 실패 시 에러 메시지 로깅 부족, 테스트가 성공 경로만 검증이라는 세 가지 코멘트가 붙습니다. 리뷰어는 그중 두 개를 채택하고 PR에 이렇게 남깁니다.

/codex unresolved review comments만 반영하고,
로그인 실패 케이스에 대한 Playwright 테스트까지 추가해줘.
변경 범위는 auth 관련 파일로 최소화.

Codex가 브랜치에서 수정 후 다시 push합니다. CI가 통과합니다. 팀 리드는 점심 먹으러 가는 길에 모바일에서 요약을 읽고, 마지막으로 redirect 로직 diff만 확인한 뒤 승인합니다. 머지는 GitHub 앱에서 사람이 누릅니다.

이 하루를 보면 중요한 사실이 드러납니다. Codex가 개발자를 대신해 일한 것이 아닙니다. 팀의 대기 시간을 없앴습니다. 바로 이 점이 협업 도구로서 Codex의 진짜 가치입니다.

실패하지 않는 운영 원칙

Codex를 GitHub 워크플로에 붙일 때는 화려한 데모보다 운영 원칙이 더 중요합니다.

첫째, 처음에는 리뷰 전용으로 시작하세요. 바로 자동 수정까지 열어 두면 팀이 불안해합니다. read-only 리뷰 → 신뢰된 사용자만 act → 고위험 레포는 수동 승인 순서가 좋습니다.

둘째, 권한은 최소로 주세요. 리뷰만 할 때는 contents: read와 pull-requests: write 정도면 충분합니다. 수정이 필요할 때만 contents: write를 여세요.²

셋째, 액션 안에 테스트 실행을 꼭 넣으세요. Codex가 코드를 고쳐도 테스트를 못 돌리면, 결국 사람은 더 큰 diff를 더 오래 보게 됩니다.

넷째, 포크 PR에는 특히 보수적으로 대응하세요. 기본 GITHUB_TOKEN은 포크 브랜치에 push가 어려운 경우가 많고, 무리하게 PAT를 열면 보안 면적이 넓어집니다.²

다섯째, Codex 장애를 전제로 운영하세요. 실제로 Codex와 ChatGPT에 오류율이 높아지는 구간은 존재합니다. 배포 전 필수 게이트를 Codex 하나에만 묶어 두면, 서비스보다 도구가 병목이 됩니다.⁶ 사람이 직접 리뷰할 수 있는 우회 경로와, Codex 없이도 통과 가능한 CI 기준을 남겨 두세요.

무엇을 Codex에 맡기고, 무엇을 사람에게 남길까

이 장을 한 문장으로 요약하면 이렇습니다. 반복은 Codex에게, 책임은 사람에게.

Codex에게 맡기기 좋은 일은 분명합니다. 이슈 분류, PR 1차 리뷰, 리뷰 코멘트 반영, 테스트 보강, 사소한 회귀 수정, Slack에서 시작한 조사 작업의 초안화입니다. 반대로 사람에게 남겨야 하는 일도 분명합니다. 아키텍처 결정, 릴리스 판단, 보안 예외 승인, 제품 의도 검증, 이해관계자 조율입니다.

이 선을 잘 그으면 Codex는 팀을 피곤하게 만드는 도구가 아니라, 팀을 덜 기다리게 만드는 도구가 됩니다.

최신 변경

아래 항목은 바뀔 가능성이 상대적으로 높으니, 실제 도입 전에는 공식 문서를 한 번 더 확인하는 편이 좋습니다.

• GitHub Actions용 공식 액션 이름과 입력값은 openai/codex-action@v1 문서를 기준으로 확인합니다.¹

• PR 리뷰와 /codex 댓글 기반 자동 수정은 gersmann/codex-review-action@v1의 동작 방식과 권한 정책을 확인합니다.²

• Slack에서 @Codex를 멘션해 클라우드 태스크를 시작하는 흐름은 공식 Slack 통합 문서를 우선 봅니다.⁴

• 장애 여부나 오류율 증가는 배포 판단 전에 OpenAI Status에서 먼저 확인합니다.⁶

참고

¹GitHub Action - Codex | OpenAI Developers

²Codex Code Review & Actor · Actions · GitHub Marketplace · GitHub

³Codex CLI Automatic Code Review: PR Integration and Pre-Commit Workflows

⁴Use Codex in Slack | OpenAI Developers

⁵OpenAI Codex | Slack Marketplace

⁶Elevated error rates in ChatGPT Codex - OpenAI Status