Jenkins·GitHub Actions 파이프라인에 AI 코드 리뷰 에이전트를 적용하는 방법

게임 프로젝트의 AI 코드 리뷰 에이전트는 사람 리뷰를 대체하는 도구가 아니라 Pull Request(PR)마다 반복되는 결함 탐지와 검토 준비를 자동화하는 CI 단계다. GitHub Actions 또는 Jenkins에서 변경 파일과 테스트 결과를 전달하고 에이전트의 결과를 PR 코멘트로 남기되 병합 차단은 검증된 규칙에만 적용하는 방식이 가장 안전하다.

AI 코드 리뷰 에이전트는 왜 게임 CI/CD에 필요한가?

게임 개발에서는 클라이언트, 서버, 빌드 스크립트, 데이터 변환기가 동시에 바뀐다. 특히 Unity C#, Unreal Engine C++, 셰이더, 라이브 서비스 API가 한 PR에 섞이면 리뷰어가 변경 범위를 빠르게 파악하기 어렵다.

AI 코드 리뷰 에이전트는 다음처럼 변경분 중심의 1차 검토를 맡는다.

검토 항목	사람이 최종 판단할 항목	AI 에이전트가 먼저 찾기 좋은 항목
크래시	실제 재현 가능성, 수정 우선순위	null 접근, 배열 범위 초과, 예외 누락
성능	프레임 타임 영향, 플랫폼별 측정	루프 안 할당, 매 프레임 탐색, 불필요한 LINQ
네트워크	게임 규칙과 동기화 정책	타임아웃 누락, 권한 검사 누락, 재시도 폭주
빌드	출시 영향과 롤백 결정	환경 변수 누락, 경로 의존성, 실패한 테스트
보안	위협 모델과 대응 수준	토큰 하드코딩, 로그의 개인정보·키 출력

핵심은 AI의 의견을 사실로 취급하지 않는 것이다. 에이전트는 변경된 코드의 위험 후보와 근거 위치를 제시하고 개발자와 리뷰어가 테스트·프로파일링·재현으로 확인한다.

Jenkins와 GitHub Actions 중 어디에 연결해야 할까?

새 PR 워크플로라면 GitHub Actions가 간단하다. 이미 Jenkins에서 Unity 배치 빌드, Unreal Automation Tool(UAT), 플랫폼별 서명 작업을 운영 중이라면 Jenkins 파이프라인에 추가하는 편이 중복이 적다.

기준	GitHub Actions	Jenkins
PR 이벤트 연결	`pull_request` 트리거로 바로 시작	GitHub 웹훅 또는 Multibranch Pipeline 설정 필요
비밀값 관리	GitHub Secrets, Environment	Credentials Binding 또는 외부 Secret Manager
대규모 게임 빌드	호스티드 러너의 시간·디스크 제한 확인 필요	자체 Windows/macOS 빌드 머신 활용에 유리
AI 리뷰 단계	YAML 한 파일로 구성 가능	Jenkinsfile의 stage로 추가 가능
권장 역할	빠른 PR 리뷰와 경량 검사	기존 빌드·패치 파이프라인 확장

둘을 함께 쓸 때는 역할을 분리한다. GitHub Actions는 PR diff 분석과 코멘트 게시를 맡고 Jenkins는 무거운 에디터 빌드와 패키징 결과를 상태 체크로 반환한다. 같은 AI 리뷰를 두 시스템에서 중복 실행할 이유는 없다.

AI 코드 리뷰 에이전트는 어떻게 구현할까?

1. PR 변경분과 검증 결과만 수집한다

전체 저장소를 매번 전달하면 비용과 잡음이 커진다. 기본 입력은 PR diff, 변경 파일 목록, 실패한 테스트 로그의 잘린 구간으로 제한한다. 예를 들어 Unity 프로젝트라면 Assets/, Packages/, ProjectSettings/ 변경을 구분해 맥락을 제공한다.

git diff --unified=20 origin/main...HEAD > pr.diff
git diff --name-only origin/main...HEAD > changed-files.txt

비밀값, 인증서, .env 파일, 배포 키가 포함된 경로는 AI 입력에서 제외해야 한다. 로그도 액세스 토큰, 계정 ID, IP 주소가 남을 수 있으므로 마스킹 단계를 둔다.

2. 결과를 구조화된 JSON으로 받는다

자유 형식 리뷰는 자동 처리와 품질 측정이 어렵다. 심각도, 파일, 줄 번호, 근거, 제안 수정안을 포함한 JSON 스키마를 요구한다.

{
  "findings": [
    {
      "severity": "high",
      "file": "Assets/Scripts/Combat/DamageSystem.cs",
      "line": 84,
      "title": "서버 권한 확인 없이 피해를 적용함",
      "reason": "클라이언트 입력값이 그대로 체력 계산에 사용됩니다.",
      "suggestion": "피해 적용을 서버 권한 경로로 제한하고 입력값 범위를 검증합니다."
    }
  ]
}

심각도는 critical, high, medium, low처럼 고정된 값으로 제한한다. 파일·줄 번호가 없는 의견, 변경분과 관계없는 일반론은 게시하지 않도록 후처리 규칙을 둔다.

3. PR 코멘트와 병합 규칙을 분리한다

초기에는 모든 결과를 정보성 PR 코멘트로 게시한다. 오탐률과 누락 사례를 기록한 뒤 토큰 노출이나 권한 검사 누락처럼 명확하고 재현 가능한 규칙만 병합 차단 조건으로 승격한다.

flowchart LR
  A[PR 생성 또는 업데이트] --> B[diff와 테스트 결과 수집]
  B --> C[비밀값 및 불필요 파일 제거]
  C --> D[AI 코드 리뷰 에이전트]
  D --> E[JSON 검증 및 중복 제거]
  E --> F[PR 코멘트 게시]
  E --> G{검증된 차단 규칙 위반?}
  G -->|예| H[CI 실패]
  G -->|아니오| I[정보성 리뷰 완료]

PR diff와 테스트 로그를 입력으로 받아 구조화된 리뷰 결과를 PR에 게시하는 AI 코드 리뷰 CI 파이프라인

GitHub Actions에서 PR AI 리뷰를 실행하는 예시

다음 예시는 PR이 열리거나 업데이트될 때 변경분을 만들고 내부 리뷰 스크립트를 실행하는 최소 구성이다. 실제 모델 호출은 조직의 승인된 API 게이트웨이 또는 리뷰 도구로 감싸고 API 키는 AI_REVIEW_API_KEY Secret으로만 주입한다.

name: AI PR Review

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

permissions:
  contents: read
  pull-requests: write

jobs:
  ai-review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Create pull request diff
        run: git diff --unified=20 ${{ github.event.pull_request.base.sha }} ${{ github.sha }} > pr.diff

      - name: Review changed code
        env:
          AI_REVIEW_API_KEY: ${{ secrets.AI_REVIEW_API_KEY }}
        run: node scripts/ai-review.mjs pr.diff > review.json

      - name: Publish review
        env:
          GH_TOKEN: ${{ github.token }}
        run: node scripts/publish-review.mjs review.json ${{ github.event.pull_request.number }}

pull_request_target는 포크 PR의 코드를 신뢰된 권한으로 실행할 수 있어 위험하다. 외부 기여자의 PR을 허용하는 저장소라면 pull_request에서 읽기 전용 분석만 수행하고 비밀값이 필요한 작업은 신뢰된 브랜치 또는 사람이 승인한 후속 워크플로로 분리한다.

Jenkins Pipeline에 AI 코드 리뷰 단계를 추가하는 방법

Jenkins에서는 기존 빌드 전에 가벼운 리뷰 단계를 넣는다. 크고 느린 Unity 또는 Unreal 빌드가 실패한 뒤에 리뷰를 돌리면 피드백이 늦어지기 때문이다.

pipeline {
  agent { label 'linux' }

  stages {
    stage('AI PR Review') {
      when { changeRequest() }
      steps {
        checkout scm
        sh 'git diff --unified=20 origin/${CHANGE_TARGET}...HEAD > pr.diff'
        withCredentials([string(credentialsId: 'ai-review-api-key', variable: 'AI_REVIEW_API_KEY')]) {
          sh 'node scripts/ai-review.mjs pr.diff > review.json'
        }
        sh 'node scripts/publish-review.mjs review.json ${CHANGE_ID}'
      }
    }

    stage('Game Build') {
      steps {
        sh './ci/build-game.sh'
      }
    }
  }
}

