home / skills / vm0-ai / vm0-skills / github-copilot

github-copilot skill

safe

This skill helps manage GitHub Copilot subscriptions and usage metrics via REST API, simplifying seat administration and adoption monitoring for organizations.

npx playbooks add skill vm0-ai/vm0-skills --skill github-copilot

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

7.6 KB

---
name: github-copilot
description: GitHub Copilot REST API via curl. Use this skill to manage Copilot subscriptions and retrieve usage metrics.
vm0_secrets:
  - GITHUB_TOKEN
---

# GitHub Copilot API

Use the GitHub Copilot REST API via direct `curl` calls to **manage Copilot subscriptions and retrieve usage metrics** for your organization.

> Official docs: `https://docs.github.com/en/rest/copilot`

**Note:** This API is for managing Copilot subscriptions and viewing metrics, not for code generation.

---

## When to Use

Use this skill when you need to:

- **Manage Copilot seat assignments** (add/remove users and teams)
- **View Copilot billing information** for an organization
- **Retrieve usage metrics** (active users, code completions, chat usage)
- **Monitor Copilot adoption** across teams
- **Audit Copilot usage** for compliance

---

## Prerequisites

1. You need a GitHub organization with Copilot Business or Enterprise
2. Generate a Personal Access Token (PAT) or use a GitHub App
3. Required permissions: `manage_billing:copilot` or `admin:org`
4. Store your token in the environment variable `GITHUB_TOKEN`

```bash
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
```

### Token Permissions

- `manage_billing:copilot` - For billing and seat management
- `read:org` - For reading organization data
- `admin:org` - For adding/removing users and teams

---


> **Important:** When using `$VAR` in a command that pipes to another command, wrap the command containing `$VAR` in `bash -c '...'`. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
> ```bash
> bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'
> ```

## How to Use

All examples below assume you have `GITHUB_TOKEN` set.

Base URL: `https://api.github.com`

**Required headers:**
- `Authorization: Bearer ${GITHUB_TOKEN}`
- `Accept: application/vnd.github+json`
- `X-GitHub-Api-Version: 2022-11-28`

---

### 1. Get Copilot Billing Information

Get seat breakdown and settings for an organization. Replace `your-org-name` with your organization name:

```bash
bash -c 'curl -s -X GET "https://api.github.com/orgs/your-org-name/copilot/billing" --header "Authorization: Bearer ${GITHUB_TOKEN}" --header "Accept: application/vnd.github+json" --header "X-GitHub-Api-Version: 2022-11-28"'
```

**Response:**
```json
{
  "seat_breakdown": {
  "total": 12,
  "added_this_cycle": 2,
  "pending_cancellation": 0,
  "pending_invitation": 1,
  "active_this_cycle": 12,
  "inactive_this_cycle": 0
  },
  "seat_management_setting": "assign_selected",
  "public_code_suggestions": "block"
}
```

---

### 2. List All Copilot Seat Assignments

Get all users with Copilot seats. Replace `your-org-name` with your organization name:

```bash
bash -c 'curl -s -X GET "https://api.github.com/orgs/your-org-name/copilot/billing/seats?per_page=50" --header "Authorization: Bearer ${GITHUB_TOKEN}" --header "Accept: application/vnd.github+json" --header "X-GitHub-Api-Version: 2022-11-28"' | jq '.seats[] | {login: .assignee.login, last_activity: .last_activity_at}'
```

---

### 3. Get Copilot Seat Details for a User

Get specific user's Copilot seat information. Replace `your-org-name` with your organization name and `username` with the target username:

```bash
bash -c 'curl -s -X GET "https://api.github.com/orgs/your-org-name/members/username/copilot" --header "Authorization: Bearer ${GITHUB_TOKEN}" --header "Accept: application/vnd.github+json" --header "X-GitHub-Api-Version: 2022-11-28"'
```

---

### 4. Add Users to Copilot Subscription

Assign Copilot seats to specific users. Replace `your-org-name` with your organization name:

Write to `/tmp/github_copilot_request.json`:

```json
{
  "selected_usernames": ["user1", "user2"]
}
```

Then run:

```bash
bash -c 'curl -s -X POST "https://api.github.com/orgs/your-org-name/copilot/billing/selected_users" --header "Authorization: Bearer ${GITHUB_TOKEN}" --header "Accept: application/vnd.github+json" --header "X-GitHub-Api-Version: 2022-11-28" --header "Content-Type: application/json" -d @/tmp/github_copilot_request.json'
```

**Response:**
```json
{
  "seats_created": 2
}
```

---

### 5. Remove Users from Copilot Subscription

Remove Copilot seats from specific users. Replace `your-org-name` with your organization name:

Write to `/tmp/github_copilot_request.json`:

```json
{
  "selected_usernames": ["user1", "user2"]
}
```

Then run:

```bash
bash -c 'curl -s -X DELETE "https://api.github.com/orgs/your-org-name/copilot/billing/selected_users" --header "Authorization: Bearer ${GITHUB_TOKEN}" --header "Accept: application/vnd.github+json" --header "X-GitHub-Api-Version: 2022-11-28" --header "Content-Type: application/json" -d @/tmp/github_copilot_request.json'
```

