Authenticating with Copilot SDK

身份验证方法概览

GitHub Copilot SDK 支持多种身份验证方式，以满足不同的使用场景。

方法	使用场景	需要 Copilot 订阅
已登录的 GitHub 用户	用户使用 GitHub 登录的交互式应用	是
OAuth GitHub 应用	通过 OAuth 代表用户操作的应用	是
环境变量	CI/CD、自动化、服务器到服务器	是
BYOK（自行提供密钥）	使用您自己的 API 密钥（Azure AI Foundry、OpenAI 等）	否

已登录的 GitHub 用户

这是在交互式运行 GitHub Copilot CLI 时的默认身份验证方法，参见 身份验证 GitHub Copilot CLI。用户通过 GitHub OAuth 设备流程登录，SDK 使用其已存储的凭据。

工作原理

1. 用户运行 copilot CLI 并通过 GitHub OAuth 登录。
2. 凭据安全地存储在系统钥匙串中。
3. SDK 自动使用存储的凭据。

SDK 配置

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

// Default: uses signed-in user credentials
const client = new CopilotClient();

其它语言的示例请参阅 Authentication，位于 github/copilot-sdk 仓库。

何时使用此方法

• 用户直接交互的桌面应用
• 开发和测试环境
• 任何用户可以交互式登录的场景

OAuth GitHub 应用

使用 OAuth GitHub 应用通过您的程序对用户进行身份验证，并将其凭据传递给 SDK。这样，您的应用便可代表授权的用户向 GitHub Copilot API 发起请求。

工作原理

1. 用户授权您的 OAuth GitHub 应用。
2. 您的应用收到用户访问令牌（前缀为 gho_ 或 ghu_）。
3. 通过 githubToken 选项将令牌传递给 SDK。

SDK 配置

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

const client = new CopilotClient({
    githubToken: userAccessToken,  // Token from OAuth flow
    useLoggedInUser: false,        // Don't use stored CLI credentials
});

其它语言的示例请参阅 Authentication，位于 github/copilot-sdk 仓库。

支持的令牌类型

• gho_ — OAuth 用户访问令牌
• ghu_ — GitHub 应用用户访问令牌
• github_pat_ — 细粒度个人访问令牌

不支持的类型

• ghp_ — 经典个人访问令牌（即将停用）

何时使用此方法

• 用户通过 GitHub 登录的 Web 应用
• 基于 GitHub Copilot 构建的软件即服务（SaaS）应用
• 任何需要代表不同用户发起请求的多用户应用

环境变量

对于自动化、CI/CD 流水线以及服务器到服务器场景，您可以使用环境变量进行身份验证。

支持的环境变量（按优先级顺序）

1. COPILOT_GITHUB_TOKEN — 推荐用于显式的 Copilot 调用
2. GH_TOKEN — 与 GitHub CLI 兼容
3. GITHUB_TOKEN — 与 GitHub Actions 兼容

SDK 会自动检测并使用这些环境变量，无需修改代码。

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

// Token is read from environment variable automatically
const client = new CopilotClient();

何时使用此方法

• CI/CD 流水线（GitHub Actions、Jenkins 等）
• 自动化测试
• 使用服务账号的服务器端应用
• 在不想使用交互式登录时的开发场景

BYOK（自行提供密钥）

BYOK 允许您使用来自 Azure AI Foundry、OpenAI、Anthropic 等模型提供商的自有 API 密钥，完全绕过 GitHub Copilot 的身份验证。

关键优势

• 无需 GitHub Copilot 订阅
• 使用企业级模型部署
• 直接向模型提供商计费
• 支持 Azure AI Foundry、OpenAI、Anthropic 以及兼容 OpenAI 的端点

完整的设置说明（包括提供商配置选项、限制与代码示例），请参阅 自行提供密钥（BYOK）。

身份验证优先级

当存在多种身份验证方式时，SDK 按以下顺序尝试：

1. 显式 githubToken — 直接传入 SDK 构造函数的令牌
2. HMAC 密钥 — 环境变量 CAPI_HMAC_KEY 或 COPILOT_HMAC_KEY
3. 直接 API 令牌 — 使用 GITHUB_COPILOT_API_TOKEN 搭配 COPILOT_API_URL
4. 环境变量令牌 — COPILOT_GITHUB_TOKEN → GH_TOKEN → GITHUB_TOKEN
5. 已存储的 OAuth 凭据 — 来自先前的 copilot CLI 登录
6. GitHub CLI — gh auth 凭据

禁用自动登录

若要阻止 SDK 自动使用已存储的凭据或 GitHub CLI 的认证，请将 useLoggedInUser 选项设为 false

const client = new CopilotClient({
    useLoggedInUser: false,  // Only use explicit tokens
});

其它语言的示例请参阅 Authentication，位于 github/copilot-sdk 仓库。

后续步骤

• 自带密钥 (BYOK)
• MCP 服务器文档——使用 SDK 将外部工具连接到 Copilot