GitHub Copilot Integration

Use the GitHub Copilot integration when you want FireGuard to check Copilot CLI sessions and Copilot cloud agent jobs before tool calls run.

This integration covers Copilot CLI (~/.copilot/hooks/) and Copilot cloud agent (.github/hooks/ on the default branch). It does not cover VS Code inline completions, Tab suggestions, or Microsoft Copilot Studio.

Requirements

• python3 available on PATH.
• A FireGuard API key.
• A FireGuard project ID with the policies and security guardrails you want to enforce.

Install

User-level (Copilot CLI)

curl -fsSL https://raw.githubusercontent.com/fireravenai/fireraven-agent-hooks/refs/heads/main/install.sh | sh -s -- --agent github-copilot

Or install from a local clone of github.com/fireravenai/fireraven-agent-hooks:

./fg install --agent github-copilot
./fg doctor

This writes:

Project-level (Copilot cloud agent)

From your repository root:

./fg install --agent github-copilot --project

This writes:

Cloud agent only loads .github/hooks/*.json from the cloned repository on the default branch.

Configure

Edit config.env in the installed hooks directory:

FIRERAVEN_GUARDRAILS_API_KEY=fg_...
FIRERAVEN_PROJECT_ID=00000000-0000-0000-0000-000000000000

Optional overrides (installer defaults are normal / open if omitted):

FIRERAVEN_API_URL=https://api.fireraven.ai
# FIRERAVEN_EXECUTION_MODE=fast
FIRERAVEN_REQUEST_TIMEOUT_SEC=15
# FIRERAVEN_FAIL_MODE=closed

Restart Copilot CLI or merge hook files to the default branch after editing config.env.

Configuration reference

FIRERAVEN_EXECUTION_MODE

See FireGuard concepts — Execution modes.

FIRERAVEN_FAIL_MODE

For preToolUse, GitHub Copilot treats hook crashes and non-zero exits as deny when fail-closed.

What GitHub Copilot Checks

Unlike Cursor, GitHub Copilot cannot block prompts via userPromptSubmitted. Enforcement happens on tool calls through preToolUse.

GitHub Copilot blocks by returning:

{
  "permissionDecision": "deny",
  "permissionDecisionReason": "Blocked by Fireraven FireGuard."
}

See the GitHub Copilot hooks documentation for platform details.

Copilot cloud agent prerequisites

1. Merge .github/hooks/fireraven-fireguard.json and .github/hooks/fireraven/ to your repository default branch.
2. Configure .github/hooks/fireraven/config.env with Fireraven credentials (do not commit secrets).
3. Ensure outbound network allows api.fireraven.ai (org admin firewall allow rule may be required).
4. Cloud agent runs Linux/bash only — powershell hook entries are ignored.

Verify

Smoke-test the hook script directly (no Copilot required):

echo '{"sessionId":"test","prompt":"hello"}' \
  | python3 ~/.copilot/hooks/fireraven/github_copilot_guardrail.py

echo '{"sessionId":"test","toolName":"bash","toolArgs":"{\"command\":\"rm -rf /\"}"}' \
  | python3 ~/.copilot/hooks/fireraven/github_copilot_guardrail.py

From a clone of the hooks repository, use:

./fg doctor

Windows

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/fireravenai/fireraven-agent-hooks/refs/heads/main/install.ps1))) -Agent github-copilot

Project install:

powershell -ExecutionPolicy Bypass -File .\install.ps1 -Agent github-copilot -Project

If py -3 is unavailable in the Copilot hook environment, edit fireraven-fireguard.json to use run_github_copilot_guardrail.ps1 for the powershell field.

Related Pages