GitHub Copilot CLI에서 후크 사용

후크를 사용하면 에이전트를 실행하는 동안 키 지점에서 사용자 지정 셸 명령을 실행하여 GitHub Copilot 에이전트의 동작을 확장하고 사용자 지정할 수 있습니다. 후크의 개념적 개요는 후크에 관하여을 참조하세요.

GitHub의 리포지토리에 후크 만들기

리포지토리 폴더에 hooks.json 원하는 이름을 사용하여 새 .github/hooks/ 파일을 만듭니다. Copilot 코딩 에이전트에서 사용되기 위해서는 후크 구성 파일이 반드시 리포지토리의 기본 분기에 존재해야 합니다. GitHub Copilot 명령 줄 인터페이스 (CLI)의 경우 현재 작업 디렉터리에서 후크가 로드됩니다.

텍스트 편집기에서 다음 후크 템플릿을 복사하여 붙여넣습니다. 사용하지 않을 계획인 후크를 hooks 배열에서 제거합니다.

JSON

{
  "version": 1,
  "hooks": {
    "sessionStart": [...],
    "sessionEnd": [...],
    "userPromptSubmitted": [...],
    "preToolUse": [...],
    "postToolUse": [...],
    "errorOccurred": [...]
  }
}

{
  "version": 1,
  "hooks": {
    "sessionStart": [...],
    "sessionEnd": [...],
    "userPromptSubmitted": [...],
    "preToolUse": [...],
    "postToolUse": [...],
    "errorOccurred": [...]
  }
}

       `bash` 또는 `powershell` 키 아래에서 후크 구문을 구성하거나, 직접 만든 스크립트 파일을 참조합니다.

이 예제에서는 후크를 사용하여 세션의 시작 날짜를 로그 파일에 출력하는 스크립트를 sessionStart 실행합니다.

JSON

"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
  }
],

"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

"userPromptSubmitted": [
  {
    "type": "command",
    "bash": "./scripts/log-prompt.sh",
    "powershell": "./scripts/log-prompt.ps1",
    "cwd": "scripts",
    "env": {
      "LOG_LEVEL": "INFO"
    }
  }
],

"userPromptSubmitted": [
  {
    "type": "command",
    "bash": "./scripts/log-prompt.sh",
    "powershell": "./scripts/log-prompt.ps1",
    "cwd": "scripts",
    "env": {
      "LOG_LEVEL": "INFO"
    }
  }
],

샘플 스크립트와 함께 에이전트 세션의 입력 JSON에 대한 전체 참조는 후크 구성을 참조하세요.

파일을 리포지토리에 커밋하고 기본 분기에 병합합니다. 이제 에이전트 세션 중에 후크가 실행됩니다.

Troubleshooting

후크를 사용하여 문제가 발생하면 다음 표를 사용하여 문제를 해결합니다.

문제	조치
후크가 실행되고 있지 않습니다.	JSON 파일이 디렉터리에 있는지 `.github/hooks/` 확인합니다. 유효한 JSON 구문(예: `jq . hooks.json`)을 확인합니다.

          `version: 1`이 당신의 `hooks.json` 파일에 지정되어 있는지 확인하십시오.</li><li>후크에서 호출하는 스크립트가 실행 파일인지 확인(`chmod +x script.sh`)</li><li>스크립트에 적절한 shebang이 있는지 확인합니다(예: `#!/bin/bash`).</li></ul> |

| 후크가 시간 초과되고 있습니다 |

기본 제한 시간은 30초입니다. 필요한 경우 timeoutSec을(를) 구성에 추가하십시오.
불필요한 작업을 방지하여 스크립트 성능을 최적화합니다.

| | 잘못된 JSON 출력 |

출력이 한 줄에 있는지 확인합니다.
Unix에서 JSON 출력을 압축하고 유효성을 검사하는 데 사용합니다 jq -c .
Windows에서 PowerShell의 ConvertTo-Json -Compress 명령을 사용하여 동일한 작업을 수행합니다.

디버깅

다음 메서드를 사용하여 후크를 디버그할 수 있습니다.

        **스크립트에서 상세 로깅을 활성화하여** 입력 데이터를 점검하고 스크립트 실행을 추적합니다.

Shell

#!/bin/bash
set -x  # Enable bash debug mode
INPUT=$(cat)
echo "DEBUG: Received input" >&2
echo "$INPUT" >&2
# ... rest of script

#!/bin/bash
set -x  # Enable bash debug mode
INPUT=$(cat)
echo "DEBUG: Received input" >&2
echo "$INPUT" >&2
# ... rest of script

테스트 입력을 후크에 파이핑하여 로컬로 후크를 테스트하여 해당 동작의 유효성을 검사합니다.

Shell

# 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 .

# 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 .

추가 읽기

        [AUTOTITLE](/copilot/reference/hooks-configuration)

        [AUTOTITLE](/copilot/concepts/agents/coding-agent/about-coding-agent)

        [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli)

        [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment)

이 문서의 내용

GitHub의 리포지토리에 후크 만들기

Troubleshooting

디버깅

추가 읽기