AI Native Notes
Gemini CLI로 돌아가기
Gemini CLI중급9분 소요

Gemini CLI Headless Automation

스크립트, CI 파이프라인(GitHub Actions), 내부 도구에서 Gemini CLI를 구조화된 출력으로 자동화하는 방법

자동화headlessjsonci-cdgithub-actions

공식 레퍼런스: Headless mode · Authentication · Token caching · Sandboxing

학습 경로

  1. Gemini CLI 시작하기 — 설치, 인증, 메모리 기초
  2. 100만 토큰의 장점 — 전체 코드베이스로 작업하기 — 저장소 단위 분석을 낭비 없이
  3. Gemini Extensions & MCP — 커스텀 워크플로 만들기 — 명령, MCP, 스킬 패키징
  4. Gemini CLI MCP 연동 — 외부 도구와 데이터 연결하기
  5. Trusted Folders, Sandboxing, 그리고 Restore — 신뢰, 격리, 복구
  6. Gemini Task Decomposition — 복잡한 작업을 성공적으로 완수하기
  7. Gemini CLI Headless Automation — 스크립트, CI, 구조화 출력 ← 현재 문서
  8. Gemini Git Worktrees — 병렬 작업 최적화
  9. 서브 에이전트와 스킬 오케스트레이션 — 위임과 전문가 워크플로
  10. GEMINI.md Mastery — 계층적 컨텍스트 설계
  11. Gemini 첫날 안전 루프
  12. Multi-Agent Orchestration — 서브 에이전트와 스킬 조합
  13. Gemini 주간 단위 딜리버리 플레이북
  14. Gemini GitHub Actions — CI 자동화와 리뷰
  15. Gemini 고위험 변경 통제 모델
  16. Gemini Effective Prompting — 100만 토큰을 지배하는 프롬프팅
  17. Gemini 운영 매뉴얼 — 팀 단위 CLI 딜리버리 리듬
  18. Gemini Hooks Automation — 로컬 자동화의 방패
  19. Gemini 사고 복구 플레이북
  20. Mid-size Refactor Playbook — 중규모 리팩터링
  21. Gemini 사고 후 하드닝 루프
  22. Gemini 카오스 복원력 드릴
  23. Human-Agent Handoffs — 인간과 AI의 릴레이
  24. Ralph Persistence Loops — 끝까지 물고 늘어지는 자가 치유
  25. Gemini 복원력 지표와 SLO
  26. Release Readiness Automation — 배포 자동화
  27. ADR Automation — 아키텍처 결정 기록 자동화

이 문서에서 참고한 공식 문서

  • headless mode 진입 조건과 출력 포맷 — Headless mode
  • 비대화형 자동화에 권장되는 인증 방식 — Authentication
  • API key / Vertex 인증이 비용 구조를 바꾸는 이유 — Token caching

headless mode는 Gemini CLI를 "대화"에서 "인프라"로 바꾼다

대화형 세션은 탐색과 설계에 좋습니다. 하지만 Gemini CLI를 진짜 팀 도구로 만드는 순간은 headless mode에 들어갈 때입니다.

이 모드가 빛나는 곳은 명확합니다.

  • CI에서 콘텐츠 QA 돌리기
  • PR / commit 리뷰 자동화
  • release note 초안 생성
  • nightly drift / broken link 점검
  • 에디터 확장이나 셸 스크립트에서 구조화된 출력 받기

공식 문서는 headless mode를 “터미널 UI 없이 text / JSON / JSONL을 반환하는 비대화형 실행”으로 설명합니다. 즉 사람이 보조로 쓰는 모드가 아니라 파이프라인의 일부로 쓰는 모드입니다.

자동화에서는 프롬프트보다 출력 계약이 더 중요하다

자동화에서 흔한 실수는 프롬프트를 아름답게 쓰는 데만 집중하고, 다른 프로그램이 그 결과를 어떻게 소비할지는 설계하지 않는 것입니다.

자동화 프롬프트는 아래 네 가지가 먼저 보장되어야 합니다.

  1. 입력 범위 — 어떤 파일 / 디렉터리를 읽을 것인가?
  2. 출력 스키마 — 어떤 key / section이 반드시 있어야 하는가?
  3. 실패 규칙 — 증거가 부족하면 어떻게 반환할 것인가?
  4. 사람 검토 지점 — 최종 결과인가, 초안인가?

좋은 자동화 프롬프트는 조금 지루해 보일 수 있습니다. 그게 오히려 장점입니다.

"전체를 보고 중요한 걸 말해줘"는 자동화 프롬프트가 아니다

