클라우드 태스크 위임과 GitHub 워크플로: PR 자동 생성, 작업 병렬화

비동기 작업의 핵심은 "시간이 아니라 내 주의력"을 절약하는 것

Codex를 잘 쓰는 팀은 코드를 "직접 타이핑하는 시간"보다 "의사결정과 검증에 쓰는 집중력"이 더 비싸다는 사실을 일찍 받아들입니다. 그래서 1~30분(때로는 그 이상)이 걸리는 큰 작업은 클라우드에서 돌리고, 나는 그 사이에 다른 일을 합니다. 그리고 작업이 끝나면 결과는 '브랜치/PR'이라는 표준 형태로 돌아오게 만듭니다.

이 챕터의 목표는 단순합니다.

클라우드에서 Codex가 변경을 만들고 → GitHub가 PR을 열고 → CI가 테스트/로그를 남기고 → 나는 PR만 보고 승인/거절/수정 지시를 내리는 흐름을, 팀이 그대로 복제 가능한 형태로 정리하는 것입니다.

"태스크의 정의"를 PR 단위로 고정하기

클라우드에 일을 맡길 때 가장 흔한 실패는 '작업의 경계가 모호한 것'입니다. 경계를 PR로 고정하면 일의 크기와 완료 기준이 자연스럽게 정렬됩니다.

권장하는 태스크 정의는 다음처럼 단순합니다.

작업 입력(요구사항/맥락/제약)

작업 출력(바뀐 파일 + 테스트 결과 + 변경 요약)

실패 출력(재현 로그 + 어디까지 했는지 + 다음 제안)

즉, Codex에게 "코드를 만들어"가 아니라 "PR로 끝내"라고 시키는 겁니다. PR에는 다음 정보가 반드시 들어가야 합니다.

무엇을 바꿨는지(요약)

왜 바꿨는지(의도)

어떻게 검증했는지(테스트/명령/로그 링크)

무엇이 남았는지(리스크/후속 작업)

이 네 가지가 PR 본문에 있으면, 리뷰어는 코드보다 먼저 '결정'을 내릴 수 있습니다.

GitHub에서 태스크를 "제출"하는 3가지 인터페이스

클라우드 작업을 반복하려면, 팀이 익숙한 입력 채널이 필요합니다. 보통 세 가지 중 하나로 수렴합니다.

1) workflow_dispatch: 버튼 하나로 작업 시작

가장 단순하고 권한 관리도 쉽습니다. Actions 탭에서 수동 실행하면서 입력값(prompt, target, scope)을 받습니다. "실험적 자동화"를 시작할 때 특히 좋습니다.

2) Issue 템플릿: 업무 요청을 표준 문서로 남기기

이슈 템플릿을 태스크 명세서로 쓰면, 기록이 남고 논의가 이어집니다. Codex는 이슈 본문을 읽고 브랜치/PR을 만들면 됩니다.

3) PR 코멘트 트리거: '추가 작업'을 같은 맥락에서 이어가기

리뷰 중에 "여기까지는 좋은데, 예외 처리 추가해줘" 같은 요청을 PR 코멘트로 남기고, 특정 키워드(예: /codex fix)로 다시 태스크를 시작하는 방식입니다. 사람의 대화 흐름과 가장 자연스럽게 맞습니다.

어떤 방식을 고르든 핵심은 같습니다. 요청은 한 번에 작게, 결과는 PR로 회수합니다.

PR 자동 생성 패턴: gh CLI vs Action

Codex가 변경을 만들었다면, 다음 단계는 "PR을 여는 것"입니다. 여기서 선택지는 크게 둘입니다.

gh CLI로 PR 만들기(가장 직관적)

GitHub Actions 러너에는 GitHub CLI(gh)를 쉽게 사용할 수 있습니다. 변경을 커밋/푸시한 뒤 다음처럼 PR을 엽니다.

gh pr create \
  --title "feat: add rate limit guard" \
  --body "요약/검증/리스크를 여기에" \
  --base main \
  --head "$BRANCH"

장점은 "스크립트로 모든 걸 통제"할 수 있다는 점입니다. 예를 들어 테스트가 통과하면 gh pr merge --auto로 자동 병합 예약까지 걸 수 있습니다(팀 정책이 허용할 때).

PR 생성 전용 Action 쓰기(설정이 쉬움)

PR 생성 기능을 캡슐화한 GitHub Marketplace Action을 쓰면 YAML이 짧아지고 옵션(라벨, 리뷰어, 드래프트 등)을 선언적으로 관리할 수 있습니다. 팀이 '표준 PR 속성'을 강제하고 싶을 때 특히 편합니다.

