Add GitHub Copilot and Gemini OAuth support to coding-agent

[badlogic]

Implement full GitHub Copilot integration in coding-agent, including:

1. Generate GitHub Copilot models in @mariozechner/pi-ai

   • Update packages/ai/scripts/generate-models.ts to add github-copilot provider
   • Filter available models, exclude deprecated ones
   • Set API to openai-completions, add static headers
   • Update KnownProvider type

2. Implement device flow OAuth in packages/coding-agent

   • Create src/oauth/github-copilot.ts with loginGitHubCopilot() and refreshGitHubCopilotToken()
   • Update src/oauth/index.ts and src/model-config.ts to handle github-copilot

3. Add GitHub Copilot to TUI

   • Update src/tui/oauth-selector.ts to add github-copilot provider and show device flow UI
   • Update src/tui/tui-renderer.ts to show Copilot models
   • Update src/main.ts to add github-copilot to default providers

4. Test end-to-end

   • Login via TUI, select Copilot model, test chat and tool calls
   • Verify usage/cost tracking works

[kanishkave]

this one would be really appreciated

[mrairdon-midmark]

Copilot CLI is really too bad 😂😭😂

[KarmaMonk]

Yes, but Students and Educators have some free Tokens (300 Requests per month) for a lot of different models.

[renzo4web]

Yes, please, it would help a lot with what we have gh copilot.

[badlogic]

Gemini OAuth Implementation Analysis

I've completed a comprehensive analysis of how to implement Gemini OAuth support in pi-mono. Here's the detailed findings:

Gemini API Capabilities Confirmed

✅ System Prompts: Supported via getCoreSystemPrompt() in their implementation
✅ Tools/Function Calling: Full support including file operations, web search, and custom tools via @google/genai Tool type
✅ Content Generation: Streaming/non-streaming, token counting, embeddings, and context compression

Gemini OAuth Details

OAuth Configuration:

