GitHub Copilot SDK 服务端到服务端Server-to-Server认证完整指南使用短期安装令牌与 GITHUB_TOKEN【免费下载链接】copilot-sdkMulti-platform SDK for integrating GitHub Copilot Agent into apps and services项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdk导读当你的服务需要以组织身份发起 Copilot 请求且不希望依赖任何单个用户的凭据时GitHub Copilot SDK 提供了标准的服务端到服务端server-to-server认证路径在 GitHub Actions 中使用内置的GITHUB_TOKEN在 GitHub Actions 之外的 CI 或自有服务中使用 GitHub App 的短期安装访问令牌installation access token。本文将完整讲解这两种方式的配置步骤、六种 SDK 语言的运行时配置代码、令牌刷新与计费机制并结合仓库源码说明认证优先级与令牌传递路径帮助你构建无需用户登录的自动化 Copilot 应用。服务端到服务端认证概述服务端到服务端认证的核心诉求是在没有用户凭据的情况下让服务代表某个组织发起 Copilot 请求。GitHub Copilot SDK 为此提供了两条互斥的路径场景令牌来源说明GitHub Actions 中的组织仓库内置GITHUB_TOKEN无需创建 GitHub App无需存储任何认证密钥GitHub Actions 之外的服务与 CIGitHub App 安装访问令牌ghs_前缀通过短期令牌认证计费归属于 GitHub App 安装所在的组织两条路径产出的令牌都通过运行时环境变量传递而不是通过 SDK 的显式令牌选项传递。这一点在后续“令牌传递路径”章节会重点强调因为它决定了整个方案是否可行。需要说明的是这类令牌要求组织启用 Copilot 请求能力organization policy而不依赖个人用户订阅相比之下SDK 的其他认证方式登录用户、OAuth App、环境变量用户令牌则通常要求 Copilot 订阅。完整的方法对比可参见 docs/auth/README.md。在 GitHub Actions 中使用内置 GITHUB_TOKEN对于组织拥有的仓库中的 workflowGitHub 内置的GITHUB_TOKEN被授予copilot-requests: write权限后即可直接用于发起 Copilot 请求无需 GitHub App 或任何存储的认证密钥permissions: contents: read copilot-requests: write jobs: copilot: runs-on: ubuntu-latest steps: - uses: actions/checkoutv6 - run: your-application env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}使用该方案有几个前提条件组织策略组织的Allow use of Copilot CLI billed to the organization允许使用计入组织费用的 Copilot CLI策略必须启用。权限声明copilot-requests: write是发起 Copilot 请求所需的权限contents: read通常用于让应用读取仓库内容。无密钥存储整个流程依赖 GitHub Actions 内置令牌不需要在仓库中保存任何长期密钥。从 SDK 的角度看GITHUB_TOKEN属于环境变量令牌中的第三优先级优先级依次为COPILOT_GITHUB_TOKEN→GH_TOKEN→GITHUB_TOKENSDK 启动运行时会自动检测并使用无需任何额外代码配置。在 GitHub Actions 之外的服务与 CI 中使用安装访问令牌对于 GitHub Actions 之外的 Jenkins、自有服务器、云函数等服务需要走 GitHub App 安装令牌路径整体流程如下创建 GitHub App并将其Copilot Requests仓库权限设置为Read write读与写。将 App 安装到需要计费的组织。注意当前 Copilot 权限检查要求安装具备All repositories所有仓库访问权限。生成安装访问令牌请求中包含repository_ids仓库 ID 列表与 Copilot 权限copilot_requests: write{ repository_ids: [123456789], permissions: { copilot_requests: write } }将生成的ghs_令牌以COPILOT_GITHUB_TOKEN环境变量形式传给运行时。关键约束组织必须启用来自 GitHub App 安装的 Copilot 请求。安装访问令牌一小时后过期short-lived因此需要在其过期前重新铸造详见“刷新令牌”章节。令牌传递路径环境变量而非 SDK 显式选项[!WARNING] 严禁将安装令牌传给 SDK 的gitHubToken、github_token或等价选项。该选项是为用户令牌gho_/ghu_/github_pat_设计的安装令牌必须走运行时环境认证路径即COPILOT_GITHUB_TOKEN。这条约束是服务端到服务端认证方案能否生效的关键。仓库中的源码印证了这一点在 go/client.go 中显式GitHubToken与UseLoggedInUser用于外部运行时URIConnection时会直接panic提示外部服务器自己管理认证——显式令牌选项走的是与运行时环境认证完全不同的通道。在 nodejs/src/client.ts 中当提供了gitHubToken时useLoggedInUser默认被置为false反之默认为true——显式令牌与“使用已登录用户”是互斥的两条路径。这与 docs/auth/authenticate.md 中定义的认证优先级一致显式gitHubToken优先级最高其次是直接 API 令牌、环境变量令牌COPILOT_GITHUB_TOKEN→GH_TOKEN→GITHUB_TOKEN、已存储的 OAuth 凭据最后是 GitHub CLI 凭据。安装令牌必须落在“环境变量令牌”这一档才能保证按预期使用组织身份计费。配置运行时六种语言的完整示例以下示例假定铸造好的安装令牌位于环境变量INSTALLATION_TOKEN中并做了两件事仅将令牌传给子进程运行时通过env选项。禁用回退到已存储用户凭据useLoggedInUser: false确保不会意外使用本机已登录用户身份。TypeScriptimport { CopilotClient, RuntimeConnection } from github/copilot-sdk; const token process.env.INSTALLATION_TOKEN; if (!token) throw new Error(INSTALLATION_TOKEN is required); const client new CopilotClient({ connection: RuntimeConnection.forStdio(), env: { ...process.env, COPILOT_GITHUB_TOKEN: token, }, useLoggedInUser: false, });Pythonimport os from copilot import CopilotClient, RuntimeConnection client CopilotClient( connectionRuntimeConnection.for_stdio(), env{**os.environ, COPILOT_GITHUB_TOKEN: os.environ[INSTALLATION_TOKEN]}, use_logged_in_userFalse, )Gopackage main import ( log os copilot github.com/github/copilot-sdk/go ) func main() { token, ok : os.LookupEnv(INSTALLATION_TOKEN) if !ok { log.Fatal(INSTALLATION_TOKEN is required) } client : copilot.NewClient(copilot.ClientOptions{ Connection: copilot.StdioConnection{}, Env: append(os.Environ(), COPILOT_GITHUB_TOKENtoken), UseLoggedInUser: copilot.Bool(false), }) _ client }Rustuse github_copilot_sdk::{ClientOptions, Transport}; fn main() { let token std::env::var(INSTALLATION_TOKEN).expect(INSTALLATION_TOKEN is required); let options ClientOptions::new() .with_transport(Transport::Stdio) .with_env([(COPILOT_GITHUB_TOKEN, token)]) .with_use_logged_in_user(false); drop(options); }.NETusing System.Collections; using GitHub.Copilot; var token Environment.GetEnvironmentVariable(INSTALLATION_TOKEN) ?? throw new InvalidOperationException(INSTALLATION_TOKEN is required); var environment Environment.GetEnvironmentVariables() .CastDictionaryEntry() .ToDictionary(entry (string)entry.Key, entry entry.Value?.ToString() ?? ); environment[COPILOT_GITHUB_TOKEN] token; await using var client new CopilotClient(new CopilotClientOptions { Connection RuntimeConnection.ForStdio(), Environment environment, UseLoggedInUser false, });Javaimport com.github.copilot.CopilotClient; import com.github.copilot.rpc.CopilotClientOptions; import java.util.HashMap; import java.util.Objects; var environment new HashMap(System.getenv()); var token Objects.requireNonNull( System.getenv(INSTALLATION_TOKEN), INSTALLATION_TOKEN is required); environment.put(COPILOT_GITHUB_TOKEN, token); try (var client new CopilotClient(new CopilotClientOptions() .setEnvironment(environment) .setUseLoggedInUser(false))) { // Use the client. }进程内In-ProcessFFI 与既有运行时的特殊说明对于进程内 FFI模式COPILOT_GITHUB_TOKEN必须在加载运行时之前设置到宿主进程环境中按客户端per-client传递的env选项在该模式下不被支持。对于既有运行时 URIRuntimeConnection.forUri/URIConnection需要在那个运行时进程上设置环境变量——正如 nodejs/src/client.ts 所示外部运行时自己管理认证客户端层不能叠加显式令牌选项。如果你需要在托管进程中配置此类环境变量可以参考 docs/setup/backend-services.md 中Environment/EnvVar的环境注入方式而本地 CLI 场景下通过环境变量认证的最小示例见 docs/setup/local-cli.md。刷新令牌安装访问令牌有效期为一小时必须在到期前铸造新令牌子进程运行时用包含新令牌的环境变量重启 SDK 客户端重新new CopilotClient并传入新的env。进程内或既有运行时用新令牌重启宿主运行时进程。由于安装令牌不是由 SDK 自动刷新的你需要在自己的服务中安排周期性的令牌铸造任务例如每 30–45 分钟并实现客户端/运行时的平滑重建。计费归属使用量归属于拥有 GitHub App 安装的账户组织安装使用量计入组织账单。用户账户安装使用量计入该用户。因此如果你希望组织统一承担 Copilot 费用应使用组织安装这与本指南开篇“服务代表组织发起请求”的目标一致。多用户服务器场景下按会话分配身份的方案可进一步参考 docs/setup/multi-tenancy.md。故障排查速查表症状排查方向401 Unauthorized确认组织已支持 GitHub App 安装认证方式发起 Copilot 请求。403 Resource not accessible by integration或涉及用户信息的报错确认安装令牌被放入了COPILOT_GITHUB_TOKEN而不是 SDK 的显式令牌选项gitHubToken/github_token。Copilot API 返回403 Forbidden确认令牌请求中包含repository_ids且权限为copilot_requests: write。令牌请求合法但仍返回403 Forbidden确认 App 安装具有All repositories访问权限然后重新铸造新令牌。请求的模型不可用确认组织 Copilot 策略允许该模型且捆绑的运行时版本支持该模型。计费账户不符合预期确认安装归属于预期的组织。延伸阅读Authenticate Copilot SDK其他认证方式登录用户、OAuth App、环境变量、BYOK及完整认证优先级认证方法总览按部署场景选择认证方法Bring Your Own KeyBYOK使用 OpenAI、Azure、Anthropic 等自有 API 密钥后端服务部署在服务进程中注入令牌环境变量本地 CLI 环境变量认证COPILOT_GITHUB_TOKEN的最小使用方式多用户与服务端部署按会话分配 GitHub 身份【免费下载链接】copilot-sdkMulti-platform SDK for integrating GitHub Copilot Agent into apps and services项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考