Why This Matters

Manual policy management doesn't scale across teams and orgs. API-driven policy ensures consistency, audit, and automation.

Concept Explained

/copilot/org-policy endpoints allow: content filter mode (block/allow), model allowlist (which models users can pick), training opt-out enforcement.

How It Works

GET current policy. PUT to update. Audit changes. Enforce via CI checks or scheduled jobs.

Step-by-Step Tutorial

1. Get current policy

2. Set content filter

3. Set model allowlist

4. Enforce training opt-out

5. Audit

Real-World Example

A regulated org used the Policy API to enforce: content filter block, model allowlist (only approved models), training opt-out. CI check verified policy weekly; alerted if anything changed. Passed compliance audit.

Example Prompts / Commands / Code

import requests

ORG = 'your-org'
TOKEN = 'YOUR_GITHUB_TOKEN'

def get_policy():
    r = requests.get(f'https://api.github.com/orgs/{ORG}/copilot/policy',
                     headers={'Authorization': f'Bearer {TOKEN}'})
    return r.json()

def set_policy(content_filter: str, allowed_models: list, training_opt_out: bool):
    r = requests.put(f'https://api.github.com/orgs/{ORG}/copilot/policy',
                     headers={'Authorization': f'Bearer {TOKEN}'},
                     json={
                         'content_filter': content_filter,
                         'allowed_models': allowed_models,
                         'training_opt_out': training_opt_out
                     })
    return r.json()

# Set strict policy for regulated org:
set_policy(
    content_filter='block',
    allowed_models=['gpt-5', 'claude'],  # only approved models
    training_opt_out=True
)

# Weekly policy audit
expected_policy = {
    'content_filter': 'block',
    'allowed_models': ['gpt-5', 'claude'],
    'training_opt_out': True
}

current = get_policy()
for key, expected_value in expected_policy.items():
    if current.get(key) != expected_value:
        alert(f'Policy drift detected: {key} is {current.get(key)}, expected {expected_value}')

Common Mistakes

• Setting policy once and never auditing — drift undetected.
• Over-restrictive model allowlist — devs can't use best model for task.
• Not enforcing training opt-out — compliance issue.
• No audit trail — can't prove policy to auditors.

Best Practices

• Set strict policy for regulated orgs (block, allowlist, opt-out).
• Audit weekly; alert on drift.
• Don't over-restrict models — leave enough for task variety.
• Log all policy changes.
• Use CI check to verify policy compliance.

Troubleshooting

Practical Exercise

Professional Challenge

Frequently Asked Questions

Further Reading

• Copilot org policy

Official References

• Copilot REST API

Related lessons: PR-09, PR-11