Jenkins 에이전트에 API 키를 파일로 남기지 말고 Credentials Binding을 사용한다. withCredentials 내부에서만 환경 변수로 노출하고 셸의 디버그 출력인 set -x는 끈다.

AI 리뷰의 오탐과 비용은 어떻게 관리할까?

AI 리뷰 품질은 모델 이름보다 입력 범위와 피드백 루프에 크게 좌우된다. 다음 지표를 PR 단위로 기록하면 병합 차단 여부를 판단할 수 있다.

지표	계산 방법	판단 기준 예시
유효 지적률	실제 수정 또는 결함 등록된 지적 수 / 전체 지적 수	낮으면 프롬프트·필터를 축소
오탐률	무관 또는 잘못된 지적 수 / 전체 지적 수	`high` 이상에서 특히 낮아야 함
리뷰 지연	PR 생성부터 첫 결과까지의 시간	개발자 피드백 주기보다 짧게 유지
비용/PR	모델 호출 비용 / PR 수	diff 크기 제한과 캐시 기준 검토
누락 사례	배포 후 발견된 결함 중 AI가 놓친 수	테스트 규칙과 프롬프트 보강

변경 줄 수가 N이고 입력 토큰 밀도를 d, 출력 토큰을 O라 하면 호출 규모는 대략 다음처럼 관리할 수 있다.

T \approx N \times d + O

대형 에셋 변경, 자동 생성 코드, Library/, Binaries/, DerivedDataCache/는 리뷰 대상에서 제외한다. 또한 같은 커밋 SHA에 대한 결과는 재실행하지 않으면 불필요한 호출을 줄일 수 있다.

게임 코드에서 우선 검토할 규칙은 무엇인가?

처음부터 모든 코드 품질 규칙을 맡기지 말고 출시 사고와 연결되는 좁은 규칙부터 시작한다.

권한과 입력 검증: 클라이언트가 전달한 재화, 피해량, 보상 ID를 서버에서 다시 검증하는지 확인한다.
크래시 경로: 씬 전환, 비동기 로딩 완료 전 접근, 네트워크 응답 실패 시 null·예외 처리가 있는지 확인한다.
프레임 타임 위험: Update()와 Tick()에서 반복되는 할당, 전체 오브젝트 탐색, 동기 I/O를 찾는다.
빌드·패치 위험: 주소 지정 에셋 키, 번들 이름, 버전 코드, 콘텐츠 매니페스트의 불일치를 확인한다.

AI 에이전트에는 “추측하지 말고 변경된 코드의 파일과 줄 번호를 인용하라”, “게임 규칙을 모르면 질문 또는 낮은 심각도로 표시하라” 같은 제약을 명시한다. 이 제약이 없으면 그럴듯하지만 검증하기 어려운 리뷰가 늘어난다.

자주 묻는 질문 (FAQ)

AI 코드 리뷰가 사람 코드 리뷰를 대체할 수 있나?

아니다. 게임 규칙, 설계 의도, 출시 위험의 최종 판단은 사람이 맡아야 한다. AI는 반복적인 위험 후보 탐지와 변경 요약에 적합하다.

AI 리뷰 결과를 바로 병합 차단 조건으로 써도 되나?

처음에는 권장하지 않는다. 정보성 코멘트로 오탐률을 측정한 뒤 토큰 노출처럼 판정이 명확한 항목만 차단 규칙으로 적용한다.

포크 PR에도 API 키를 전달해도 되나?

안 된다. 포크의 임의 코드는 비밀값이 주입된 러너에서 실행하면 안 된다. 읽기 전용 분석으로 제한하거나 신뢰된 후속 워크플로와 승인 절차를 사용한다.

정리

Jenkins와 GitHub Actions의 AI 코드 리뷰 에이전트는 PR diff, 테스트 결과, 고정된 JSON 결과 형식을 중심으로 작게 시작하는 것이 좋다. 먼저 코멘트 기반으로 유효 지적률과 오탐률을 확인하고 게임 출시 사고와 직접 연결되는 검증 규칙만 CI 차단 조건으로 올리면 리뷰 속도와 안전성을 함께 높일 수 있다.