• Client ID and Secret: See google-gemini/gemini-cli oauth2.ts (public for installed apps per Google's OAuth docs)
• Scopes:
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/userinfo.email
  • https://www.googleapis.com/auth/userinfo.profile

API Endpoints (when using OAuth):

• Base URL: https://cloudcode-pa.googleapis.com
• API Version: v1internal
• Key methods: generateContent, streamGenerateContent, countTokens, embedContent

Implementation Plan

1. Add Gemini OAuth Provider (packages/coding-agent/src/core/oauth/gemini.ts)

   • Use google-auth-library for OAuth flow (different from Anthropic's manual implementation)
   • Support both web flow and device code flow (NO_BROWSER mode)
   • Store tokens in existing oauth.json format

2. Create Gemini OAuth API Provider (packages/ai/src/providers/gemini-oauth.ts)

   • Implement Provider interface
   • Use Code Assist API endpoints
   • Handle user tier information (FREE/STANDARD)

3. Update OAuth Infrastructure:

   • Add "gemini" to SupportedOAuthProvider type
   • Update model-config.ts to check Gemini OAuth tokens
   • Add gemini: "gemini" to providerToOAuthProvider mapping

4. Environment Variables:

   • GEMINI_OAUTH_TOKEN - Manual OAuth token override
   • GOOGLE_CLOUD_PROJECT - For project-specific features
   • NO_BROWSER - Force device code flow

Key Differences from Anthropic/GitHub Implementations

1. Uses Google's auth library instead of manual OAuth implementation
2. Multiple auth types supported (OAuth, API keys, ADC)
3. Includes user profile fetching and caching
4. Project context included in API calls
5. User tier management for rate limits

Dependencies

• google-auth-library: ^9.0.0

Full implementation details available in packages/coding-agent/docs/gemini.md.

[hjanuschka]

subscribe! 👍

[cmaas]

I looked into this for a bit. There seem to be other projects on GitHub that implement the OAuth flow for Copilot, for example this one: https://github.com/sosacrazy126/github-copilot-cli-chat/blob/797f7908a39ff6a843455378a4e2d6852528ff1a/src/auth/github-copilot.ts#L184

The flow is a bit different from Anthropic. For Copilot, it is: retrieve device code from API → copy from console, paste the code in the browser → (script polls for result or maybe wait until user hits return) → use GH token to generate a Copilot token, which manages refresh and caching apparently.

Hence, the /login method in pi needs some adjustments, because right now it expects the same flow as for Anthropic: open website, copy code and paste in CLI. A loginGitHubCopilot method needs to either print to the terminal or have another webhook that helps to print stuff, because you gotta print the device code to the terminal (preferrably without using console.log I guess?)

[Tiberriver256]

For copilot it'd probably be easier to start with fine-grained PAT tokens instead of OAuth.

Just going to leave these here as a handy reference:

copilot-auth-flow-demo.mjs - Set a GH_TOKEN env variable with a "Copilot Requests" PAT and run

copilot-auth-flow-demo.mjs

#!/usr/bin/env node
/**
 * GitHub Copilot CLI Authentication Flow Demo
 * ============================================
 * 
 * This script demonstrates the complete authentication flow that GitHub Copilot CLI
 * uses to convert a GH_TOKEN into authenticated Copilot API calls.
 * 
 * THE FLOW:
 * 1. Read GH_TOKEN from environment
 * 2. Query GitHub's GraphQL API to get user info and Copilot API endpoint
 * 3. List available models from the Copilot API
 * 4. Use the SAME token to make chat completion requests to the Copilot API
 * 
 * USAGE:
 *   export GH_TOKEN="ghp_your_token_here"  # or use a fine-grained PAT with Copilot permission
 *   node copilot-auth-flow-demo.mjs
 * 
 * REQUIREMENTS:
 *   - Node.js 18+ (for native fetch)
 *   - A GitHub token with Copilot access (fine-grained PAT with "Copilot Requests" permission)
 */

const GITHUB_API_HOST = "https://api.github.com";
const INTEGRATION_ID = "copilot-developer-cli";

// ============================================================================
// STEP 0: Get the GitHub token from environment
// ============================================================================
function getToken() {
    // The CLI checks these in priority order
    const token = process.env.COPILOT_GITHUB_TOKEN 
        || process.env.GH_TOKEN 
        || process.env.GITHUB_TOKEN;
    
    if (!token) {
        console.error(`
❌ No GitHub token found!

Please set one of these environment variables:
  export GH_TOKEN="your_token_here"
  export GITHUB_TOKEN="your_token_here"
  export COPILOT_GITHUB_TOKEN="your_token_here"

Your token needs:
  - Fine-Grained PAT with "Copilot Requests" permission enabled
  - OR an OAuth token from a user with Copilot subscription
`);
        process.exit(1);
    }
    
    console.log("✅ Step 0: Found GitHub token from environment");
    console.log(`   Token prefix: ${token.substring(0, 10)}...`);
    console.log(`   Token type: ${token.startsWith('ghp_') ? 'Classic PAT' : token.startsWith('github_pat_') ? 'Fine-Grained PAT' : 'OAuth/Other'}`);
    
    return token;
}

// ============================================================================
// STEP 1: Query GitHub GraphQL API for user info and Copilot endpoint
// ============================================================================
async function getCopilotEndpoint(token) {
    console.log("\n🔍 Step 1: Querying GitHub GraphQL API for Copilot endpoint...");
    
    const query = `
        {
            viewer {
                login
                copilotEndpoints {
                    api
                }
            }
        }
    `;
    
    const url = `${GITHUB_API_HOST}/graphql`;
    console.log(`   POST ${url}`);
    
    const response = await fetch(url, {
        method: "POST",
        headers: {
            "Authorization": `Bearer ${token}`,
            "Accept": "application/json",
            "Content-Type": "application/json",
        },
        body: JSON.stringify({ query }),
    });
    
    if (!response.ok) {
        const errorText = await response.text();
        console.error(`\n❌ GraphQL request failed: ${response.status} ${response.statusText}`);
        console.error(`   Response: ${errorText}`);
        
        if (response.status === 401) {
            console.error("\n   Your token may be invalid or expired.");
        }
        process.exit(1);
    }
    
    const data = await response.json();
    
    if (data.errors) {
        console.error("\n❌ GraphQL errors:", JSON.stringify(data.errors, null, 2));
        process.exit(1);
    }
    
    const { viewer } = data.data;
    const copilotApiUrl = viewer.copilotEndpoints?.api;
    
    console.log(`\n✅ Step 1 Complete!`);
    console.log(`   Logged in as: ${viewer.login}`);
    console.log(`   Copilot API endpoint: ${copilotApiUrl || '(not available)'}`);
    
    if (!copilotApiUrl) {
        console.error(`\n❌ No Copilot endpoint returned. This usually means:`);
        console.error(`   - Your account doesn't have Copilot access`);
        console.error(`   - Your token doesn't have the required permissions`);
        process.exit(1);
    }
    
    return { username: viewer.login, copilotApiUrl };
}

// ============================================================================
// STEP 2: List available models from the Copilot API
// ============================================================================
async function listModels(token, copilotApiUrl) {
    console.log("\n📋 Step 2: Listing available models from Copilot API...");
    
    const url = `${copilotApiUrl}/models`;
    console.log(`   GET ${url}`);
    
    const response = await fetch(url, {
        method: "GET",
        headers: {
            "Authorization": `Bearer ${token}`,
            "Copilot-Integration-Id": INTEGRATION_ID,
            "Accept": "application/json",
        },
    });
    
    if (!response.ok) {
        const errorText = await response.text();
        console.error(`\n❌ Failed to list models: ${response.status} ${response.statusText}`);
        console.error(`   Response: ${errorText}`);
        process.exit(1);
    }
    
    const data = await response.json();
    const models = data.models || data.data || data;
    
    console.log(`\n✅ Step 2 Complete! Found ${Array.isArray(models) ? models.length : 'unknown'} models`);
    
    if (Array.isArray(models) && models.length > 0) {
        console.log(`   Available models:`);
        models.slice(0, 10).forEach(m => {
            const name = m.id || m.name || m;
            console.log(`     - ${name}`);
        });
        if (models.length > 10) {
            console.log(`     ... and ${models.length - 10} more`);
        }
    }
    
    return models;
}

// ============================================================================
// STEP 3: Make an authenticated request to the Copilot API
// ============================================================================
async function callCopilotApi(token, copilotApiUrl, model) {
    console.log("\n🚀 Step 3: Making authenticated chat completion request...");
    
    const url = `${copilotApiUrl}/chat/completions`;
    
    const requestBody = {
        messages: [
            {
                role: "system",
                content: ""
            },
            {
                role: "user", 
                content: "What is the capital of France?"
            }
        ],
        model: model
    };
    
    console.log(`   POST ${url}`);
    console.log(`   Headers:`);
    console.log(`     Authorization: Bearer ${token.substring(0, 10)}...`);
    console.log(`     Copilot-Integration-Id: ${INTEGRATION_ID}`);
    console.log(`     Content-Type: application/json`);
    console.log(`   Body: ${JSON.stringify(requestBody, null, 2).split('\n').map((l, i) => i === 0 ? l : '         ' + l).join('\n')}`);
    
    const response = await fetch(url, {
        method: "POST",
        headers: {
            "Authorization": `Bearer ${token}`,
            "Copilot-Integration-Id": INTEGRATION_ID,
            "Content-Type": "application/json",
            "Accept": "application/json",
        },
        body: JSON.stringify(requestBody),
    });
    
    const responseText = await response.text();
    
    if (!response.ok) {
        console.error(`\n❌ Copilot API request failed: ${response.status} ${response.statusText}`);
        console.error(`   Response: ${responseText}`);
        
        if (response.status === 401 || response.status === 403) {
            console.error(`\n   Possible causes:`);
            console.error(`   - Token doesn't have "Copilot Requests" permission (for fine-grained PATs)`);
            console.error(`   - User doesn't have an active Copilot subscription`);
            console.error(`   - Classic PATs are not supported - use fine-grained PATs`);
        }
        process.exit(1);
    }
    
    let data;
    try {
        data = JSON.parse(responseText);
    } catch {
        data = responseText;
    }
    
    console.log(`\n✅ Step 3 Complete! Copilot API responded successfully.`);
    
    return data;
}

// ============================================================================
// MAIN: Run the complete flow
// ============================================================================
async function main() {
    console.log("=".repeat(70));
    console.log("  GitHub Copilot CLI Authentication Flow Demo");
    console.log("=".repeat(70));
    console.log(`
This demonstrates how the Copilot CLI authenticates:

  ┌─────────────────┐
  │    GH_TOKEN     │  (Your GitHub PAT or OAuth token)
  └────────┬────────┘
           │
           ▼
  ┌─────────────────────────────────────────────────────┐
  │  Step 1: GitHub GraphQL API                         │
  │  POST https://api.github.com/graphql                │
  │  Authorization: Bearer <GH_TOKEN>                   │
  │                                                     │
  │  Query: { viewer { login copilotEndpoints { api }}} │
  │  Returns: User info + Copilot API URL               │
  └────────┬────────────────────────────────────────────┘
           │
           ▼
  ┌─────────────────────────────────────────────────────┐
  │  Step 2: List Models                                │
  │  GET https://api.{tier}.githubcopilot.com/models    │
  │  Authorization: Bearer <GH_TOKEN>  (same token!)    │
  │  Returns: Available models for your subscription    │
  └────────┬────────────────────────────────────────────┘
           │
           ▼
  ┌─────────────────────────────────────────────────────┐
  │  Step 3: Chat Completion                            │
  │  POST .../chat/completions                          │
  │  Authorization: Bearer <GH_TOKEN>  (same token!)    │
  │  Copilot-Integration-Id: copilot-developer-cli      │
  │                                                     │
  │  The Copilot API accepts GitHub tokens directly     │
  │  because it shares GitHub's auth backend.           │
  └─────────────────────────────────────────────────────┘
`);

    // Step 0: Get token
    const token = getToken();
    
    // Step 1: Get Copilot endpoint via GraphQL
    const { username, copilotApiUrl } = await getCopilotEndpoint(token);
    
    // Step 2: List available models
    const models = await listModels(token, copilotApiUrl);
    
    // Pick a model to use
    let modelToUse = "gpt-4o"; // default fallback
    if (Array.isArray(models) && models.length > 0) {
        // Try to find a good chat model
        const preferredModels = ["gpt-4o", "gpt-4", "gpt-3.5-turbo", "claude-3.5-sonnet"];
        for (const preferred of preferredModels) {
            const found = models.find(m => {
                const id = m.id || m.name || m;
                return id.toLowerCase().includes(preferred.toLowerCase());
            });
            if (found) {
                modelToUse = found.id || found.name || found;
                break;
            }
        }
        // If no preferred model found, use the first one
        if (modelToUse === "gpt-4o" && models[0]) {
            modelToUse = models[0].id || models[0].name || models[0];
        }
    }
    console.log(`\n   Selected model: ${modelToUse}`);
    
    // Step 3: Call Copilot API
    const result = await callCopilotApi(token, copilotApiUrl, modelToUse);
    
    // Display result
    console.log("\n" + "=".repeat(70));
    console.log("  RESULT");
    console.log("=".repeat(70));
    
    if (result.choices && result.choices[0]?.message?.content) {
        console.log(`\n🤖 Copilot's response:`);
        console.log(`   "${result.choices[0].message.content}"`);
    } else {
        console.log(`\n📦 Raw response:`);
        console.log(JSON.stringify(result, null, 2));
    }
    
    console.log(`\n` + "=".repeat(70));
    console.log(`  SUCCESS! The authentication flow works.`);
    console.log("=".repeat(70));
    console.log(`
Summary:
  ✅ Token read from environment variable
  ✅ GraphQL query returned user "${username}" and Copilot endpoint
  ✅ Listed available models from Copilot API
  ✅ Same token used to authenticate chat completion request
  ✅ Copilot API accepted the request and returned a response

Key insight: The GitHub token is used DIRECTLY with the Copilot API.
There's no token exchange - GitHub's auth backend is shared.
`);
}

main().catch(err => {
    console.error("\n💥 Unexpected error:", err.message);
    process.exit(1);
});

Opus 4.5 take on how the copilot CLI does the auths stuff

How GitHub Copilot CLI Does Authentication

Executive Summary

GitHub Copilot CLI implements a sophisticated multi-method authentication system that supports six distinct authentication types, prioritized in a specific order. The system leverages native OS credential storage via keytar.node, GitHub's OAuth Device Flow, environment variables, and the GitHub CLI (gh).

---

1. Authentication Types Hierarchy

The CLI defines an AuthInfo union type supporting six authentication methods:

type AuthInfo = HMACAuthInfo | EnvAuthInfo | UserAuthInfo | GhCliAuthInfo | ApiKeyAuthInfo | TokenAuthInfo;

1.1 HMAC Authentication (HMACAuthInfo)

• Type: "hmac"
• Purpose: Server-to-server authentication for enterprise/internal deployments
• Source: Environment variables CAPI_HMAC_KEY or COPILOT_HMAC_KEY
• Use Case: Automated CI/CD pipelines, GitHub Codespaces, enterprise deployments
• Display: "Logged in with HMAC" / "Unknown (via HMAC)"

1.2 Environment Token Authentication (EnvAuthInfo)

• Type: "env"
• Properties: host, login, token, envVar
• Priority Order:
  1. COPILOT_GITHUB_TOKEN
  2. GH_TOKEN
  3. GITHUB_TOKEN
  4. GITHUB_ASKPASS
• Use Case: CI environments, GitHub Actions, automated scripts
• Display: "Logged in with {envVar} as user: {login}"

1.3 User OAuth Authentication (UserAuthInfo)

• Type: "user"
• Properties: host, login
• Token Storage: Native OS keychain via keytar.node
• Use Case: Interactive user sessions (primary method)
• Display: "Logged in as user: {login}"

1.4 GitHub CLI Authentication (GhCliAuthInfo)

• Type: "gh-cli"
• Properties: host, login, token
• Source: Leverages existing gh auth credentials
• Use Case: Users already authenticated with GitHub CLI
• Display: "Logged in with gh as user: {login}"

1.5 API Key Authentication (ApiKeyAuthInfo)

• Type: "api-key"
• Properties: apiKey, host
• Use Case: Direct API key access for specific integrations
• Display: "Logged in with API key to {host}"

1.6 Direct Token Authentication (TokenAuthInfo)

• Type: "token"
• Properties: host, token
• Use Case: SDK programmatic access
• Display: "Logged in with token to {host}"

---

2. Authentication Flow

2.1 Authentication State Manager

The CLI maintains a central AuthManager class that:

• Tracks current authentication state (currentAuthInfo)
• Manages authentication callbacks for state changes
• Implements priority-based authentication method resolution

2.2 Authentication Priority Resolution

When loadAuthInfo() is called, methods are tried in this order:

1. HMAC Key Check: CAPI_HMAC_KEY or COPILOT_HMAC_KEY
2. GitHub Token Login: COPILOT_GITHUB_TOKEN > GH_TOKEN > GITHUB_TOKEN > GITHUB_ASKPASS
3. API Key Check: Direct API key if configured
4. User OAuth: Native keychain-stored tokens
5. GitHub CLI: Existing gh auth session

async loadAuthInfo() {
    let n = this.getPrioritizedAuthMethods(false);
    for (let r of n) {
        let l = await r();
        if (l.length > 0) {
            let { authInfo: a, token: s } = l[0];
            this.currentAuthInfo = a;
            await this.notifyAuthChange(a, s);
            return;
        }
    }
}

---

3. Token-to-Copilot-API Flow (Critical Path)

3.1 How GH_TOKEN Becomes Copilot API Access

This is the key mechanism: A GitHub token (PAT or OAuth token) does NOT directly authenticate to api.githubcopilot.com. Instead, the CLI uses a two-step process:

Step 1: Query GitHub's GraphQL API for Copilot Endpoint

The CLI calls GitHub's GraphQL API (/graphql) with the user's GitHub token to discover their personalized Copilot API endpoint:

async function WN(host, token, logger) {
    let query = `
      {
        viewer {
          login
          copilotEndpoints {
            api
          }
        }
      }
    `;
    
    let url = new URL("/graphql", host);  // e.g., https://api.github.com/graphql
    let response = await fetch(url.href, {
        method: "POST",
        headers: { 
            Authorization: `Bearer ${token}`,  // GH_TOKEN used here
            Accept: "application/json" 
        },
        body: JSON.stringify({ query }),
    });
    
    let { viewer } = (await response.json()).data;
    return viewer.copilotEndpoints.api;  // Returns: https://api.githubcopilot.com (or tier-specific URL)
}

Step 2: Create Copilot Client with OAuth Token

Once the endpoint is discovered, the CLI creates a Copilot API client using the same GitHub token:

let copilotApiUrl = await WN(host, token, logger);  // Step 1: Get endpoint
let client = CopilotClient.createWithOAuthToken(
    logger,
    copilotApiUrl,           // e.g., https://api.githubcopilot.com
    integrationId,
    token,                   // Same GH_TOKEN used for Bearer auth
    sessionId
);

The Complete Flow Diagram

┌──────────────────┐
│  GH_TOKEN        │
│  (GitHub PAT)    │
└────────┬─────────┘
         │
         ▼
┌──────────────────────────────────────────────────────┐
│  Step 1: GitHub GraphQL API                          │
│  POST https://api.github.com/graphql                 │
│  Authorization: Bearer <GH_TOKEN>                    │
│                                                      │
│  Query: { viewer { login copilotEndpoints { api } }} │
│                                                      │
│  Response: {                                         │
│    viewer: {                                         │
│      login: "username",                              │
│      copilotEndpoints: {                             │
│        api: "https://api.githubcopilot.com"          │
│      }                                               │
│    }                                                 │
│  }                                                   │
└────────┬─────────────────────────────────────────────┘
         │
         ▼
┌──────────────────────────────────────────────────────┐
│  Step 2: Copilot API Calls                           │
│  POST https://api.githubcopilot.com/chat/completions │
│  Authorization: Bearer <GH_TOKEN>                    │
│  Copilot-Integration-Id: <integration_id>            │
│                                                      │
│  (Same token is reused - GitHub's backend validates  │
│   the token and Copilot entitlements)                │
└──────────────────────────────────────────────────────┘

3.2 Why This Works

The Copilot API (api.githubcopilot.com) accepts GitHub OAuth tokens directly because:

1. Shared Authentication Backend: GitHub's authentication system validates the token
2. Entitlement Check: The Copilot API verifies the user has an active Copilot subscription
3. Tier Routing: The GraphQL query returns the appropriate API endpoint based on the user's subscription tier (individual, business, enterprise)

3.3 Token Requirements

For a GH_TOKEN to work with Copilot CLI, the token must have:

• Fine-Grained PAT: "Copilot Requests" permission enabled
• Classic PAT: Not supported (will fail with permission error)
• OAuth Token: Standard scopes work if user has Copilot subscription

Error message for invalid PAT:

"The provided personal access token (PAT) does not have Copilot Requests permission. 
Please generate a new Fine-Grained Access Token with Copilot Requests permission 
(not a Classic token), or log in using /login"

3.4 The Copilot-Integration-Id Header

Every request to the Copilot API includes a Copilot-Integration-Id header that identifies which client/application is making the request.

What It Is

The Integration ID is a string identifier that tells GitHub's Copilot backend which application or integration is making API requests. This enables:

1. Usage Tracking: GitHub can track API usage per client application
2. Feature Gating: Different clients may have access to different features or models
3. Rate Limiting: Separate rate limits can be applied per integration
4. Analytics: GitHub can analyze usage patterns across different clients
5. Billing: For enterprise scenarios, usage can be attributed to specific integrations

Default Value for CLI

The Copilot CLI uses a default integration ID:

const integrationId = process.env.GITHUB_COPILOT_INTEGRATION_ID || "copilot-developer-cli";

How It's Used in Requests

The Integration ID is included as an HTTP header in all Copilot API calls:

headers: {
    "Authorization": `Bearer ${token}`,
    "Copilot-Integration-Id": integrationId,  // e.g., "copilot-developer-cli"
    "X-Interaction-Id": interactionId,        // Optional: tracks specific interactions
}

Configuration

The Integration ID can be configured via:

Source	Priority
Config file (copilot_integration_id)	1 (highest)
Environment variable (GITHUB_COPILOT_INTEGRATION_ID)	2
Default value ("copilot-developer-cli")	3 (fallback)

Known Integration IDs

Different GitHub Copilot clients use different Integration IDs:

Client	Integration ID
Copilot CLI	copilot-developer-cli
VS Code Extension	vscode-chat (or similar)
GitHub.com Chat	dotcom-chat
JetBrains Plugin	jetbrains
Custom/SDK	User-defined

Example Request Flow

POST https://api.githubcopilot.com/chat/completions
Headers:
  Authorization: Bearer ghp_xxxxxxxxxxxx
  Copilot-Integration-Id: copilot-developer-cli
  Content-Type: application/json

Body:
  {
    "model": "gpt-4o",
    "messages": [...]
  }

The Copilot-Integration-Id helps GitHub's backend understand that this request originated from the CLI tool, enabling appropriate feature access and usage attribution.

---

4. OAuth Device Flow Implementation

4.1 Device Code Flow

When user authentication is required, the CLI implements GitHub's OAuth Device Flow:

Endpoint Configuration:

Purpose	URL
Device Code Request	https://github.com/login/device/code
Token Exchange	https://github.com/login/oauth/access_token
Client ID	Ov23ctDVkRmgkPke0Mmm

Flow:

1. Request device code from GitHub
2. Display user_code and verification_uri to user
3. User visits URL and enters code
4. CLI polls for authorization completion
5. On success, receive access_token
6. Store token in native keychain
7. Use token to query GraphQL for Copilot endpoint (see Section 3)

// Token exchange request
body: new URLSearchParams({
    client_id: "Ov23ctDVkRmgkPke0Mmm",
    device_code: deviceCode,
    grant_type: "urn:ietf:params:oauth:grant-type:device_code",
}),

4.2 User Authentication Verification

After obtaining a token, the CLI verifies it via the same GraphQL query used for endpoint discovery (Section 3.1):

query {
    viewer {
        login
        copilotEndpoints {
            api
        }
    }
}

This simultaneously:

• Validates the token
• Retrieves the user's login name
• Gets the user's Copilot API endpoint URL (the critical piece for API calls)

---

5. Native Token Storage

5.1 Keytar Integration

The CLI uses native OS credential storage through keytar.node prebuilt binaries:

Supported Platforms:

Platform	Binary Location
macOS Apple Silicon	prebuilds/darwin-arm64/keytar.node
macOS Intel	prebuilds/darwin-x64/keytar.node
Linux ARM64	prebuilds/linux-arm64/keytar.node
Linux x64	prebuilds/linux-x64/keytar.node
Windows ARM64	prebuilds/win32-arm64/keytar.node
Windows x64	prebuilds/win32-x64/keytar.node

Service Name: copilot-cli

Storage Functions:

// Token Storage Module (zk)
{
    getToken: async (host, login) => {...},
    getAnyToken: async () => {...},
    removeToken: async (host, login) => {...},
    storeToken: async (host, login, token) => {...},
    storeCurrentTokenInConfig: async (host, login) => {...}
}

5.2 Account Identification

Tokens are stored using a composite key pattern:

function getAccountKey(host, login) {
    if (!host || !login) return undefined;
    return `${host}:${login}`;
}

5.3 OS-Specific Backends

Platform	Backend
Windows	Windows Credential Manager (wincred)
macOS	Keychain Services
Linux	libsecret (via Secret Service API)

Error Handling:

"The system vault (keychain, keyring, password manager, etc.) is not available. 
 You may need to install one."

---

6. Copilot API Integration

6.1 API Endpoints

Purpose	Endpoint
Default API	https://api.githubcopilot.com
Enterprise	https://api.enterprise.githubcopilot.com
Business	https://api.business.githubcopilot.com
Individual	https://api.individual.githubcopilot.com
MCP Server	https://api.githubcopilot.com/mcp/readonly

6.2 Request Authentication Headers

For OAuth token authentication:

Authorization: Bearer <token>
Copilot-Integration-Id: <integration_id>
X-Interaction-Id: <interaction_id>
User-Agent: <user_agent>

For HMAC authentication:

• Uses HMAC-signed requests with the CAPI_HMAC_KEY
• Includes GITHUB_USER_ID when available

6.3 Client Creation

// With OAuth token
"Creating copilot-client for integration ID ${integrationId} with token authentication"

// With HMAC key
"Creating copilot-client for integration ID ${integrationId} with HMAC key authentication"

---

7. GitHub CLI Integration

7.1 Token Retrieval from gh

The CLI can leverage existing GitHub CLI authentication:

async tryGhCliLogin() {
    // Attempts to retrieve token from gh auth
    let token = await ghCliGetToken();
    if (token) {
        return [{ 
            authInfo: { type: "gh-cli", host, login, token },
            token
        }];
    }
}

7.2 Git Credential Helper

For git operations, the CLI configures credential helpers:

# Credential helper script
'!f() { test "$1" = get && echo "password=$GITHUB_TOKEN"; }; f'

Git configuration:

git config credential.username <username>
git config credential.helper '!f() { test "$1" = get && echo "password=$GITHUB_TOKEN"; }; f'

---

8. Personal Access Token (PAT) Support

8.1 Fine-Grained PAT Requirements

Users can authenticate with a fine-grained PAT requiring:

• Permission: "Copilot Requests" enabled
• Generation URL: https://github.com/settings/personal-access-tokens/new

8.2 Environment Variable Configuration

Set via:

export GH_TOKEN=<your_pat>
# or
export GITHUB_TOKEN=<your_pat>

---

9. Session Management

9.1 Session Options

interface SessionOptions {
    authInfo?: AuthInfo;
    copilotUrl?: string;
    integrationId?: string;
    // ...other options
}

9.2 Runtime Settings

The IRuntimeSettings interface includes comprehensive API configuration:

interface IRuntimeSettings {
    api: {
        copilot: {
            url: string;
            integrationId: string;
            hmacKey: string;
            token: string;
            useSessions: boolean;
            sessionId: string;
            previousSessionIds: string[];
        };
        github: {
            mcpServerToken: string;
        };
    };
}

---

10. Error Handling & Recovery

10.1 Authentication Errors

The CLI handles various authentication failures:

// Token expiration detection
if (t.message.includes("no Copilot API key provided") ||
    t.message.includes("fatal error getting model")) {
    // Trigger re-authentication
}

10.2 Logout Flow

async logout() {
    if (!this.currentAuthInfo) return false;
    
    await handleAuthType(this.currentAuthInfo, {
        onHMACAuthInfo: async () => false,  // Cannot logout
        onEnvAuthInfo: async () => false,   // Cannot logout  
        onUserAuthInfo: async (n) => {
            await tokenStore.removeToken(n.host, n.login);
            // Remove from keychain
        },
        onGhCliAuthInfo: async () => false, // Cannot logout
        onApiKeyAuthInfo: async () => false, // Cannot logout
        onTokenAuthInfo: async () => false,  // Cannot logout
    });
    
    await this.notifyAuthChange(null);
}

---

11. Security Considerations

11.1 Secret Filtering

The CLI implements secret filtering for logs:

filterSecrets(messageOrError: string | Error): string | Error

Filtered patterns include:

• JWT tokens (eyJ...)
• Bearer tokens
• Personal access tokens (gh[pousr]_...)
• Various password patterns

11.2 Sensitive Environment Variables

const sensitiveEnvVars = [
    "GITHUB_TOKEN",
    "COPILOT_GITHUB_TOKEN",
    "GITHUB_COPILOT_API_TOKEN",
    "CAPI_HMAC_KEY",
    "CAPI_HMAC_KEY_OVERRIDE",
    "ANTHROPIC_API_KEY",
];

---

12. SDK Authentication API

12.1 Public Exports

// Get available models (requires auth)
export function getAvailableModels(
    authInfo: AuthInfo, 
    integrationId?: string, 
    logger?: RunnerLogger
): Promise<readonly ModelMetadata[]>;

// Retrieve models with full details
export function retrieveAvailableModels(
    authInfo: AuthInfo, 
    integrationId?: string, 
    sessionId?: string, 
    logger?: RunnerLogger
): Promise<Model[]>;

// Get custom agents
export function getCustomAgents(
    authInfo: AuthInfo, 
    workingDir: string, 
    integrationId?: string, 
    logger?: RunnerLogger
): Promise<SweCustomAgent[]>;

12.2 Session Authentication

class Session {
    protected authInfo?: AuthInfo;
    
    setAuthInfo(authInfo: AuthInfo | undefined): void;
    // Updates authentication for the session
}

---

13. Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                    Copilot CLI Authentication                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
│  │    HMAC     │    │  Env Token  │    │ User OAuth  │         │
│  │  (Server)   │    │ (CI/Env)    │    │ (Primary)   │         │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘         │
│         │                  │                  │                  │
│         └──────────────────┼──────────────────┘                  │
│                            │                                     │
│                   ┌────────▼────────┐                           │
│                   │  AuthManager    │                           │
│                   │  (Priority      │                           │
│                   │   Resolution)   │                           │
│                   └────────┬────────┘                           │
│                            │                                     │
│         ┌──────────────────┼──────────────────┐                 │
│         │                  │                  │                  │
│  ┌──────▼──────┐    ┌──────▼──────┐    ┌──────▼──────┐         │
│  │  gh CLI     │    │  API Key    │    │   Token     │         │
│  │  (Reuse)    │    │  (Direct)   │    │   (SDK)     │         │
│  └─────────────┘    └─────────────┘    └─────────────┘         │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    Token Storage                          │  │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────────────────────┐   │  │
│  │  │ Windows │  │  macOS  │  │        Linux            │   │  │
│  │  │Credential│  │Keychain │  │ libsecret/Secret Service│   │  │
│  │  │ Manager │  │Services │  │                         │   │  │
│  │  └─────────┘  └─────────┘  └─────────────────────────┘   │  │
│  │                     via keytar.node                       │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                 API Endpoints                             │  │
│  │  • https://api.githubcopilot.com (default)               │  │
│  │  • https://api.{tier}.githubcopilot.com (enterprise/biz) │  │
│  │  • https://github.com/login/device/code (OAuth)          │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

14. Quick Reference

Environment Variables

Variable	Purpose	Priority
CAPI_HMAC_KEY	HMAC server auth	1 (highest)
COPILOT_HMAC_KEY	HMAC server auth (alt)	1
COPILOT_GITHUB_TOKEN	GitHub token	2
GH_TOKEN	GitHub token	3
GITHUB_TOKEN	GitHub token	4
GITHUB_ASKPASS	Git credential helper	5
COPILOT_API_URL	Custom API endpoint	N/A
GITHUB_COPILOT_INTEGRATION_ID	Integration ID	N/A

Slash Commands

Command	Description
/login	Initiate OAuth device flow authentication
/logout	Remove stored credentials (user auth only)

Key Files

File	Purpose
index.js	Main bundled CLI application
sdk/index.js	SDK exports for programmatic use
sdk/index.d.ts	TypeScript type definitions
prebuilds/*/keytar.node	Native credential storage bindings