누락된 환경 변수를 확인하기 위해 AI 생성 PR을 리뷰하는 방법

AI 보조 PR(Pull Request)은 종종 애플리케이션 코드, 배포 설정(deployment config), 그리고 CI를 동시에 변경합니다. 이는 유용하지만, 리뷰 시 놓치기 쉬운 지루한 실패 모드(failure mode)를 만들어냅니다. 바로 PR이 새로운 환경 변수(environment variable)를 사용하기 시작했지만, .env.example 또는 .env.dist 파일은 업데이트되지 않는 경우입니다. 배포가 실패하는 데 있어 실제 비밀 값(raw secret values)이 유출될 필요는 없습니다. 문제는 메타데이터 드리프트(metadata drift)입니다. 즉, 리포지토리가 이제 선언된 환경 계약(environment contract)에 언급되지 않은 변수에 의존하게 되는 것입니다. 이러한 종류의 PR에 대해 제가 사용하는 리뷰 흐름은 다음과 같습니다.

시나리오: AI 에이전트가 합리적으로 보이는 PR을 생성합니다. GitHub Actions에 Stripe 기반의 체크아웃 배포 단계를 추가하고, Docker Compose에 Redis 기반의 워커(worker)를 추가하며, 런타임 코드 경로를 업데이트하지만, .env.example을 업데이트하는 것은 잊어버렸습니다. 개별 변경 사항이 작아 보이기 때문에 디프(diff)는 일반적인 코드 리뷰를 통과할 수도 있습니다.

1. 환경 계약(env contract)부터 시작하기
   템플릿 파일은 향후 기여자(contributors)와 리뷰어가 보게 될 계약입니다:
   NEXT_PUBLIC_APP_URL=https://example.com
   DATABASE_URL=
   이것은 프로젝트가 NEXT_PUBLIC_APP_URL과 DATABASE_URL을 기대한다는 것을 의미합니다. Stripe나 Redis에 대해서는 아무것도 말하지 않습니다.

2. 소스 코드뿐만 아니라 CI 및 배포 설정 확인하기
   워크플로우는 이제 새로운 비밀 값(secret)을 참조합니다:
   env :
   DATABASE_URL : ${{ secrets.DATABASE_URL }}
   STRIPE_SECRET_KEY : ${{ secrets.STRIPE_SECRET_KEY }}

Docker Compose 또한 Redis를 기대합니다:
services :
web :
environment :
DATABASE_URL : ${DATABASE_URL}
REDIS_URL : ${REDIS_URL}
worker :
environment :
REDIS_URL : ${REDIS_URL}

두 변경 사항 모두 정상적입니다. 버그는 STRIPE_SECRET_KEY와 REDIS_URL이 환경 템플릿에 추가되지 않은 채로 필수 배포 입력값(deployment inputs)이 되었다는 점입니다.

3. 메타데이터 전용 드리프트 체크 실행하기
   Secret Coverage 리포지토리에서, 다음 피스처(fixtures)들은 두 가지 리뷰 발견 사항을 모델링합니다:
   pnpm scan -- --path examples/demos/github-actions-missing-secret --ci
   pnpm scan -- --path examples/demos/docker-compose-missing-redis-url --ci

배포된 패키지를 사용하는 소비자 리포지토리(consumer repo)의 경우:
pnpm dlx @leviro-ai/secret-coverage scan --path .

--ci 이 체크는 CI/CD, Docker 및 설정 파일(config files)에서 참조되는 변수 이름과 환경 변수 템플릿(env templates)에 선언된 변수 이름을 비교합니다. 프로덕션(production) 비밀 값(secret values)은 필요하지 않습니다.

4. 발견 사항을 리뷰 코멘트처럼 읽기

GitHub Actions 드리프트(drift):

Critical

• STRIPE_SECRET_KEY — STRIPE_SECRET_KEY가 .github/workflows/deploy.yml에서 사용되고 있지만, 환경 변수 템플릿에는 누락되었습니다.
  • 컨텍스트(Context): .github/workflows/deploy.yml · missing-from-template
  • 수정 방법(Fix): 환경 변수 템플릿에 STRIPE_SECRET_KEY=를 추가하고, 배포 환경(deployment environment)에서 해당 값을 설정하세요.

