Auth and Bundling Scenarios

[patniko]

GitHub Copilot CLI SDK Auth & Bundling

Overview

The GitHub Copilot SDK provides a shim for Go, Python, TypeScript, and .NET that allows developers to create CLI sessions and access Copilot capabilities programmatically. This guide covers the authentication patterns, bundling strategies, and version management approaches for different integration scenarios.

Integration Scenarios

The SDK supports four primary integration patterns, each with distinct authentication and distribution requirements.

Scenario	Users	Authentication	Distribution	Complexity
Hobby Apps	Single developer	Local CLI login	Local only	Low
Internal Apps	Team/Org users	GitHub OAuth per user	Internal deployment	Medium
Backend Services	External customers	Token pass-through or BYOK	Server deployment	High
Desktop Apps	End customers	Embedded OAuth or token exchange	Bundled installer	High

---

Scenario 1: Hobby and Personal Applications

This is the simplest integration pattern, designed for individual developers building personal projects on their local machine.

Use Case

A developer wants to add agentic AI capabilities to a side project, personal tool, or learning experiment. The app runs only on their machine and uses their personal GitHub Copilot subscription.

Authentication Flow

1. Developer installs the Copilot CLI and authenticates via copilot auth login
2. SDK is configured with explicit flag: useLoggedInUser: true
3. SDK detects and uses the CLI's authenticated session
4. All API calls use the developer's Copilot rate limits

SDK Configuration

// TypeScript example
const session = await CopilotSDK.createSession({
  useLoggedInUser: true  // Explicit opt-in required
});

Considerations

• Rate limits: Uses individual Copilot subscription limits, not designed for high-volume usage
• Single user: Only the authenticated developer can use the app
• Local only: Not suitable for deployment to servers or distribution to others
• CLI dependency: Requires CLI to be installed and authenticated on the machine

---

Scenario 2: Internal Enterprise Applications

For teams building internal tools where multiple users in an organization need to access the same application using their own GitHub identities.

Use Case

A development team creates an internal code review assistant or documentation generator. Team members sign in with their GitHub accounts, and each user's actions are attributed to their identity with their individual rate limits.

Authentication Flow

1. Application implements "Sign in with GitHub" using standard GitHub OAuth
2. User authenticates and grants required scopes
3. Application receives OAuth access token
4. Token is passed to SDK for session creation
5. SDK uses the signed-in user's identity, not the app creator's

GitHub OAuth Setup

1. Register an OAuth App in your GitHub organization settings
2. Configure callback URL for your internal application
3. Request appropriate scopes (consult SDK documentation for required scopes)

SDK Configuration

const session = await CopilotSDK.createSession({
  githubToken: userOAuthToken  // Token from OAuth flow
});

CLI Lockdown Mode

When deploying internal applications, you should ensure the CLI on the deployment machine does not accidentally use a different authenticated account. Configure the SDK to never fall back to logged-in users:

const session = await CopilotSDK.createSession({
  githubToken: userOAuthToken,
  useLoggedInUser: false  // Explicit: never use CLI auth
});

Considerations

• User attribution: Each user's actions are tracked against their own identity
• Rate limits: Each user consumes their own Copilot subscription limits
• Token security: Store tokens securely, implement proper session management
• Scope management: Request minimum required OAuth scopes

---

Scenario 3: Production Backend Services

For production services that need to handle requests at scale, either passing through customer identities or using centralized API credentials.

Use Case

A SaaS platform integrates Copilot capabilities into their product. They need to either let customers use their own GitHub identities or manage API access centrally for all customers.

Option A: GitHub Token Pass-Through

In this model, your customers authenticate with GitHub, and their tokens are passed through your infrastructure to the SDK.

1. Customer clicks "Login with GitHub" in your application
2. Your app receives their GitHub OAuth token
3. Token is securely passed to your backend
4. Backend passes token to SDK when creating sessions
5. Customer uses their own GitHub/Copilot rate limits

// Backend service code
const session = await CopilotSDK.createSession({
  githubToken: customerToken,  // Pass-through from customer
  useLoggedInUser: false
});

Option B: Bring Your Own Key (BYOK)

Use your own API credentials from OpenAI, Anthropic, or Azure AI Foundry. This provides enterprise-grade rate limits and centralized billing.

const session = await CopilotSDK.createSession({
  provider: 'anthropic',  // or 'openai', 'azure-foundry'
  apiKey: process.env.ANTHROPIC_API_KEY
});

Comparison

Aspect	Token Pass-Through	BYOK
Rate Limits	Customer's Copilot limits	Your API provider limits
Billing	Customer pays via Copilot sub	You pay API provider
Setup	OAuth implementation required	Single API key configuration
Scale	Limited by individual subscriptions	Enterprise-ready, high volume

---

Scenario 4: Desktop Applications for Customers

For software vendors distributing desktop applications to end customers who need embedded AI capabilities.

Use Case

A company builds a desktop IDE, code editor, or developer tool that includes Copilot-powered features. The application is distributed to customers who may or may not have GitHub accounts.

Option A: Embedded GitHub OAuth