어떤 방식을 쓰든, PR을 여는 주체(토큰)와 권한을 먼저 정리해야 합니다.

워크플로 권한과 토큰: "될 때까지"가 아니라 "되게 만든다"

자동 PR은 대부분 권한 문제에서 막힙니다. 최소한 다음을 점검하세요.

Actions 워크플로 권한이 읽기 전용인지, 읽기/쓰기인지

pull-requests: write, contents: write 같은 job permissions가 선언되어 있는지

브랜치 보호 규칙이 '봇 커밋/봇 PR'을 허용하는지

특히 "Actions가 PR을 만들고 승인까지 하게" 하려면 저장소 설정에서 별도 옵션을 켜야 하는 경우가 있습니다. 팀의 보안 정책상 승인/머지는 사람만 하도록 두는 편이 안전한 기본값입니다.

실무 예제: Codex 클라우드 작업 → PR 생성 → 로그/테스트 확인

아래는 가장 보편적인 형태의 GitHub Actions 워크플로 뼈대입니다. 포인트는 4가지입니다.

1. 브랜치를 태스크 단위로 만든다.

2. Codex는 그 브랜치에서 변경을 만든다.

3. 테스트를 돌리고 로그/아티팩트를 남긴다.

4. PR을 드래프트로 열고 리뷰어를 지정한다.

name: codex-task
on:
  workflow_dispatch:
    inputs:
      task:
        description: "Codex 작업 지시문"
        required: true
      base:
        description: "대상 브랜치"
        default: "main"
        required: true

jobs:
  run:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Create task branch
        run: |
          BRANCH="codex/${{ github.run_id }}"
          echo "BRANCH=$BRANCH" >> $GITHUB_ENV
          git checkout -b "$BRANCH"

      - name: Run Codex (example)
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          # 예: codex exec "${{ inputs.task }}" 같은 형태로 실행
          # 실제 명령은 팀의 Codex 실행 방식에 맞게 교체하세요.
          ./scripts/run-codex.sh "${{ inputs.task }}"

      - name: Commit changes (if any)
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

          if [[ -n "$(git status --porcelain)" ]]; then
            git add -A
            git commit -m "chore(codex): ${{ inputs.task }}"
            git push origin "$BRANCH"
          else
            echo "No changes."
          fi

      - name: Run tests
        run: |
          ./scripts/test.sh | tee test.log

      - name: Upload test log
        uses: actions/upload-artifact@v4
        with:
          name: test-log
          path: test.log

      - name: Create PR
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr create \
            --base "${{ inputs.base }}" \
            --head "$BRANCH" \
            --title "[codex] ${{ inputs.task }}" \
            --body "## 요약
- (Codex가 만든 변경 요약)

## 검증
- ./scripts/test.sh (로그: Actions Artifacts 참고)

## 리스크/메모
- (리뷰 포인트/주의사항)
" \
            --draft

이 워크플로에서 중요한 점은 Codex의 출력이 곧바로 PR 본문과 로그 링크로 연결되게 만드는 것입니다. PR을 열어 놓고 "설명은 나중에 채우자"가 되면 자동화의 가치가 급격히 떨어집니다.

변경 로그/테스트 로그를 "PR에서 한 번에" 보이게 만들기

클라우드 작업은 내가 자리에 없을 때도 돈다 보니, 완료 후에 '상황 파악 비용'이 생깁니다. 이 비용을 없애는 방법은 PR을 "대시보드"로 만드는 겁니다.

PR 본문: 사람이 읽는 변경 로그

PR 본문에는 코드 diff보다 먼저 읽히는 내용이 있어야 합니다. 추천 템플릿은 다음 순서입니다.

요약(사용자 영향/동작 변화)

변경 범위(어떤 모듈/파일이 핵심인지)

검증(실행한 테스트, 통과/실패, 특이사항)

리스크(호환성, 마이그레이션, 롤백)

Codex가 이 템플릿을 채우도록 강제하면, 리뷰어는 "파일 40개 변경" 같은 큰 PR도 훨씬 빨리 판단합니다.

Actions 로그/아티팩트: 기계가 남기는 증거

테스트가 길거나, 실패했을 때 재현이 까다로운 레포라면 로그는 필수입니다. 원칙은 단순합니다.

표준 출력은 Actions 로그에 남긴다.

길거나 구조화된 결과물(JUnit, 커버리지, 성능 리포트)은 아티팩트로 업로드한다.

실패 시에만 남겨야 하는 로그는 따로 분리한다(비용/노이즈 절감).

이렇게 하면 "Codex가 뭘 했는지"를 묻는 대화 자체가 사라집니다.

작업 병렬화: "한 번에 많이"가 아니라 "작게 나눠 동시에"

