run-gemini-cli

개요

run-gemini-cli는 Gemini CLI를 통해 Gemini를 개발 워크플로우에 통합하는 GitHub Action입니다. 이는 중요한 일상적인 코딩 작업을 위한 자율 에이전트이자, 작업을 빠르게 위임할 수 있는 주문형 협력자 역할을 합니다.

GitHub 저장소 내에서 Gemini와 대화형으로(예: @gemini-cli 이 이슈 수정) GitHub Pull Request 리뷰 수행, 이슈 분류, 코드 분석 및 수정 등을 수행하는 데 사용합니다.

• run-gemini-cli
  • 개요
  • 기능
  • 빠른 시작
    • 1. Gemini API 키 받기
    • 2. GitHub Secret으로 추가
    • 3. .gitignore 업데이트
    • 4. 워크플로우 선택
    • 5. 사용해 보세요!
  • 워크플로우
    • Gemini Dispatch
    • Issue Triage
    • Pull Request Review
    • Gemini CLI Assistant
  • 구성
    • 입력값
    • 출력값
    • 저장소 변수
    • 시크릿
  • 인증
    • Google 인증
    • GitHub 인증
  • 관측 가능성
  • 확장 기능
  • 모범 사례
  • 커스터마이징
  • 기여

기능

• 자동화: 이벤트(예: 이슈 열림) 또는 일정(예: 야간)에 따라 워크플로우 트리거.
• 주문형 협업: 이슈 및 Pull Request 댓글에서 Gemini CLI를 멘션하여 워크플로우 트리거 (예: @gemini-cli /review).
• 도구를 통한 확장 가능: Gemini 모델의 도구 호출 기능을 활용하여 GitHub CLI (gh)와 같은 다른 CLI와 상호 작용.
• 커스터마이징 가능: 저장소에 GEMINI.md 파일을 사용하여 Gemini CLI에 프로젝트별 지침 및 컨텍스트 제공.

빠른 시작

몇 분 만에 저장소에서 Gemini CLI를 시작하세요:

1. Gemini API 키 받기

Google AI Studio에서 API 키를 받으세요. 관대한 무료 할당량이 제공됩니다.

2. GitHub Secret으로 추가

API 키를 GEMINI_API_KEY라는 이름의 시크릿으로 저장소에 저장하세요:

• 저장소의 Settings > Secrets and variables > Actions로 이동
• New repository secret 클릭
• Name: GEMINI_API_KEY, Value: API 키 입력

3. .gitignore 업데이트

.gitignore 파일에 다음 항목을 추가하세요:

# gemini-cli 설정
.gemini/

# GitHub App 자격 증명
gha-creds-*.json

4. 워크플로우 선택

워크플로우 설정에는 두 가지 옵션이 있습니다:

옵션 A: setup 명령 사용 (권장)

1. 터미널에서 Gemini CLI 시작:

   root@kitploit:~

   gemini
   

2. 터미널의 Gemini CLI에서 다음 입력:

   root@kitploit:~

   /setup-github
   

옵션 B: 수동으로 워크플로우 복사

1. examples/workflows 디렉토리에서 사전 빌드된 워크플로우를 저장소의 .github/workflows 디렉토리로 복사합니다. 참고: gemini-dispatch.yml 워크플로우도 복사해야 워크플로우가 실행되도록 트리거됩니다.

5. 사용해 보세요!

Pull Request 리뷰:

• 저장소에서 Pull Request를 열고 자동 리뷰를 기다립니다.
• 기존 Pull Request에 @gemini-cli /review 댓글을 달아 수동으로 리뷰를 트리거합니다.

Issue Triage (이슈 분류):

• 이슈를 열고 자동 분류를 기다립니다.
• 기존 이슈에 @gemini-cli /triage 댓글을 달아 수동으로 분류를 트리거합니다.

일반 AI 지원:

• 모든 이슈 또는 Pull Request에서 @gemini-cli 뒤에 요청을 멘션합니다.
• 예시:
  • @gemini-cli 이 코드 변경 설명해줘
  • @gemini-cli 이 함수에 대한 개선 제안
  • @gemini-cli 이 오류 디버깅 도와줘
  • @gemini-cli 이 컴포넌트에 대한 단위 테스트 작성해줘

워크플로우

이 액션은 다양한 사용 사례를 위한 여러 사전 빌드된 워크플로우를 제공합니다. 각 워크플로우는 저장소의 .github/workflows 디렉토리에 복사하여 필요에 따라 커스터마이징할 수 있습니다.

Gemini Dispatch

이 워크플로우는 Gemini CLI의 중앙 디스패처 역할을 하며, 트리거 이벤트와 댓글에 제공된 명령에 따라 적절한 워크플로우로 요청을 라우팅합니다. 디스패치 워크플로우 설정에 대한 자세한 가이드는 Gemini Dispatch 워크플로우 문서를 참조하세요.

Issue Triage

이 액션은 GitHub Issues를 자동으로 또는 일정에 따라 분류하는 데 사용할 수 있습니다. 이슈 분류 시스템 설정에 대한 자세한 가이드는 GitHub Issue Triage 워크플로우 문서를 참조하세요.

Pull Request Review

이 액션은 Pull Request가 열릴 때 자동으로 리뷰하는 데 사용할 수 있습니다. Pull Request 리뷰 시스템 설정에 대한 자세한 가이드는 GitHub PR Review 워크플로우 문서를 참조하세요.

Gemini CLI Assistant