나쁜 예:

저장소 전체를 리뷰하고 중요한 걸 말해줘.

더 좋은 예:

@content @messages
ko, en, es Gemini CLI 글을 비교해.
아래 key를 가진 JSON으로 반환해:
- missingSlugs
- frontmatterDrift
- brokenRelativeLinks
- suggestedFixes
근거가 없으면 해당 key는 빈 배열로 반환해.

후자는 파싱, diff, 재현, 회귀 검증이 훨씬 쉽습니다.

json과 jsonl은 쓰임새가 다르다

둘 다 구조화 출력이지만 목적이 다릅니다.

--output-format json

최종 결과를 기계가 읽게 할 때 좋습니다.

  • CI artifact 저장
  • 후속 스크립트가 .response를 읽는 경우
  • 검토 리포트 생성
  • 콘텐츠 감사 결과 저장

--output-format jsonl

이벤트 스트림 자체가 필요할 때 좋습니다.

  • tool trace 수집
  • 중간 진행 상황 표시
  • custom UI wrapper 연동
  • 자동화가 왜 이상하게 동작했는지 디버깅

확신이 없으면 먼저 json으로 시작하세요. 스트림 단위 분석이 필요해질 때 jsonl로 넘어가면 됩니다.

비대화형 인증은 편의가 아니라 아키텍처 선택이다

headless mode에서는 브라우저 로그인보다는 아래 방식이 권장됩니다.

  • GEMINI_API_KEY
  • Vertex AI 인증

이건 단순히 로그인 수단이 아니라 비용 구조와도 연결됩니다. 공식 문서가 설명하듯 API key / Vertex 기반 인증은 token caching을 활용할 수 있어서, 같은 저장소를 반복 분석하는 CI 파이프라인의 비용과 지연 시간을 크게 줄일 수 있습니다.

즉 좋은 headless 파이프라인은 보통 다음 조합입니다.

  • 결정적인 프롬프트
  • 좁고 안정된 입력 범위
  • API key 또는 Vertex 인증
  • 구조화된 출력

이 저장소에서 바로 쓸 만한 자동화 패턴

1) locale parity 점검

gemini -p "@content ko, en, es의 Gemini CLI 글에서 missing slug와 frontmatter drift를 찾아 JSON으로 반환해" --output-format json

2) MDX 품질 리뷰

gemini -p "@content/en MDX 파일의 약한 description, 반복 예시, broken relative link를 찾아 JSON으로 정리해" --output-format json

3) release note 초안 생성

gemini -p "@git diff --staged 현재 staged 변경을 기준으로 headings, bullets, risks를 포함한 릴리즈 노트를 markdown으로 작성해" \
  --output-format text

이 세 가지의 공통점은 사람이 마지막으로 검토하기 쉽다는 점입니다.

셸 실행이 섞이면 sandbox와 같이 보자

headless mode가 구조를 준다면, sandbox는 격리를 줍니다. 자동화가 셸 실행이나 설치를 포함한다면 둘을 같이 보는 편이 안전합니다.

특히 아래 상황에서 유용합니다.

  • 의존성 설치가 포함될 때
  • 제3자 저장소나 사용자 생성 코드가 대상일 때
  • 스크립트가 임의 명령을 실행할 수 있을 때
  • 처음 만드는 자동화 체인을 검증할 때

즉 headless가 "파이프라인화"라면 sandbox는 "피해 범위 제한"입니다.

GitHub Actions도 처음엔 review-first가 좋다

실무에서 무난한 CI 흐름은 보통 이렇습니다.

  1. 저장소 checkout
  2. 입력 범위를 최대한 좁힘
  3. Gemini를 JSON 모드로 실행
  4. 결과를 annotation / artifact / 요약으로 변환
  5. 영향이 큰 작업은 반드시 사람 승인 유지

초기 자동화의 핵심은 auto-merge가 아니라 사람 검토 전 단계의 기계적인 정리입니다.

headless mode를 오래 건강하게 쓰는 규칙

  • 프롬프트를 결정적으로 유지하기
  • 입력 범위를 최소화하기
  • 출력 스키마를 명시하기
  • Gemini 결과를 최종 권위가 아니라 draft / evidence로 다루기
  • 실패 결과도 artifact로 남기기
  • 대화형에서 검증된 워크플로만 CI로 승격하기

이 원칙을 지키면 headless mode는 믿을 수 있는 팀 도구가 됩니다. 그렇지 않으면 “가끔 신기한 JSON을 뱉는 블랙박스”가 되기 쉽습니다.

다음에 읽으면 좋은 글

연결된 가이드