Skip to content
Arcjet Docs

Secure GitHub Copilot

GitHub Copilot already fires hooks for prompts and tool calls. Arcjet uses those hooks to enforce your policies and record the session. You don’t change how developers work.

What is Arcjet? Arcjet is the AI agent runtime security platform. Discover the agents running in your organization, enforce policy across every action, prompt, and tool call, and keep the evidence to prove what happened. Detect prompt injection, authorize agent tool calls, redact PII, and block bots and abuse.

Before you start

Section titled “Before you start”

Create a free Arcjet account then use the key to authenticate the Arcjet hooks. It is semi-secret, but can be distributed to multiple devices and team members through environment variables or configuration management.

Install the hooks

Section titled “Install the hooks”

This template is a complete setup. Put this file in the repository as .github/hooks/arcjet.json.

Show .github/hooks/arcjet.json
.github/hooks/arcjet.json
{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "http",
        "url": "https://decide.arcjet.com/v1/agent-hooks/copilot?event=pre-tool-use",
        "headers": {
          "Authorization": "Bearer $ARCJET_KEY",
          "X-Arcjet-Principal": "$USER"
        },
        "allowedEnvVars": ["ARCJET_KEY", "USER"],
        "timeoutSec": 5
      }
    ],
    "permissionRequest": [
      {
        "type": "http",
        "url": "https://decide.arcjet.com/v1/agent-hooks/copilot?event=permission-request",
        "headers": {
          "Authorization": "Bearer $ARCJET_KEY",
          "X-Arcjet-Principal": "$USER"
        },
        "allowedEnvVars": ["ARCJET_KEY", "USER"],
        "timeoutSec": 5
      }
    ],
    "userPromptSubmitted": [
      {
        "type": "http",
        "url": "https://decide.arcjet.com/v1/agent-hooks/copilot?event=user-prompt-submit",
        "headers": {
          "Authorization": "Bearer $ARCJET_KEY",
          "X-Arcjet-Principal": "$USER"
        },
        "allowedEnvVars": ["ARCJET_KEY", "USER"],
        "timeoutSec": 5
      }
    ],
    "userPromptTransformed": [
      {
        "type": "http",
        "url": "https://decide.arcjet.com/v1/agent-hooks/copilot?event=user-prompt-transformed",
        "headers": {
          "Authorization": "Bearer $ARCJET_KEY",
          "X-Arcjet-Principal": "$USER"
        },
        "allowedEnvVars": ["ARCJET_KEY", "USER"],
        "timeoutSec": 5
      }
    ],
    "postToolUse": [
      {
        "type": "http",
        "url": "https://decide.arcjet.com/v1/agent-hooks/copilot?event=post-tool-use",
        "headers": {
          "Authorization": "Bearer $ARCJET_KEY",
          "X-Arcjet-Principal": "$USER"
        },
        "allowedEnvVars": ["ARCJET_KEY", "USER"],
        "timeoutSec": 5
      }
    ],
    "agentStop": [
      {
        "type": "http",
        "url": "https://decide.arcjet.com/v1/agent-hooks/copilot?event=stop",
        "headers": {
          "Authorization": "Bearer $ARCJET_KEY",
          "X-Arcjet-Principal": "$USER"
        },
        "allowedEnvVars": ["ARCJET_KEY", "USER"],
        "timeoutSec": 5
      }
    ],
    "sessionStart": [
      {
        "type": "http",
        "url": "https://decide.arcjet.com/v1/agent-hooks/copilot?event=session-start",
        "headers": {
          "Authorization": "Bearer $ARCJET_KEY",
          "X-Arcjet-Principal": "$USER"
        },
        "allowedEnvVars": ["ARCJET_KEY", "USER"],
        "timeoutSec": 5
      }
    ],
    "sessionEnd": [
      {
        "type": "http",
        "url": "https://decide.arcjet.com/v1/agent-hooks/copilot?event=session-end",
        "headers": {
          "Authorization": "Bearer $ARCJET_KEY",
          "X-Arcjet-Principal": "$USER"
        },
        "allowedEnvVars": ["ARCJET_KEY", "USER"],
        "timeoutSec": 5
      }
    ]
  }
}

allowedEnvVars allows $ARCJET_KEY and $USER to be used in the hook headers. Export ARCJET_KEY where the agent runs, or replace the header with a literal value in a file only an administrator can edit. Never commit a literal key.

X-Arcjet-Principal attributes a session to a developer. It’s untrusted, but useful extra metadata. $USER is unset on Windows, so use $USERNAME there and add it to both allowedEnvVars lists.

The hook URLs omit surface. The same file reaches the CLI and the cloud coding agent, so a hard-coded cli mislabels cloud sessions. Arcjet records unknown when you omit the parameter. Set it only when the hook file is specific to one surface.

Copilot hook payloads have no model field. A model-list policy doesn’t run, and a Tool call entry doesn’t approximate it. For more information about model lists, see Allowed models.

Per surface

Section titled “Per surface”

VS Code

Section titled “VS Code”

Agent hooks in VS Code are in preview and do not support HTTP hook types, so cannot be used with Arcjet.

Copilot CLI

Section titled “Copilot CLI”

The CLI reads .github/hooks/*.json from the repository and honors HTTP entries as written. For an administrator lock, put the same JSON in /etc/github-copilot/policy.d/arcjet.json, root-owned and not group- or world-writable. Users can’t disable a policy hook.

Cloud coding agent

Section titled “Cloud coding agent”

The cloud agent runs .github/hooks/*.json from the repository’s default branch, so the hooks apply once the file is merged. Add a firewall allow rule for decide.arcjet.com under the repository or organization’s internet access settings.

Verify the install

Section titled “Verify the install”

  1. Start a Copilot session in a repository that carries the hook file and ask it to run a harmless command, such as listing a directory.

  2. Open the site’s Activity in the Arcjet Console and confirm the session and the tool call appear.

Section titled “Related”