Antigravity 에게 깃허브 권한 주기

최근 업무를 진행하면서 클로드 코드 또는 안티그래비티와 같은 코딩 에이전트에게 직접 깃허브 이슈 내용을 파악하고 관련 작업에 대한 댓글을 달도록 요청해보고 있어요. 이 과정에서 알게된 몇가지 사실에 대해서 공유하고자해요.

먼저, 깃허브 이슈 또는 PR에 대한 작업을 요청할 때 사용할 수 있는 도구로는 GitHub MCP Server와 GitHub CLI(gh)가 있습니다. 코딩 에이전트에게 이 도구들을 설정하고 사용하는 과정에서 겪게 되는 주요 고려 사항은 권한 설정과 기능 지원 여부입니다.

Github Official MCP Server

우선 Github MCP Server는 Fine-grained PAT 를 사용할 경우 조직(Org) 리포지토리 접근 권한이 없는 문제가 자주 발생합니다. 이건 클래식 토큰으로 발급해서 사용하면 해결되지만 이슈에 댓글은 등록할 수 있는데 수정은 불가능하다는 이상한 문제가 있어요.

댓글 수정이 불가능한 점은 생각보다 큰 불편함을 초래하므로, 저는 GitHub CLI만 설치하여 사용하고 있습니다.

Fine-grained PAT 설정 스코프

코딩 에이전트가 이슈와 PR을 원활하게 관리하기 위해서는 다음과 같은 최소 권한이 설정된 Fine-grained PAT가 필요합니다.

Github CLI(gh)

GitHub CLI는 명령줄 기반 도구이기 때문에 코딩 에이전트가 활용하기에 매우 적합합니다. 토큰 권한 설정은 MCP Server와 유사하므로 설정에 큰 어려움은 없을 것입니다. 에이전트가 이슈와 PR 작업을 수행할 때 주로 사용하게 되는 주요 명령어들은 다음과 같습니다.

• gh issue create : 이슈 생성
• gh issue comment : 이슈에 댓글 달기
• gh issue view : 이슈 조회
• gh issue edit : 이슈 수정
• gh issue develop : 이슈 브랜치 연결
• gh pr create : PR 생성
• gh pr comment : PR 에 댓글 달기
• gh pr view : PR 조회
• gh pr edit : PR 수정

gh 인증 상태 확인

에이전트가 정상적으로 GitHub에 로그인되어 있는지 확인하려면 gh auth status 명령어를 사용합니다. 정상적으로 연동되었다면 아래와 같이 로그인된 계정 정보와 토큰 유형을 확인할 수 있습니다.

Github CLI 로 하지 못하는 것들

gh 명령어를 사용해서 아직은 불가능한 기능들을 알아볼게요.

하위 이슈(Sub-issue) 연결 기능 부재

GitHub 이슈를 생성할 때 종종 하위 이슈로 구성하여 상위 이슈에서 쉽게 참조할 수 있도록 관리해야 하는 경우가 많습니다. 하지만 gh issue create 명령어를 사용할 때 상위(parent) 이슈를 직접 지정하는 옵션은 아직 제공되지 않습니다. 현재 관련 기능이 개발 중이므로, 지금은 yahsan2/gh-sub-issue와 같은 확장 프로그램을 설치하고 에이전트 지침에 이를 포함해야 합니다.

gh extension install yahsan2/gh-sub-issue
gh sub-issue add <상위-이슈-번호> <하위-이슈-번호>

Development 이슈 연결 기능 부재

gh 명령어로 PR을 수정할 때 Development 이슈를 연결하는 옵션 또한 부재합니다. 따라서 코딩 에이전트가 Resolves #이슈번호와 같은 키워드를 PR 본문에 포함하도록 가이드해야 합니다. 저는 에이전트 지침에 본문 하단에 작업자 정보와 사용 모델을 명시하도록 설정하여 관리하고 있습니다.

깃허브 관련 작업에 대한 지침

결국은 코딩 에이전트에게 깃허브 관련 작업에 대한 지침을 추가하는게 좋아요. 이슈는 어떤 구조로 생성하는지, 이슈 댓글을 작성할 때 관련 작업에 따라 누구를 멘션해야하는지, PR 생성 시 Draft PR 로 만들게하고, 어떤 템플릿 구조로 만들어져야 하는지를 기재했어요.

### 깃허브 작업 지침 (GitHub Operations)

- **이슈 관리 (Issues)**:
    - 하위 이슈(Sub-issue) 관리가 필요한 경우 `yahsan2/gh-sub-issue` 확장을 사용합니다.
    - 상위 이슈에 연결 시 `gh sub-issue add <상위-번호> <하위-번호>`를 실행합니다. (미설치 시 `gh extension install` 선행)
- **풀 리퀘스트 (Pull Requests)**:
    - PR 생성 시 본문에 `Resolves #<이슈-번호>` 또는 `Closes #<이슈-번호>`를 포함하여 이슈를 자동으로 연결하고 닫히도록 합니다.
    - 최초 PR을 생성할 때에는 `gh pr create --draft`를 사용하여 Draft PR로 생성합니다.
    - PR 본문 하단에는 작업을 수행한 에이전트 이름과 사용된 모델 정보를 기재합니다.
- **댓글 및 소통 (Communication)**:
    - 이슈나 PR에 댓글을 남길 때는 최대한 간결한 말투로 작업의 목적과 변경 사항을 요약하여 기재합니다. 장황한 설명이나 불필요한 수식어 사용을 금지합니다.
    - 이슈에 댓글을 작성할 때는 이슈 작성자(@author)를 멘션합니다.
    - PR에 댓글을 작성할 때는 리뷰어(@reviewers)를 멘션합니다.