큰 작업을 클라우드에 맡긴다고 해서 PR 하나에 다 때려 넣으면, 다시 사람이 막힙니다. 병렬화는 결국 작업을 쪼개는 기술입니다.

1) 태스크 병렬화: 여러 PR로 팬아웃

예를 들어 '레거시 API 교체' 같은 작업은 보통 아래로 쪼갤 수 있습니다.

첫 PR: 타입/인터페이스 추가 + 기존 호출 래핑

둘째 PR: 호출부 일부 마이그레이션(모듈 A)

셋째 PR: 호출부 일부 마이그레이션(모듈 B)

넷째 PR: 레거시 제거 + 문서/릴리스 노트

각 PR은 10~20분짜리 태스크가 되고, Codex를 여러 러너(또는 여러 워크플로 실행)로 동시에 돌릴 수 있습니다. 나는 PR들을 순서대로 리뷰하며 "어떤 단계에서 멈출지"만 결정하면 됩니다.

2) 테스트 병렬화: CI 시간을 줄여 '피드백 대기'를 없애기

PR 자동화의 병목은 종종 테스트입니다. 테스트가 30분이면, 결국 리뷰어는 30분을 기다립니다.

가장 쉬운 해법은 GitHub Actions의 매트릭스 전략으로 테스트를 샤딩(sharding)하는 것입니다. 예를 들어 E2E 테스트 파일을 4개 조각으로 나눠 동시에 돌리면, 전체 대기 시간을 크게 줄일 수 있습니다.

이때 중요한 전제는 테스트가 서로 독립적이어야 한다는 점입니다(공유 DB, 공유 계정, 고정 포트 같은 것들이 병렬화를 방해합니다).

3) 리뷰 병렬화: "동시에 열어두되, 머지는 순서대로"

여러 PR을 동시에 만들어도 병합 순서가 꼬이면 사고가 납니다. 그래서 운영 규칙을 하나 둡니다.

의존성이 있는 PR은 모두 드래프트로 열고, '베이스 PR'이 머지되면 다음 PR을 rebase/업데이트한다.

리뷰는 동시에 해도 되지만, 머지는 순서(큐)로 한다.

Codex에게도 이 규칙을 명시하면, 충돌 해결 비용이 크게 줄어듭니다.

PR 리뷰 루프: 내가 하는 일은 "코드 작성"이 아니라 "승인/반려/재지시"

클라우드 태스크 방식으로 전환하면, 내 업무는 아래 순서로 재구성됩니다.

PR 요약을 읽고 의도가 맞는지 판단

테스트 로그(Checks/Artifacts)로 신뢰도를 판단

diff는 '위험한 부분'만 집중해서 확인

필요하면 Codex에 후속 태스크를 준다(예: 예외 처리, 경계 조건, 성능)

여기서 팁은 하나입니다. 수정 요청을 "리뷰 코멘트 여러 개"로 흩뿌리지 말고, 후속 태스크 한 개로 묶어라는 겁니다.

예를 들어 이렇게 정리합니다.

"다음 PR에서 처리할 것": 범위 밖이거나 리스크가 큰 것

"이번 PR에서 반드시": 안전/정확성/컴플라이언스에 직결되는 것

"코드 스타일": 자동 포매터/린터로 해결할 것

이 구조로 정리해 Codex에게 후속 태스크를 주면, PR은 빨리 닫히고 작업은 계속 앞으로 갑니다.

운영 체크리스트: 자동화가 커질수록 '기본 규칙'이 중요해진다

자동 PR이 팀에 안착하려면, 기술보다 규칙이 먼저입니다.

브랜치 보호: main에 직접 푸시 금지, PR 필수

드래프트 기본: 자동 생성 PR은 기본 드래프트(사람이 'Ready'로 전환)

라벨 규칙: automation, needs-review, risk:high 같은 라벨로 분류

리뷰어 지정: 코드오너/모듈 담당자를 자동 지정

자동 머지 범위: 의존성 업데이트처럼 안전한 것부터 제한적으로

로그 보존: 실패 로그/테스트 결과를 일정 기간 보관

이 체크리스트가 갖춰지면, 큰 작업을 클라우드에 맡기는 것이 불안이 아니라 '표준 운영'이 됩니다.

이제 당신의 역할은 분명해집니다. Codex가 클라우드에서 시간을 쓰는 동안, 나는 PR에서 결정만 내립니다. 다음 챕터에서는 이 흐름을 한 단계 더 나아가, GitHub Actions 안에서 codex exec를 CI/CD의 반복 업무(릴리스, 체인지로그, 버전 업데이트)에 직접 연결하는 방법을 다룹니다.