# GitHub Copilot CLI로 후크 사용하기 에이전트를 실행하는 동안 키 지점에서 사용자 지정 셸 명령을 사용하여 에이전트 동작을 확장 GitHub Copilot 합니다. 후크를 사용하면 에이전트를 실행하는 동안 키 지점에서 사용자 지정 셸 명령을 실행하여 에이전트의 GitHub Copilot 동작을 확장하고 사용자 지정할 수 있습니다. 사용 가능한 후크 트리거의 세부 정보를 포함하여 후크의 개념적 개요는 [후크에 대한 정보 GitHub Copilot](/ko/enterprise-cloud@latest/copilot/concepts/agents/hooks)을 참조하세요. ## 전제 조건 **Windows 사용자 전용:** 이 문서의 예제 후크는 Windows, Linux 및 macOS에서 실행되도록 설계되었습니다. Windows 경우 PowerShell을 사용하며 PowerShell 7.0 이상을 설치하고 PATH에 설치해야 합니다. 터미널에서 실행 `pwsh --version` 하여 PowerShell 버전을 확인할 수 있습니다. PowerShell을 설치하려면 `winget install Microsoft.PowerShell` 실행한 다음 터미널을 다시 시작합니다. ## 리포지토리 수준 후크 만들기 1. 리포지토리의 `NAME.json` 폴더에 새 `NAME` 파일(`.github/hooks/`는 파일의 용도를 설명함)을 만듭니다. 2. 텍스트 편집기에서 다음 후크 템플릿을 복사하여 붙여넣습니다. 사용하지 않을 계획인 후크를 `hooks` 배열에서 제거합니다. ```json copy { "version": 1, "hooks": { "sessionStart": [...], "sessionEnd": [...], "userPromptSubmitted": [...], "preToolUse": [...], "postToolUse": [...], "errorOccurred": [...] } } ``` 3. `bash` 및 `powershell` 키에서 후크 구문을 구성하거나 직접 만든 스크립트 파일을 참조하세요. > \[!NOTE] > 세 운영 체제에서 후크를 실행할 수 있도록 `bash` 키(Linux 및 macOS용 스크립트 포함)와 `powershell` 키(Windows 스크립트용)를 모두 포함합니다. > Copilot 는 사용자의 운영 체제에 따라 적절한 키를 사용합니다. * 이 예제에서는 후크를 사용하여 세션의 시작 날짜를 로그 파일에 출력하는 스크립트를 `sessionStart` 실행합니다. ```json copy "sessionStart": [ { "type": "command", "bash": "echo \"Session started: $(date)\" >> logs/session.log", "powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"", "cwd": ".", "timeoutSec": 10 } ], ``` * 이 예제에서는 외부 `log-prompt` 스크립트를 호출합니다. ```json copy "userPromptSubmitted": [ { "type": "command", "bash": "./scripts/log-prompt.sh", "powershell": "./scripts/log-prompt.ps1", "cwd": "scripts", "env": { "LOG_LEVEL": "INFO" } } ], ``` 샘플 스크립트와 함께 에이전트 세션의 입력 JSON에 대한 전체 참조는 [GitHub Copilot 후크 참조](/ko/enterprise-cloud@latest/copilot/reference/hooks-reference)을 참조하세요. 4. 파일을 리포지토리에 커밋하고 기본 분기에 병합합니다. 이제 에이전트 세션 동안 후크가 실행됩니다. ## 사용자 수준 후크 만들기 사용자 수준 후크는 리포지토리 수준 후크처럼 구성되지만 후크 파일은 홈 디렉터리 아래에 로컬로 저장됩니다. macOS 및 Windows 대한 다음 예제에서는 CLI가 프롬프트에 응답하는 것을 완료하고 Copilot CLI 종료할 때 소리를 재생하고 메시지 상자를 표시하는 후크를 구성하는 방법을 보여 줍니다. Linux용 후크는 macOS 예제와 유사하지만, 소리를 재생하고 메시지를 표시하기 위해 Linux 도구를 사용합니다. ### macOS에 대한 사용자 수준 예제 1. `notification-hooks.json`에 `~/.copilot/hooks/`이라는 파일을 만듭니다. > \[!NOTE] > `COPILOT_HOME`이 설정된 경우 `$COPILOT_HOME/hooks/`에 파일을 생성합니다. 2. 다음 JSON을 복사하여 파일에 붙여넣습니다. ```json copy { "version": 1, "hooks": { "agentStop": [ { "type": "command", "bash": "osascript -e 'do shell script \"afplay /System/Library/Sounds/Funk.aiff &> /dev/null &\"' -e 'display dialog \"Agent stopped.\" with title \"Hook-generated message\" buttons {\"OK\"} default button \"OK\"'", "timeoutSec": 5 } ], "sessionEnd": [ { "type": "command", "bash": "osascript -e 'do shell script \"afplay /System/Library/Sounds/Funk.aiff &> /dev/null &\"' -e 'display dialog \"Session ended.\" with title \"Hook-generated message\" buttons {\"OK\"} default button \"OK\"'", "timeoutSec": 5 } ] } } ``` 3. Copilot CLI을(를) 시작하거나 다시 시작합니다. > \[!NOTE] > 후크 구성에 대한 변경 내용은 CLI가 시작될 때 로드됩니다. 4. 프롬프트를 입력하고 소리가 들리고 에이전트가 응답을 완료하고 CLI를 종료할 때 메시지 상자가 표시되는지 확인합니다. 5. `notification-hooks.json` 파일을 삭제하여 이러한 후크를 제거합니다. ### Windows 대한 사용자 수준 예제 1. `notification-hooks.json`에 `%USERPROFILE%\.copilot\hooks\`이라는 파일을 만듭니다. > \[!NOTE] > `COPILOT_HOME`이 설정된 경우 `%COPILOT_HOME%\hooks\`에 파일을 생성합니다. 2. 다음 JSON을 복사하여 파일에 붙여넣습니다. ```json copy { "version": 1, "hooks": { "agentStop": [ { "type": "command", "powershell": "Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Agent stopped.', 'Hook-generated message') | Out-Null", "timeoutSec": 5 } ], "sessionEnd": [ { "type": "command", "powershell": "Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Session ended.', 'Hook-generated message') | Out-Null", "timeoutSec": 5 } ] } } ``` 3. Copilot CLI을(를) 시작하거나 다시 시작합니다. > \[!NOTE] > 후크 구성에 대한 변경 내용은 CLI가 시작될 때 로드됩니다. 4. 프롬프트를 입력하고 소리가 들리고 에이전트가 응답을 완료하고 CLI를 종료할 때 메시지 상자가 표시되는지 확인합니다. 5. `notification-hooks.json` 파일을 삭제하여 이러한 후크를 제거합니다. ## 문제 해결 후크를 사용하여 문제가 발생하면 다음 표를 사용하여 문제를 해결합니다. | Issue | 조치 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 후크가 실행되고 있지 않습니다. | | | | 후크가 시간 초과되고 있습니다 | | | 잘못된 JSON 출력 | | ## 디버깅 다음 메서드를 사용하여 후크를 디버그할 수 있습니다. * **스크립트에서 상세 로깅을 활성화하여** 입력 데이터를 점검하고 스크립트 실행을 추적합니다. ```shell copy #!/bin/bash set -x # Enable bash debug mode INPUT=$(cat) echo "DEBUG: Received input" >&2 echo "$INPUT" >&2 # ... rest of script ``` * 테스트 입력을 후크에 파이핑하여 **로컬로 후크를 테스트**하여 해당 동작의 유효성을 검사합니다. ```shell copy # Create test input echo '{"timestamp":1704614400000,"cwd":"/tmp","toolName":"bash","toolArgs":"{\"command\":\"ls\"}"}' | ./my-hook.sh # Check exit code echo $? # Validate output is valid JSON ./my-hook.sh | jq . ``` ## 추가 읽기 * [GitHub Copilot 후크 참조](/ko/enterprise-cloud@latest/copilot/reference/hooks-reference) * [GitHub Copilot 클라우드 에이전트 정보](/ko/enterprise-cloud@latest/copilot/concepts/agents/cloud-agent/about-cloud-agent) * [GitHub Copilot CLI 정보](/ko/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/about-copilot-cli) * [개발 환경 구성](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment)