How the Copilot SDK Prioritizes Authentication Credentials: 5-Level Priority Chain Explained

The GitHub Copilot SDK follows a strict five-level priority chain when selecting authentication credentials, starting with explicit programmatic tokens and falling back through environment variables, stored OAuth credentials, and finally GitHub CLI authentication.

The github/copilot-sdk repository implements consistent credential resolution logic across all supported languages. Understanding this authentication credentials priority chain helps developers configure secure, predictable access to GitHub Copilot services in both interactive and CI/CD environments.

The Five-Level Authentication Priority Chain

According to the authentication guide in docs/auth/authenticate.md (lines 100-108), the SDK evaluates potential credentials in the following strict order:

1. Explicit Programmatic Tokens

The SDK always prefers a token supplied directly via code. When initializing any client, passing the gitHubToken option in the constructor overrides all other sources.

This approach ensures developers maintain explicit control over authentication in production environments, preventing accidental credential leakage from system environments or user sessions.

2. Direct API Token Environment Variables

If no explicit token is provided, the SDK checks for a raw Copilot API token via the GITHUB_COPILOT_API_TOKEN environment variable, which must be paired with COPILOT_API_URL to define the endpoint.

This configuration supports advanced use cases requiring direct API access without standard GitHub token flows.

3. Standard GitHub Token Environment Variables

The SDK searches three specific environment variables in sequence, using the first valid token encountered:

• COPILOT_GITHUB_TOKEN
• GH_TOKEN
• GITHUB_TOKEN

This tier accommodates common developer workflows where standard GitHub personal access tokens are already configured for other tooling.

4. Stored OAuth Credentials

When a user previously authenticated via the copilot CLI login command, the SDK retrieves stored credentials from the system keychain.

These credentials persist across sessions, enabling seamless interactive development without repeated authentication prompts.

5. GitHub CLI Authentication

As the final fallback, the SDK queries authentication information managed by the GitHub CLI (gh auth status).

This ensures compatibility with existing developer setups where gh serves as the primary GitHub authentication mechanism.

Implementation Across Language SDKs

Each language implementation enforces this priority chain through dedicated client initialization modules:

• Node.js / TypeScript: nodejs/src/client.ts reads process.env.COPILOT_GITHUB_TOKEN, process.env.GH_TOKEN, and process.env.GITHUB_TOKEN before checking the keychain or gh CLI.
• Python: python/copilot/client.py performs identical environment-variable validation and uses the keyring library for secure credential storage access.
• Go: go/client.go implements the priority logic using os.Getenv and the github.com/zalando/go-keyring package.
• .NET: dotnet/CopilotClient.cs follows the same pattern using Environment.GetEnvironmentVariable for cross-platform compatibility.
• Java: java/src/main/java/com/github/copilot/CopilotClient.java checks the three environment variables before consulting CLI configuration files.

Practical Code Examples

Node.js: Explicit Token Configuration

Use the gitHubToken option to force the highest priority credential and disable fallback mechanisms:

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  gitHubToken: "ghu_XXXXXXXXXXXXXXXXXXXXXXXX",
  useLoggedInUser: false,
});

Python: Environment Variable Fallback

When relying on environment variables, the client automatically discovers the first available valid token:

import os
from copilot import CopilotClient

# Requires: export COPILOT_GITHUB_TOKEN=ghu_XXXXXXXXXXXXXXXXXXXXXXXX

client = CopilotClient()
await client.start()

Go: Disabling Automatic Login

Prevent the SDK from falling back to stored or CLI credentials:

import copilot "github.com/github/copilot-sdk/go"

func main() {
    client := copilot.NewClient(&copilot.ClientOptions{
        GitHubToken:     "",
        UseLoggedInUser: copilot.Bool(false),
    })
}

.NET: Forcing Explicit Authentication

Programmatically control credential selection in C# applications:

using GitHub.Copilot;

var client = new CopilotClient(new CopilotClientOptions {
    GitHubToken = "ghu_XXXXXXXXXXXXXXXXXXXXXXXX",
    UseLoggedInUser = false
});
await using var _ = client;

Java: Environment Variable Integration

Explicitly bind environment variables while maintaining priority logic:

import com.github.copilot.CopilotClient;
import com.github.copilot.CopilotClientOptions;

var client = new CopilotClient(new CopilotClientOptions()
    .setGitHubToken(System.getenv("COPILOT_GITHUB_TOKEN"))
    .setUseLoggedInUser(false));
client.start().get();

Why This Order Matters

The Copilot SDK authentication credentials priority chain balances security with developer experience. By checking explicit tokens first, the SDK prevents accidental credential leakage from shared environments or stored sessions. The structured fallback ensures that CI/CD pipelines, interactive development, and CLI-based workflows all function without redundant configuration.

This design allows teams to enforce strict authentication in production (via explicit tokens) while maintaining convenience for local development (via CLI or stored credentials).

Summary

• The SDK evaluates credentials in a strict five-level hierarchy: explicit tokens → direct API tokens → environment variables (COPILOT_GITHUB_TOKEN → GH_TOKEN → GITHUB_TOKEN) → stored OAuth → GitHub CLI.
• Implementation is consistent across Node.js (nodejs/src/client.ts), Python (python/copilot/client.py), Go (go/client.go), .NET (dotnet/CopilotClient.cs), and Java (java/src/main/java/com/github/copilot/CopilotClient.java).
• Use the useLoggedInUser: false option (or language equivalent) to disable fallback to stored or CLI credentials.
• The priority chain is documented in docs/auth/authenticate.md lines 100-108.

Frequently Asked Questions

How do I override all other credentials in the Copilot SDK?

Pass the gitHubToken parameter directly when constructing the client. This explicit approach takes precedence over environment variables, stored credentials, and CLI authentication in all supported languages.

What happens if multiple environment variables are set?

The SDK checks COPILOT_GITHUB_TOKEN first, then GH_TOKEN, then GITHUB_TOKEN, using the first valid token it encounters. It does not merge or combine tokens from multiple sources.

Can I disable fallback to CLI and stored credentials?

Yes. Set the useLoggedInUser option (or UseLoggedInUser in .NET/Java, UseLoggedInUser in Go) to false during client initialization. This restricts authentication to only explicit tokens and environment variables.

Why does the SDK check GitHub CLI credentials last?

The GitHub CLI (gh) serves as a universal fallback because it represents the broadest authentication context. Checking it last ensures that application-specific configurations (explicit tokens, environment variables) take precedence over user-level CLI settings, preventing unintended authentication contexts in multi-tenant or shared development environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}