후크 정보

후크에 대하여

후크를 사용하면 에이전트 세션이 시작 또는 종료되거나 프롬프트가 입력되거나 도구가 호출되기 전과 후에 에이전트 워크플로의 전략적 지점에서 사용자 지정 셸 명령을 실행할 수 있습니다.

후크는 JSON 입력을 통해 에이전트 작업에 대한 자세한 정보를 수신하여 컨텍스트 인식 자동화를 사용하도록 설정합니다. 예를 들어 후크를 사용하여 다음을 수행할 수 있습니다.

프로그래밍 방식으로 도구 실행을 승인하거나 거부합니다.
비밀 검사와 같은 기본 제공 보안 기능을 활용하여 자격 증명 누출을 방지합니다.
규정 준수에 대한 사용자 지정 유효성 검사 규칙 및 감사 로깅을 구현합니다.

Copilot 에이전트는 .github/hooks/*.json 리포지토리의 JSON 파일에 저장된 후크를 지원합니다.

후크는 다음과 함께 사용할 수 있습니다.

GitHub의 Copilot 코딩 에이전트
터미널에서 GitHub Copilot 명령 줄 인터페이스 (CLI)

후크 유형

다음 유형의 후크를 사용할 수 있습니다.

        **sessionStart**: 새 에이전트 세션이 시작되거나 기존 세션을 다시 시작할 때 실행됩니다. 환경을 초기화하고, 감사를 위해 세션 로그를 시작하고, 프로젝트 상태의 유효성을 검사하고, 임시 리소스를 설정하는 데 사용할 수 있습니다.

        **sessionEnd**: 에이전트 세션이 완료되거나 종료될 때 실행됩니다. 임시 리소스를 정리하거나, 세션 보고서 및 로그를 생성 및 보관하거나, 세션 완료에 대한 알림을 보내는 데 사용할 수 있습니다.

        **userPromptSubmitted**: 사용자가 에이전트에 프롬프트를 제출할 때 실행됩니다. 감사 및 사용량 분석에 대한 사용자 요청을 기록하는 데 사용할 수 있습니다.

        **preToolUse**: 에이전트가 모든 도구(예: , `bash``edit`)를 `view`사용하기 전에 실행됩니다. 도구 **실행을 승인하거나 거부할** 수 있는 가장 강력한 후크입니다. 이 후크를 사용하여 위험한 명령을 차단하고, 보안 정책 및 코딩 표준을 적용하고, 중요한 작업에 대한 승인이 필요하거나, 규정 준수를 위해 도구 사용을 기록할 수 있습니다.

        **postToolUse**: 도구가 실행을 완료한 후 실행됩니다(성공 여부 또는 실패 여부). 실행 결과를 기록하고, 사용 통계를 추적하고, 감사 내역을 생성하고, 성능 메트릭을 모니터링하고, 실패 경고를 보내는 데 사용할 수 있습니다.

        **errorOccurred**: 에이전트를 실행하는 동안 오류가 발생할 때 실행됩니다. 디버깅 오류를 기록하고, 알림을 보내고, 오류 패턴을 추적하고, 보고서를 생성하는 데 사용할 수 있습니다.

예제 사용 사례, 모범 사례 및 고급 패턴이 있는 후크 형식에 대한 전체 참조를 보려면 후크 구성을 참조하세요.

후크 구성 형식

특수 JSON 형식을 사용하여 후크를 구성합니다. JSON에는 1 값이 있는 version 필드와 후크 정의 배열이 포함된 hooks 개체가 있어야 합니다.

JSON

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "string (optional)",
        "powershell": "string (optional)",
        "cwd": "string (optional)",
        "env": { "KEY": "value" },
        "timeoutSec": 30
      }
    ],
  }
}

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "string (optional)",
        "powershell": "string (optional)",
        "cwd": "string (optional)",
        "env": { "KEY": "value" },
        "timeoutSec": 30
      }
    ],
  }
}

후크 개체에는 다음 키가 포함될 수 있습니다.

재산	필수	Description
`type`	Yes

          `"command"`이어야 합니다. |

후크 구성 파일 예제

리포지토리 내에 있는 ~/.github/hooks/project-hooks.json 예제 구성 파일입니다.

JSON

{
  "version": 1,
  "hooks": {
    "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
      }
    ],
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "./scripts/log-prompt.sh",
        "powershell": "./scripts/log-prompt.ps1",
        "cwd": "scripts",
        "env": {
          "LOG_LEVEL": "INFO"
        }
      }
    ],
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/security-check.sh",
        "powershell": "./scripts/security-check.ps1",
        "cwd": "scripts",
        "timeoutSec": 15
      },
      {
        "type": "command",
        "bash": "./scripts/log-tool-use.sh",
        "powershell": "./scripts/log-tool-use.ps1",
        "cwd": "scripts"
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "cat >> logs/tool-results.jsonl",
        "powershell": "$input | Add-Content -Path logs/tool-results.jsonl"
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "./scripts/cleanup.sh",
        "powershell": "./scripts/cleanup.ps1",
        "cwd": "scripts",
        "timeoutSec": 60
      }
    ]
  }
}

{
  "version": 1,
  "hooks": {
    "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
      }
    ],
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "./scripts/log-prompt.sh",
        "powershell": "./scripts/log-prompt.ps1",
        "cwd": "scripts",
        "env": {
          "LOG_LEVEL": "INFO"
        }
      }
    ],
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/security-check.sh",
        "powershell": "./scripts/security-check.ps1",
        "cwd": "scripts",
        "timeoutSec": 15
      },
      {
        "type": "command",
        "bash": "./scripts/log-tool-use.sh",
        "powershell": "./scripts/log-tool-use.ps1",
        "cwd": "scripts"
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "cat >> logs/tool-results.jsonl",
        "powershell": "$input | Add-Content -Path logs/tool-results.jsonl"
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "./scripts/cleanup.sh",
        "powershell": "./scripts/cleanup.ps1",
        "cwd": "scripts",
        "timeoutSec": 60
      }
    ]
  }
}

성능 고려 사항

후크는 동기적으로 실행되고 에이전트 실행을 차단합니다. 응답성이 뛰어난 환경을 보장하려면 다음 고려 사항을 염두에 두세요.

        **실행 시간 최소화**: 가능하면 후크 실행 시간을 5초 미만으로 유지합니다.

        **로깅 최적화**: 동기 I/O 대신 파일에 추가하는 것과 같은 비동기 로깅을 사용합니다.

        **백그라운드 처리 사용**: 비용이 많이 드는 작업의 경우 백그라운드 처리를 고려합니다.

        **캐시 결과**: 가능한 경우 비용이 많이 드는 계산을 캐시합니다.

보안 고려 사항

후크를 사용할 때 보안이 유지되도록 하려면 다음 고려 사항에 유의하세요.

        **항상 후크에서 처리한 입력의 유효성을 검사하고 정화하십시오**. 신뢰할 수 없는 입력으로 인해 예기치 않은 동작이 발생할 수 있습니다.

        **명령을 생성할 때 적절한 셸 이스케이프를 사용합니다**. 이렇게 하면 명령 삽입 취약성이 방지됩니다.

        **토큰 또는 암호와 같은 중요한 데이터를 기록하지 않습니다**.

        **후크 스크립트 및 로그에 적절한 권한이 있는지 확인합니다**.

        **외부 네트워크를 호출하는 후크에 주의하세요**. 이러한 요소들은 대기 시간, 실패를 초래하거나, 데이터를 타사에 노출할 수 있습니다.

        **리소스 소모를 방지하기 위해 적절한 시간 제한을 설정합니다**. 장기 실행 후크는 에이전트 실행을 차단하고 성능을 저하시킬 수 있습니다.

다음 단계

후크 만들기를 시작하려면 GitHub Copilot 에이전트와 훅 사용을 참조하세요.

누가 이 기능을 사용할 수 있나요?

이 문서의 내용