Bundle a "Sign in with GitHub" flow directly in your desktop app. Customers authenticate and their tokens are used locally.

1. Implement OAuth flow using system browser or embedded webview
2. Handle OAuth callback (localhost redirect or custom protocol)
3. Store token securely in OS keychain/credential manager
4. Pass token to SDK for session creation

Option B: Token Exchange Service

For customers without GitHub accounts, build a backend token exchange service that provisions API credentials.

1. Customer signs into your app using your identity system
2. Your backend generates a scoped API token (from your BYOK provider)
3. Token is securely delivered to the desktop app
4. SDK uses this token for API calls

Considerations

• Bundling: CLI must be bundled with the application (see Bundling section)
• Updates: Plan for updating bundled CLI with app updates
• Token storage: Use platform-native secure storage (Keychain, Credential Manager, Secret Service)
• Offline handling: Implement graceful degradation when tokens expire

---

Bundling and Distribution

The SDK requires the Copilot CLI to be available at runtime. There are two approaches: relying on a system-installed CLI or bundling the CLI directly with your application.

Approach Comparison

Aspect	System CLI	Bundled CLI
Version Control	User manages CLI updates	You control exact version
Compatibility	May drift from SDK version	Pinned, guaranteed compatible
Package Size	Smaller (CLI external)	Larger (includes CLI binary)
Recommended For	Hobby apps, internal tools	Production apps, desktop distribution

Language-Specific Bundling

Each supported language has different mechanisms for bundling the CLI binary with your application.

TypeScript / Node.js

For Node.js applications, bundle the CLI binary as a package asset and reference it at runtime.

• npm/yarn: Include CLI binary in package.json files array, use pkg or nexe for single executables
• Electron: Place CLI in extraResources, access via process.resourcesPath
• Configuration: Set cliPath option in SDK initialization to bundled binary location

Python

Python applications can bundle the CLI using package data or as part of a frozen application.

• pip package: Include CLI in package_data in setup.py or pyproject.toml
• PyInstaller: Add CLI to --add-binary flag or spec file binaries list
• Configuration: Pass cli_path parameter to SDK client constructor

Go

Go applications can embed the CLI binary directly in the executable using go:embed.

• go:embed: Embed CLI binary directly in Go executable (Go 1.16+)
• Runtime extraction: Extract embedded binary to temp directory at startup
• Configuration: Use WithCLIPath option when creating SDK client

.NET

.NET applications can bundle the CLI as an embedded resource or content file.

• Embedded resource: Add CLI as EmbeddedResource in .csproj, extract at runtime
• Content file: Include with CopyToOutputDirectory, reference relative to assembly
• NuGet: Use contentFiles in .nuspec for NuGet package distribution
• Configuration: Set CliPath property in CopilotClientOptions

---

Version Management

The CLI and SDK are released frequently (daily builds for bug fixes and improvements). Managing version compatibility is critical for production applications.

Compatibility Model

The SDK specifies a minimum supported CLI version. Using a CLI version below this minimum may result in missing features, API incompatibilities, or runtime errors.

• Minimum version: SDK will validate CLI version at startup and warn/error if below minimum
• Major releases: Major version bumps may introduce breaking changes requiring SDK updates
• New models: Access to new AI models requires CLI updates (models ship with prompt customizations)

Version Management by Scenario

Scenario	Strategy	Update Process
Hobby Apps	Use system CLI, update via CLI tool	Run copilot update periodically
Internal Apps	Pin SDK version, document CLI requirements	Coordinate CLI updates with SDK releases
Backend Services	Bundle CLI, version in deployment config	CI/CD pipeline updates both together
Desktop Apps	Bundle CLI, ship updates together	App update includes new CLI version

Handling Infrastructure Breaking Changes

Occasionally, backend infrastructure changes may require coordinated CLI/SDK updates beyond normal version compatibility. When this occurs:

1. Advance notice will be provided via release notes and deprecation warnings
2. A migration window will allow time for updates
3. Production applications should monitor release channels and plan upgrade cycles

Recommendations

• Subscribe to releases: Watch the GitHub repository for release notifications
• Test updates: Validate new CLI/SDK versions in staging before production
• Automate updates: Use dependency update tools (Dependabot, Renovate) for SDK packages
• Version pinning: For production, pin specific versions rather than using ranges

---

Rate Limit Considerations

• Individual limits: GitHub Copilot subscriptions have rate limits designed for individual use
• Enterprise needs: High-volume applications should use BYOK with enterprise API providers

---

Quick Reference: Choosing Your Integration Pattern

Use this decision guide to select the appropriate integration pattern:

• Just me, on my machine → Hobby pattern with useLoggedInUser: true
• My team, our identities → Internal app with GitHub OAuth
• Customers with GitHub → Token pass-through model
• Customers without GitHub → BYOK with your API provider
• Desktop app for customers → Bundled CLI with embedded OAuth or token exchange
• High volume / enterprise scale → BYOK (OpenAI, Anthropic, or Azure Foundry)

For additional support, consult the SDK API reference documentation or open an issue on the GitHub repository.

[patniko]

Consider case where Node is available, but a specific version for bundling. Also, consider NVM support needs.