GitHub Copilot 가이드: 권한·감사·복구를 위한 Hooks
Answer in brief
GitHub Copilot 훅은 Copilot CLI와 Copilot cloud agent의 정해진 수명 주기 시점에 외부 명령을 실행합니다. 도구 호출 전 권한 결정, 감사 기록, 정리 및 오류 알림에 활용할 수 있지만 설정 위치, 지원 이벤트, 출력 보존 방식은 실행 환경에 따라 다릅니다.
Key facts at a glance
| Product / model | Current ID or version | Use case | Evidence |
|---|---|---|---|
| github-copilot | Official source does not specify a selectable model ID | Confirm the current product surface | Official source Official source |
Failure modes and verification
| Failure mode | Verification action |
|---|---|
| Stale model or version reference | Compare the model name and ID with the official source before release. |
| Unstructured or incomplete output | Validate the response against the documented contract and a deterministic fixture. |
| Unverified factual claim | Keep the claim qualified or remove the claim when the official source does not support it. |
FAQ
GitHub Copilot 훅 설정은 어디에 저장할 수 있나요?
저장소 훅은 .github/hooks/*.json에 저장합니다. Copilot CLI는 사용자 디렉터리, 인라인 설정, 설치된 플러그인, 관리자 정책 소스도 지원합니다. Copilot cloud agent는 기본적으로 저장소의 훅 파일만 검색합니다. 자세한 내용은 공식 훅 참조 문서를 확인하십시오.
Copilot CLI와 Copilot cloud agent에서 같은 훅 이벤트를 사용할 수 있나요?
아닙니다. Copilot CLI는 훅 참조 문서에 설명된 모든 이벤트를 지원하지만 Copilot cloud agent에서는 일부 이벤트만 발생합니다. 특정 수명 주기 이벤트에 의존하기 전에 대상 실행 환경을 확인해야 합니다.
도구 실행을 승인하거나 거부하는 훅은 무엇인가요?
preToolUse가 호출하려는 도구의 실행을 프로그래밍 방식으로 승인하거나 거부할 수 있습니다. Copilot cloud agent는 도구 권한이 미리 부여된 상태로 실행되고 권한 대화상자를 표시하지 않으므로, 이 통제는 대화형 승인이 아닙니다. 자세한 내용은 공식 훅 참조 문서를 확인하십시오.
감사 로깅에는 어떤 이벤트가 유용한가요?
sessionStart, sessionEnd, userPromptSubmitted, preToolUse, postToolUse, 에이전트 중지 이벤트, errorOccurred를 이용해 실행 과정의 서로 다른 단계를 기록할 수 있습니다. postToolUse는 도구 실행의 성공 여부와 관계없이 완료 후 발생합니다. 로그에는 비밀 정보와 불필요한 프롬프트 원문을 남기지 않아야 합니다.
훅이 실패한 변경 사항을 자동으로 롤백하나요?
제공된 공식 문서는 자동 롤백 동작을 정의하지 않습니다. errorOccurred, sessionEnd, 재개된 세션의 sessionStart로 사용자 정의 복구, 정리, 검증 명령을 시작할 수 있지만 실제 롤백 절차는 별도로 설계하고 시험해야 합니다.
Copilot cloud agent의 감사 출력을 어떻게 보존하나요?
임시 Linux 샌드박스의 파일은 작업이 끝나면 폐기됩니다. 보존해야 하는 출력은 http 훅 항목으로 전송해야 합니다. GitHub와 Copilot 이외의 목적지에 연결하려면 관리자가 방화벽 허용 규칙을 구성해야 합니다.
훅 설정이 잘못되면 어떻게 처리되나요?
디렉터리에서 불러오는 파일은 잘못된 개별 훅만 제외하고 오류를 기록하며 유효한 나머지 항목은 계속 로드합니다. 잘못된 JSON, 지원되지 않는 version, 배열이 아닌 이벤트 목록은 파일 전체를 거부합니다. 인라인 settings.json 훅은 개별 항목 오류가 있어도 hooks 필드 전체를 거부합니다.
Sources and freshness
- Official source
- Official source
- Last verified: 2026-08-30
Extended guide
GitHub Copilot 훅은 에이전트 세션의 정해진 시점에 외부 명령을 실행합니다. Copilot CLI와 Copilot cloud agent에서 사용할 수 있지만, 설정을 찾는 위치와 지원 이벤트, 실행 환경, 출력 보존 방식은 서로 다릅니다. 훅을 이용하면 도구 호출을 통제하고 감사 데이터를 수집하며 정리 작업이나 오류 알림을 시작할 수 있습니다. 다만 공식 문서는 훅을 완료된 변경 사항을 자동으로 되돌리는 롤백 기능으로 설명하지 않습니다.
적용 범위와 훅 위치
설정은 version: 1과 hooks 객체를 포함하는 JSON 형식입니다. hooks 객체의 이벤트 키마다 훅 정의 배열을 둡니다. 명령 훅은 동기적으로 실행되어 에이전트 진행을 멈추므로 실행 시간을 제한하고 빠르게 끝나도록 설계해야 합니다. GitHub는 가능하면 실행 시간을 5초 미만으로 유지하도록 권고합니다.
| 영역 | 공식 문서에 명시된 동작 |
|---|---|
| Copilot CLI | 훅 소스는 정책, 사용자, 프로젝트, 플러그인 순으로 결합됩니다. 저장소 훅 파일은 .github/hooks/*.json에 둡니다. 사용자 훅의 기본 위치는 macOS와 Linux에서 ~/.copilot/hooks/, Windows에서 %USERPROFILE%\.copilot\hooks\입니다. COPILOT_HOME을 설정하면 $COPILOT_HOME/hooks/를 사용합니다. 저장소 및 사용자 설정에 작성한 인라인 hooks 블록과 설치된 플러그인이 제공하는 훅도 지원합니다. 여러 소스에 같은 이벤트가 있으면 어느 하나가 다른 항목을 덮어쓰지 않으며 모든 항목이 실행됩니다. |
| 정책 훅 | Copilot CLI에서만 지원하는 장치 전체 설정입니다. 다른 훅보다 먼저 로드되며 disableAllHooks로 비활성화할 수 없습니다. 파일은 /etc/github-copilot/policy.d/*.json 또는 C:\ProgramData\GitHub\Copilot\policy.d\*.json에서 읽습니다. Windows Registry 정책도 지원합니다. 관리자 권한으로 설치해야 하며 폴더 신뢰 상태와 관계없이 적용됩니다. POSIX 정책 파일은 root 소유여야 하고 그룹이나 다른 사용자가 쓸 수 없어야 합니다. |
| Copilot cloud agent | 기본적으로 복제된 저장소의 .github/hooks/*.json만 검색합니다. 훅은 작업마다 마련되는 비대화형 임시 Linux 샌드박스에서 실행됩니다. bash 항목을 사용하고 command를 대체 수단으로 처리하며 powershell 항목은 무시합니다. 저장소가 복제된 경우 작업 디렉터리는 /workspace이고, 그렇지 않으면 /root입니다. 사용자 설정 파일이나 설치된 플러그인이 기본으로 제공된다고 가정해서는 안 됩니다. |
| 수명 주기 이벤트 | 공식 문서에는 sessionStart, sessionEnd, userPromptSubmitted, preToolUse, postToolUse, agentStop, subagentStop, errorOccurred가 설명되어 있습니다. Copilot CLI는 참조 문서에 나온 모든 이벤트를 지원하지만 Copilot cloud agent에서는 일부 이벤트만 발생합니다. 따라서 두 환경에 같은 설정을 배포하기 전에 필요한 이벤트가 대상 환경에서 실제로 발생하는지 확인해야 합니다. |
| 권한과 감사 | preToolUse는 호출하려는 도구의 실행을 승인하거나 거부할 수 있습니다. postToolUse는 도구 실행이 성공했든 실패했든 완료 후 실행됩니다. 세션, 사용자 프롬프트, 도구 호출, 에이전트 중지, 오류 이벤트를 함께 사용하면 실행 과정의 서로 다른 단계를 감사 기록으로 남길 수 있습니다. |
운영 설계
- 적용 범위를 먼저 정합니다. 저장소 구성원이 공유할 통제는
.github/hooks/*.json에 둡니다. 개인적인 Copilot CLI 동작은 사용자 훅에 두고, 장치 전체에서 강제할 요구 사항은 관리자가 설치하는 정책 훅으로 구현합니다. 같은 이벤트의 항목이 모두 실행되므로 정책, 사용자, 프로젝트, 플러그인 설정을 함께 검토해야 합니다. 서로 다른 소스에 중복 검사가 있으면 실행 시간과 로그 중복도 함께 확인합니다. - 이벤트마다 책임을 분리합니다.
sessionStart는 새 세션이나 재개된 세션에서 환경을 초기화하고 프로젝트 상태를 검증하는 데 사용할 수 있습니다.userPromptSubmitted는 사용자 요청 기록에,preToolUse는 다음 도구 호출 검사에,postToolUse는 실행 결과 수집에 연결합니다.agentStop,subagentStop,sessionEnd는 최종 상태 기록, 보고서 생성, 임시 리소스 정리에 활용할 수 있습니다. 각 훅이 너무 많은 책임을 맡지 않도록 목적과 출력 형식을 명확히 정합니다. - 권한 결정을 안전하게 구현합니다. 훅에 전달되는 JSON을 신뢰하지 말고 구조와 필수 값을 검사한 뒤 필요한 값만 사용합니다. 셸 명령을 만들 때 올바르게 이스케이프하고, 비밀번호와 토큰 또는 불필요한 프롬프트 원문을 명령이나 로그에 넣지 않습니다. Copilot cloud agent에서는 도구 권한이 미리 부여되고 사용자에게 권한 대화상자가 표시되지 않습니다. 따라서
preToolUse정책은 대화형 사용자 승인 절차가 아니라 코드로 수행하는 승인 또는 거부 절차입니다. 자세한 환경 차이는 훅 참조 문서에서 확인할 수 있습니다. - 감사 추적의 범위를 제한합니다. 감사 정책에 필요한 세션 식별자, 이벤트 시각, 도구 식별자, 결정, 결과, 오류만 기록합니다.
timeoutSec에 상한을 두고 훅 스크립트와 로그 파일에 적절한 권한을 적용합니다. 로깅 대상과 보존 기간도 운영 정책에 맞게 정합니다. 승인과 거부 경로를 모두 시험하고, 도구 실행의 성공과 실패 결과가 각각 올바르게 기록되는지 확인합니다. 로깅 실패가 에이전트를 무기한 차단하지 않는지도 검증합니다. - 복구 절차를 별도로 설계합니다.
errorOccurred는 오류 기록이나 알림에,sessionEnd는 정리와 보고서 생성에,sessionStart는 세션 재개 후 상태 재검증에 사용할 수 있습니다. 이 이벤트들은 사용자 정의 복구 명령을 시작할 수 있지만 이미 수정된 파일이나 완료된 외부 작업을 스스로 되돌리지는 않습니다. 롤백이 필요하다면 실행 조건, 되돌릴 대상, 실패 시 처리, 감사 기록을 훅 구현에 명시해야 합니다. 재개 시에는 이전 세션의 상태가 자동 복원된다고 가정하지 말고 실제 프로젝트 상태를 다시 검사합니다.
Copilot cloud agent의 파일은 작업이 끝나면 폐기됩니다. 작업 후에도 보존해야 하는 출력은 http 훅 항목으로 전송해야 합니다. GitHub와 Copilot 이외의 목적지로 연결하려면 관리자가 방화벽 허용 규칙을 구성해야 합니다. 이 내보내기 경로를 시험할 때도 샌드박스 토큰이나 기타 민감한 값을 기록하지 않아야 합니다.
디렉터리에서 불러오는 설정 파일에 잘못된 개별 훅 항목이 있으면 해당 항목만 제외하고 오류를 기록하며, 같은 파일의 유효한 항목은 계속 로드합니다. 반면 잘못된 JSON, 지원되지 않는 version, 배열이 아닌 이벤트 목록 같은 구조 오류가 있으면 파일 전체를 거부합니다. settings.json에 인라인으로 정의한 훅은 더 엄격합니다. 개별 항목의 검증 오류도 hooks 필드 전체를 거부하므로 배포 전에 구조 오류와 항목 오류를 모두 검사해야 합니다.
모델 제공 범위 안내: 공식 출처는 선택 가능한 모델 ID를 지정하지 않습니다.
근거와 최신성
근거 수준: 공식 문서 검증
AI-assisted editorial content; verify current product details against the linked official sources.
마지막 검증: