Using Hooks

Hooks enable automated workflows triggered by specific events during GitHub Copilot coding agent sessions. Each hook is a folder containing scripts and configuration that execute automatically during CCA (Copilot Coding Agent) sessions.

What are Hooks?

Hooks are event-driven automations that execute during GitHub Copilot coding agent sessions. They enable:

Session Logging - Track all CCA activity for audit and analysis
Auto-Commit - Automatically commit changes when sessions end
Integration - Connect to external tools and services
Governance - Scan prompts for security and compliance
Analytics - Collect usage metrics and patterns

Hooks are specifically designed for Copilot Coding Agent (CCA) sessions, not general VS Code or CLI usage.

Hook Structure

Each hook is a folder containing:

hooks/session-logger/
├── README.md              # Documentation with frontmatter
├── hooks.json            # Hook configuration
├── log-session-start.sh  # sessionStart handler
├── log-prompt.sh         # userPromptSubmitted handler
└── log-session-end.sh    # sessionEnd handler

README.md Frontmatter Requirements

---
name: Session Logger
description: 'Logs all Copilot coding agent session activity'
hooks: [sessionStart, sessionEnd, userPromptSubmitted]
tags: [logging, audit, monitoring]
---

name (required): Human-readable hook name
description (required): Wrapped in single quotes, not empty
hooks (extracted from hooks.json): List of event types
tags (optional): Categorization tags
Folder naming: Lowercase with hyphens

hooks.json Configuration

{
  "hooks": [
    {
      "event": "sessionStart",
      "script": "./log-session-start.sh"
    },
    {
      "event": "userPromptSubmitted",
      "script": "./log-prompt.sh"
    },
    {
      "event": "sessionEnd",
      "script": "./log-session-end.sh"
    }
  ]
}

Each hook specifies:

event: The trigger event (see below)
script: Path to the executable script (relative to hooks.json)

Available Hook Events

Hooks can respond to these CCA session events:

Triggered: When a Copilot coding agent session beginsUse Cases:

Initialize logging infrastructure
Set up session tracking
Validate environment configuration
Send session start notifications

Example:

#!/bin/bash
# log-session-start.sh
SESSION_ID=$(date +%s)
echo "Session started: $SESSION_ID" >> .copilot/session.log

Triggered: When a Copilot coding agent session endsUse Cases:

Auto-commit and push changes
Generate session summary
Clean up temporary files
Send completion notifications

Example:

#!/bin/bash
# auto-commit.sh
git add .
git commit -m "CCA session changes"
git push

Triggered: When user submits a prompt during the sessionUse Cases:

Log all user interactions
Scan for security/compliance issues
Track usage patterns
Implement governance rules

Example:

#!/bin/bash
# audit-prompt.sh
PROMPT="$1"
echo "[$(date)] Prompt: $PROMPT" >> .copilot/prompts.log

# Check for sensitive patterns
if echo "$PROMPT" | grep -i "password\|secret\|key"; then
  echo "WARNING: Sensitive data detected" >&2
fi

Triggered: Before CCA uses a toolUse Cases:

Validate tool usage permissions
Log tool invocations
Implement rate limiting
Apply governance policies

Example:

#!/bin/bash
# pre-tool-check.sh
TOOL="$1"
echo "Tool requested: $TOOL" >> .copilot/tools.log

Triggered: After CCA uses a toolUse Cases:

Verify tool execution results
Log outcomes and errors
Update metrics
Trigger follow-up actions

Example:

#!/bin/bash
# post-tool-log.sh
TOOL="$1"
RESULT="$2"
echo "Tool completed: $TOOL (status: $RESULT)" >> .copilot/tools.log

Triggered: When an error occurs during the sessionUse Cases:

Log error details
Send error notifications
Trigger debugging workflows
Collect diagnostics

Example:

#!/bin/bash
# error-handler.sh
ERROR="$1"
echo "[ERROR $(date)] $ERROR" >> .copilot/errors.log
# Send alert to monitoring system
curl -X POST https://monitoring.example.com/alert \
  -d "{\"error\": \"$ERROR\"}"

Installing Hooks

Copy hook folder

Copy the entire hook folder to .github/hooks/ in your repository:

# From awesome-copilot repo
cp -r hooks/session-logger .github/hooks/

Make scripts executable

Ensure all bundled scripts have execute permissions:

chmod +x .github/hooks/session-logger/*.sh

Commit to repository

Hooks must be committed to your repository’s default branch:

git add .github/hooks/session-logger
git commit -m "Add session logging hook"
git push

Test with CCA

Start a Copilot coding agent session to trigger the hooks and verify they execute correctly.

Hooks only execute during Copilot Coding Agent (CCA) sessions, not during regular Copilot chat or completions.

Hook Examples from the Repository

Session Logger
Session Auto-Commit
Governance Audit

Purpose: Logs all CCA session activity

// hooks.json
{
  "hooks": [
    {
      "event": "sessionStart",
      "script": "./log-session-start.sh"
    },
    {
      "event": "userPromptSubmitted",
      "script": "./log-prompt.sh"
    },
    {
      "event": "sessionEnd",
      "script": "./log-session-end.sh"
    }
  ]
}

When to use: Audit trails, usage analytics, session debugging

Purpose: Automatically commits changes when session ends

// hooks.json
{
  "hooks": [
    {
      "event": "sessionEnd",
      "script": "./auto-commit.sh"
    }
  ]
}

#!/bin/bash
# auto-commit.sh
if [[ -n $(git status -s) ]]; then
  git add .
  git commit -m "Auto-commit: CCA session $(date)"
  git push origin $(git branch --show-current)
  echo "Changes committed and pushed"
fi

When to use: Ensuring all CCA changes are automatically saved

Purpose: Scans prompts for security and compliance

// hooks.json
{
  "hooks": [
    {
      "event": "sessionStart",
      "script": "./audit-session-start.sh"
    },
    {
      "event": "userPromptSubmitted",
      "script": "./audit-prompt.sh"
    },
    {
      "event": "sessionEnd",
      "script": "./audit-session-end.sh"
    }
  ]
}

#!/bin/bash
# audit-prompt.sh
PROMPT="$1"

# Check for threat signals
THREATS="bypass|override|ignore|disable|secret|password|token"
if echo "$PROMPT" | grep -iE "$THREATS"; then
  echo "[ALERT] Potential security concern detected" >&2
  # Log to governance system
  logger -t copilot-governance "Alert: $PROMPT"
fi

When to use: Enterprise governance, compliance requirements, security monitoring

Creating Your Own Hooks

Create hook folder

mkdir -p .github/hooks/my-hook
cd .github/hooks/my-hook

Create README.md

---
name: My Custom Hook
description: 'Brief description of what this hook does'
tags: [category, purpose]
---

# My Custom Hook

Detailed documentation...

Create hooks.json

{
  "hooks": [
    {
      "event": "sessionEnd",
      "script": "./my-script.sh"
    }
  ]
}

Write hook script

#!/bin/bash
# my-script.sh

# Your automation logic here
echo "Hook executed: $(date)"

Make it executable:

chmod +x my-script.sh

Test and commit

git add .github/hooks/my-hook
git commit -m "Add custom hook"
git push

Best Practices

Keep Scripts Fast

Hooks should execute quickly to avoid blocking CCA sessions
Use background processes for long-running tasks
Implement timeouts to prevent hangs
Log performance metrics

#!/bin/bash
# Run task in background
./long-running-task.sh &
echo "Task started in background"

Handle Errors Gracefully

Use proper error handling in scripts
Log errors for debugging
Don’t fail silently
Return appropriate exit codes

#!/bin/bash
set -e  # Exit on error

if ! command -v git &> /dev/null; then
  echo "ERROR: git not found" >&2
  exit 1
fi

Secure Sensitive Data

Never hardcode secrets in hook scripts
Use environment variables for credentials
Store sensitive data in secure vaults
Sanitize logs to remove secrets

#!/bin/bash
# Use environment variable
API_KEY="${COPILOT_API_KEY:-}"
if [[ -z "$API_KEY" ]]; then
  echo "ERROR: COPILOT_API_KEY not set" >&2
  exit 1
fi

Make Scripts Portable

Use POSIX-compliant shell syntax
Handle different operating systems
Check for required commands
Use relative paths

#!/bin/bash
# Check for required tools
for cmd in git jq curl; do
  if ! command -v $cmd &> /dev/null; then
    echo "ERROR: $cmd is required" >&2
    exit 1
  fi
done

Troubleshooting

Hook not executing

Verify hook folder is in .github/hooks/
Check scripts are executable (chmod +x)
Ensure hooks.json is valid JSON
Verify hook is committed to default branch
Check CCA logs for error messages

Script errors

Check script syntax with shellcheck
Verify all referenced commands exist
Test scripts manually before committing
Review CCA session logs for stderr output

Permission issues

Ensure scripts have execute permissions
Check file system permissions on .github/hooks/
Verify scripts run in the correct working directory

Security Considerations

Important: Hook scripts execute automatically during CCA sessions. Follow these security guidelines:

Review all scripts before installing hooks from external sources
Limit permissions - hooks should only have necessary access
Validate inputs - sanitize all parameters passed to scripts
Use secure channels - HTTPS for external API calls
Audit regularly - review hook execution logs
Follow least privilege - don’t run hooks with elevated permissions

See the GitHub Copilot hooks specification for official security guidance.

Browse All Hooks
GitHub Copilot Hooks Specification
Agentic Workflows - GitHub Actions automation
Contributing Guide

Overview

Installation

Usage

Using Hooks

Using Hooks

What are Hooks?

Hook Structure

Available Hook Events

Installing Hooks

Hook Examples from the Repository

Creating Your Own Hooks

Best Practices

Troubleshooting

Security Considerations

Build docs developers (and LLMs) love

Overview

Installation

Usage

​Using Hooks

​What are Hooks?

​Hook Structure

​Available Hook Events

​Installing Hooks

​Hook Examples from the Repository

​Creating Your Own Hooks

​Best Practices

​Troubleshooting

​Security Considerations

​Related Resources

Build docs developers (and LLMs) love

Using Hooks

What are Hooks?

Hook Structure

Available Hook Events

Installing Hooks

Hook Examples from the Repository

Creating Your Own Hooks

Best Practices

Troubleshooting

Security Considerations

Related Resources