1. Fine-grained PAT
GitHub 공식 문서 기준으로도 가능하면 fine-grained PAT를 권장한다.
Classic PAT는 더 넓은 권한을 갖기 쉬워 보안상 불리하다.
Fine-grained PAT는 특정 owner, 특정 repo만 선택하고, Contents / Pull requests / Actions처럼 권한을 세부적으로 나눠서 줄 수 있어서 더 안전하다.
Classic PAT는 repo, workflow 같은 넓은 scope 단위라서 권한이 쉽게 과해지고, 여러 저장소에 광범위하게 영향을 줄 수 있다.
그래서 새로 만들 토큰이면 fine-grained PAT를 우선 쓰고, 오래된 도구 호환성 때문에 fine-grained가 안 될 때만 classic PAT를 고려하면 된다.
2. AI Agent 개발 작업용 최소 권한
| 항목 | 권한 권장값 | 이유 / 사용 목적 | 비고 |
|---|---|---|---|
| Resource owner | 개인 계정 또는 작업할 organization | App 설치 대상을 결정 | 실제 작업 대상 계정/조직에 맞춰 선택 |
| Repository access | Only select repositories | 필요한 저장소에만 접근하도록 제한 | 최소 권한 원칙 |
| Repository selection | 작업할 repo만 선택 | 불필요한 저장소 접근 방지 | 예: 특정 서비스 repo만 체크 |
| Metadata | Read | repo 기본 조회, 브랜치/PR/파일 정보 조회에 필요 | 보통 자동 포함되거나 사실상 필수 |
| Contents | Read and write | clone, branch 생성, 파일 수정, commit, push에 필요 | 코드 변경 작업이 있으면 필수 |
| Pull requests | Read and write | PR 생성, 수정, 리뷰 관련 작업에 필요 | PR 자동 생성/업데이트 시 필요 |
| Issues | Read and write (필요 시만) | 이슈 연결, 댓글 작성, 상태 관리가 필요한 경우 | 이슈를 안 건드리면 꺼도 됨 |
| Actions | Read | CI 상태/체크 결과 조회용 | 워크플로 실행/재실행까지 하려면 Read and write |
| Workflows | No access | 기본적으로 불필요 | GitHub Actions workflow 파일 수정/실행 제어가 필요할 때만 부여 |
| Administration | No access | 저장소 설정 변경 권한이라 범위가 큼 | 특별한 관리 작업 없으면 비활성 |
| Secrets | No access | 민감 권한 | 명시적으로 secret 읽기/쓰기 자동화가 필요할 때만 |
| Webhooks | No access | 웹훅 생성/관리 권한 | 앱이 직접 webhook을 관리해야 할 때만 |
| 작업 목적 | Repository access | 필요한 Repository permissions | 권장 수준 |
|---|---|---|---|
| Public repo 읽기 | 선택 안 해도 대부분 가능 | 없음 또는 Metadata: Read | 최소 |
| Private repo clone / pull | Only select repositories | Contents: Read, Metadata: Read | 읽기 전용 |
| 코드 수정 후 push | Only select repositories | Contents: Read and write, Metadata: Read | 기본 개발용 |
| 브랜치 생성 / 커밋 push | Only select repositories | Contents: Read and write, Metadata: Read | 기본 개발용 |
| PR 생성 / 수정 | Only select repositories | Contents: Read and write, Pull requests: Read and write, Metadata: Read | 개발 + PR |
| PR 리뷰 / 코멘트 | Only select repositories | Pull requests: Read and write, Contents: Read, Metadata: Read | 리뷰용 |
| Issue 생성 / 수정 | Only select repositories | Issues: Read and write, Metadata: Read | 이슈 관리용 |
| GitHub Actions 상태 확인 | Only select repositories | Actions: Read, Contents: Read, Metadata: Read | CI 확인용 |
| GitHub Actions 실행 / 재실행 | Only select repositories | Actions: Read and write, Contents: Read, Metadata: Read | 필요 시 |
| Workflow 파일 수정 | Only select repositories | Contents: Read and write, Workflows: Read and write, Metadata: Read | 주의 |
| Release 생성 | Only select repositories | Contents: Read and write, Metadata: Read | 배포용 |
| Organization repo 작업 | 해당 org 선택 | 작업별 repo 권한 | org 승인 필요 가능 |
| Org 멤버 / 팀 조회 | 해당 org 선택 | repo 권한 외 Members: Read 등 org 권한 | 필요할 때만 |
| Repo 설정 변경 | Only select repositories | Administration: Read and write, Metadata: Read | 위험 |
| Secrets / Variables 수정 | Only select repositories | Secrets: Read and write 또는 Variables: Read and write, Metadata: Read | 매우 주의 |
| Webhook 관리 | Only select repositories | Webhooks: Read and write, Metadata: Read | 필요할 때만 |
| 항목 | 추천 설정 |
|---|---|
| Token type | Fine-grained personal access token |
| Resource owner | 개인 계정 또는 작업할 organization |
| Repository access | Only select repositories |
| Repository selection | 작업할 repo만 선택 |
| Metadata | Read |
| Actions | CI 확인만이면 Read, 실행까지 필요하면 Read and write |
| Contents | Read and write |
| Pull requests | Read and write |
| Issues | 이슈 작업 필요 시 Read and write |
토큰은 채팅에 그대로 보내지 말고, 가능하면 .env 같은 로컬 파일에 GITHUB_TOKEN=... 형태로 저장하기.