Docker Compose 드리프트(drift):

Critical

• REDIS_URL — REDIS_URL이 docker-compose.yml에서 사용되고 있지만, 환경 변수 템플릿에는 누락되었습니다.
  • 컨텍스트(Context): docker-compose.yml · missing-from-template
  • 수정 방법(Fix): 환경 변수 템플릿에 REDIS_URL=를 추가하고, 배포 환경(deployment environment)에서 해당 값을 설정하세요.

이는 막연한 배포 위험을 지적하는 것이 아니라, 누락된 계약(contract) 업데이트를 지적하기 때문에 매우 유용한 PR 리뷰 신호가 됩니다.

5. 가장 작고 안전한 수정을 요청하기

수정 사항은 대개 아주 작은 템플릿 업데이트입니다:
NEXT_PUBLIC_APP_URL=https://example.com
DATABASE_URL=
STRIPE_SECRET_KEY=
REDIS_URL=

실제 값은 여전히 배포 플랫폼(deployment platform)에 있어야 합니다: CI/CD 비밀 값을 위한 GitHub Actions secrets, 서비스 변수를 위한 Docker 또는 Compose 런타임 환경(runtime environment), 그리고 관련이 있는 경우 Vercel, CircleCI 또는 다른 플랫폼의 환경 설정(environment settings) 등이 해당됩니다. .env.example, 문서(docs), 스크린샷 또는 리뷰 코멘트에 가공되지 않은(raw) 비밀 값을 넣지 마세요.

6. 머지(merge) 전 체크 추가하기

작은 CI 체크를 통해 배포 작업(deploy job)이 불일치를 발견하기 전에 PR을 실패 처리할 수 있습니다:

name : secret-coverage
on : pull_request
: push
: branches : [ main ]
jobs :
env-contract :
runs-on : ubuntu-latest
steps :
- uses : actions/checkout@v6
- uses : actions/setup-node@v6
with :
node-version : 20
- run : pnpm dlx @leviro-ai/secret-coverage scan --path .

--ci PR 리뷰 체크리스트
AI가 지원하는 PR이 배포 설정(deployment config), CI, Docker, 워커(workers) 또는 프레임워크 런타임 설정(framework runtime config)을 수정할 때 다음 사항을 확인하세요:

• PR이 새로운 process.env.NAME, ${NAME}, ${{ secrets.NAME }} 또는 CI 환경 변수(env) 참조를 추가했는가?
• 모든 새로운 필수 변수가 .env.example, .env.dist 또는 선택된 템플릿 파일에 선언되었는가?
• 데모/문서(demo/docs) 출력물이 실제 비밀 값(raw secret values) 없이 메타데이터(metadata)만 포함하고 있는가?
• CI 체크가 배포(deploy) 전에 실행되는가?
• 발견된 내용이 기여자(contributor)에게 어떤 템플릿 항목을 추가해야 하는지 알려주는가?

Secret Coverage는 이 체크를 위해 제가 사용하고 있는 로컬 우선(local-first) 도구입니다. 이 도구는 결정론적(deterministic)이며, 메타데이터만 다루고, 클라우드 계정이 필요하지 않습니다.

링크:
GitHub: https://github.com/leviro-ai/secret-coverage
npm: https://www.npmjs.com/package/@leviro-ai/secret-coverage
AI 에이전트 PR 워크스루 (AI-agent PR walkthrough): https://github.com/leviro-ai/secret-coverage/blob/main/docs/articles/ai-agent-pr-env-review-walkthrough.md
GitHub Actions 데모: https://github.com/leviro-ai/secret-coverage/tree/main/examples/demos/github-actions-missing-secret
Docker Compose 데모: https://github.com/leviro-ai/secret-coverage/tree/main/examples/demos/docker-compose-missing-redis-url