**Response:**
```json
{
  "seats_cancelled": 2
}
```

---

### 6. Add Teams to Copilot Subscription

Assign Copilot to entire teams. Replace `your-org-name` with your organization name:

Write to `/tmp/github_copilot_request.json`:

```json
{
  "selected_teams": ["engineering", "design"]
}
```

Then run:

```bash
bash -c 'curl -s -X POST "https://api.github.com/orgs/your-org-name/copilot/billing/selected_teams" --header "Authorization: Bearer ${GITHUB_TOKEN}" --header "Accept: application/vnd.github+json" --header "X-GitHub-Api-Version: 2022-11-28" --header "Content-Type: application/json" -d @/tmp/github_copilot_request.json'
```

---

### 7. Remove Teams from Copilot Subscription

Remove Copilot from teams. Replace `your-org-name` with your organization name:

Write to `/tmp/github_copilot_request.json`:

```json
{
  "selected_teams": ["engineering"]
}
```

Then run:

```bash
bash -c 'curl -s -X DELETE "https://api.github.com/orgs/your-org-name/copilot/billing/selected_teams" --header "Authorization: Bearer ${GITHUB_TOKEN}" --header "Accept: application/vnd.github+json" --header "X-GitHub-Api-Version: 2022-11-28" --header "Content-Type: application/json" -d @/tmp/github_copilot_request.json'
```

---

### 8. Get Copilot Usage Metrics for Organization

Get usage statistics (requires 5+ active users). Replace `your-org-name` with your organization name:

```bash
bash -c 'curl -s -X GET "https://api.github.com/orgs/your-org-name/copilot/metrics?per_page=7" --header "Authorization: Bearer ${GITHUB_TOKEN}" --header "Accept: application/vnd.github+json" --header "X-GitHub-Api-Version: 2022-11-28"' | jq '.[] | {date, total_active_users, total_engaged_users}'
```

**Response:**
```json
{
  "date": "2024-06-24",
  "total_active_users": 24,
  "total_engaged_users": 20
}
```

---

### 9. Get Copilot Metrics for a Team

Get team-specific usage metrics. Replace `your-org-name` with your organization name and `team-name` with the target team:

```bash
bash -c 'curl -s -X GET "https://api.github.com/orgs/your-org-name/team/team-name/copilot/metrics" --header "Authorization: Bearer ${GITHUB_TOKEN}" --header "Accept: application/vnd.github+json" --header "X-GitHub-Api-Version: 2022-11-28"'
```

---

## Metrics Data Structure

The metrics response includes:

| Field | Description |
|-------|-------------|
| `total_active_users` | Users with Copilot activity |
| `total_engaged_users` | Users who accepted suggestions |
| `copilot_ide_code_completions` | Code completion stats by language/editor |
| `copilot_ide_chat` | IDE chat usage stats |
| `copilot_dotcom_chat` | GitHub.com chat usage |
| `copilot_dotcom_pull_requests` | PR summary usage |

---

## Guidelines

1. **Requires Copilot Business/Enterprise**: Free tier users cannot use this API
2. **Metrics need 5+ users**: Usage metrics only available with 5+ active Copilot users
3. **Data retention**: Metrics available for up to 100 days
4. **Rate limits**: Standard GitHub API rate limits apply
5. **API in preview**: Some endpoints may change

Overview

This skill provides ready-to-run curl examples for the GitHub Copilot REST API to manage Copilot subscriptions and retrieve usage metrics for organizations. It focuses on seat and team assignment, billing information, and per-organization or per-team usage metrics. Use it when you need scripted, shell-based access to Copilot administration without SDKs.

How this skill works

The skill uses authenticated curl calls against the GitHub REST API (https://api.github.com) with a Personal Access Token stored in GITHUB_TOKEN. It issues endpoints for billing, seat assignment, team assignment, and metrics, and returns JSON responses that you can pipe into jq for quick parsing. When piping, wrap commands in bash -c '...' to preserve environment variables.

When to use it

Add or remove individual Copilot seats for users in an organization
Assign or revoke Copilot access for entire teams
Query billing and seat breakdowns for cost and compliance reviews
Retrieve usage metrics to monitor adoption and engagement
Automate periodic audits or reporting in CI/CD pipelines

Best practices

Store tokens in GITHUB_TOKEN and avoid embedding PATs in scripts
Use required headers: Authorization, Accept: application/vnd.github+json, X-GitHub-Api-Version
Wrap piped curl commands in bash -c '...' so environment variables remain available
Limit metrics queries to organizations with 5+ active users (metric requirement)
Respect GitHub API rate limits and cache results when possible

Example use cases

Script a monthly report of active and engaged Copilot users across teams using the metrics endpoint
Bulk-assign Copilot seats to new hires by posting selected_usernames
Revoke seats for offboarded employees via the DELETE selected_users endpoint
Enable Copilot for an entire engineering team using selected_teams
Audit seat allocation and billing settings before renewing licenses

FAQ

What permissions does the token need?

Use a PAT or GitHub App with manage_billing:copilot for billing and seat changes; admin:org or read:org may be required for organization and team operations.

Are usage metrics always available?

No. Metrics require at least 5 active Copilot users and are retained for up to 100 days; otherwise the endpoint may return limited or no data.