이러한 유형의 액션은 Pull Request 및 이슈 내에서 범용 대화형 Gemini AI 어시스턴트를 호출하여 다양한 작업을 수행하는 데 사용할 수 있습니다. 일반 목적 Gemini CLI 워크플로우 설정에 대한 자세한 가이드는 Gemini Assistant 워크플로우 문서를 참조하세요.

구성

입력값

• gcp_location: (선택 사항) Google Cloud 위치.

• gcp_project_id: (선택 사항) Google Cloud 프로젝트 ID.

• gcp_service_account: (선택 사항) Google Cloud 서비스 계정 이메일.

• gcp_workload_identity_provider: (선택 사항) Google Cloud Workload Identity Provider.

• gcp_token_format: (선택 사항, 기본값: access_token) 인증을 위한 토큰 형식. "access_token"으로 설정하면 액세스 토큰을 생성합니다(서비스 계정 필요). 빈 문자열로 설정하면 직접 WIF를 사용합니다. "access_token" 또는 "id_token"이 될 수 있습니다.

• gcp_access_token_scopes: (선택 사항, 기본값: https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/userinfo.profile) token_format이 "access_token"인 경우의 액세스 토큰 범위. 쉼표로 구분된 OAuth 2.0 범위 목록.

출력값

• summary: Gemini CLI 실행의 요약된 출력.

• error: Gemini CLI 실행의 오류 출력 (있는 경우).

저장소 변수

다음 값을 저장소 변수로 설정하여 모든 워크플로우에서 재사용하는 것을 권장합니다. 또는 개별 워크플로우의 액션 입력값으로 인라인 설정하거나 저장소 수준 값을 재정의할 수 있습니다.

[!WARNING] DEBUG 환경 변수를 사용하지 마십시오. 이 변수는 Gemini CLI가 노드 디버거가 연결될 때까지 대기하면서 중단되게 만듭니다.

저장소 변수를 추가하려면:

1. 저장소의 Settings > Secrets and variables > Actions > New variable로 이동합니다.
2. 변수 이름과 값을 입력합니다.
3. 저장합니다.

저장소 변수에 대한 자세한 내용은 GitHub 변수 문서를 참조하세요.

시크릿

저장소에 다음 시크릿을 설정할 수 있습니다:

시크릿을 추가하려면:

1. 저장소의 Settings > Secrets and variables > Actions > New repository secret으로 이동합니다.
2. 시크릿 이름과 값을 입력합니다.
3. 저장합니다.

자세한 내용은 암호화된 시크릿 생성 및 사용에 대한 공식 GitHub 문서를 참조하세요.

인증

이 액션은 Google 서비스(Gemini AI용)와 GitHub API 모두에 대한 인증이 필요합니다.

Google 인증

사용 사례에 가장 적합한 인증 방법을 선택하세요:

1. Gemini API Key: Google Cloud 통합이 필요하지 않은 프로젝트에 가장 간단한 방법
2. Workload Identity Federation: Google Cloud 서비스에 인증하는 가장 안전한 방법

GitHub 인증

두 가지 방법으로 GitHub에 인증할 수 있습니다:

1. 기본 GITHUB_TOKEN: 간단한 사용 사례의 경우, 액션은 워크플로우에서 제공하는 기본 GITHUB_TOKEN을 사용할 수 있습니다.
2. 사용자 지정 GitHub App (권장): 가장 안전하고 유연한 인증을 위해 사용자 지정 GitHub App을 만드는 것을 권장합니다.

Google 및 GitHub 인증에 대한 자세한 설정 지침은 인증 문서를 참조하세요.

관측 가능성

이 액션은 원격 측정 데이터(추적, 메트릭, 로그)를 사용자 Google Cloud 프로젝트로 보내도록 구성할 수 있습니다. 이를 통해 워크플로우 내에서 Gemini CLI의 성능과 동작을 모니터링하여 디버깅 및 최적화에 유용한 통찰력을 제공합니다.

관측 가능성 설정 및 구성에 대한 자세한 지침은 관측 가능성 문서를 참조하세요.

확장 기능

Gemini CLI는 확장 기능을 통해 추가 기능으로 확장할 수 있습니다. 이러한 확장 기능은 GitHub 저장소의 소스에서 설치됩니다.

확장 기능 설정 및 구성에 대한 자세한 지침은 확장 기능 문서를 참조하세요.

모범 사례

자동화된 워크플로우의 보안, 신뢰성 및 효율성을 보장하려면 모범 사례를 따르는 것이 좋습니다. 이러한 지침은 저장소 보안, 워크플로우 구성, 모니터링 등 주요 영역을 다룹니다.

주요 권장 사항은 다음과 같습니다:

• 저장소 보안: 브랜치 및 태그 보호 구현, Pull Request 승인자 제한.
• 워크플로우 구성: Google Cloud에 대한 안전한 인증을 위해 Workload Identity Federation 사용, 시크릿 효과적으로 관리, 예기치 않은 변경을 방지하기 위해 액션 버전 고정.
• 모니터링 및 감사: 액션 로그 정기적으로 검토, 성능 및 동작에 대한 심층 인사이트를 위해 OpenTelemetry 활성화.

저장소 및 워크플로우 보안을 위한 종합 가이드는 모범 사례 문서를 참조하세요.

커스터마이징

저장소 루트에 GEMINI.md 파일을 생성하여 Gemini CLI에 프로젝트별 컨텍스트 및 지침을 제공합니다. 이는 특정 저장소에 대해 모델이 따라야 할 코딩 규칙, 아키텍처 패턴 또는 기타 지침을 정의하는 데 유용합니다.

기여

기여를 환영합니다! 시작하는 방법에 대한 자세한 내용은 Gemini CLI 기여 가이드를 확인하세요.