For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主导航

建议

上线

性能与质量

成本与吞吐量

安全与治理

基础设施与访问

运营

API Dashboard
试用 ChatGPT

为 GitHub Actions 配置工作负载身份联合

将 GitHub 签发的 OIDC Token 换取为短期 OpenAI 访问令牌，即可将 GitHub Actions 用作工作负载身份提供方。这样，工作流无需在 GitHub 机密中存储长期有效的 API 密钥，就能向 OpenAI API 进行身份验证。

如果您使用 Codex，请按照本页说明获取并检查 GitHub Token。然后配置 Codex 工作负载身份，将该 Token 写入文件，并让 Codex 使用该文件。本页的服务账户映射和 SDK 示例适用于 OpenAI API。

对于拥有 id-token: write 权限并请求身份 Token 的工作流程作业，GitHub 可以为其签发带签名的 OIDC JWT。OpenAI 会先验证 Token 的签发方、受众、签名和映射属性，再签发 OpenAI 访问令牌。

设置 GitHub Actions

授予工作流程或作业请求 GitHub OIDC Token 的权限：

permissions:
  id-token: write
  contents: read

id-token: write 权限允许作业请求 OIDC JWT，但不会授予对代码仓库内容的写入权限。actions/checkout 需要 contents: read 权限。

请求 Token 时，使用与您在 OpenAI 工作负载身份提供方中配置的受众完全一致的值。自定义 JavaScript 操作可以调用 core.getIDToken("your-wif-audience")；Shell 步骤可以直接调用 GitHub 的 OIDC 请求 URL。如果受众值包含 URL 保留字符，例如 https://api.openai.com/v1，应先进行 URL 编码，再将其附加到请求 URL：

AUDIENCE="https://api.openai.com/v1"
ENCODED_AUDIENCE=$(jq -rn --arg audience "$AUDIENCE" '$audience | @uri')

TOKEN=$(curl -sSf -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
  "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=${ENCODED_AUDIENCE}" | jq -r .value)
export TOKEN

重要的 GitHub OIDC 声明包括：

  • iss：Token 的签发方。对于 GitHub Actions，此值为 https://token.actions.githubusercontent.com。
  • aud：工作流程请求的受众值。配置 OpenAI，使其要求的值与您请求的值完全一致，例如 your-wif-audience 或 https://api.openai.com/v1。
  • sub：主要的主体字符串。GitHub 根据代码仓库、分支、标签、Pull Request 或环境等工作流程元数据构建此字符串。
  • repository：运行工作流程的代码仓库，例如 my-org/my-repo。
  • repository_owner：拥有该代码仓库的组织或用户，例如 my-org。
  • ref：触发工作流程的 Git 引用，例如 refs/heads/main 或 refs/tags/v1.0.0。
  • workflow：工作流程声明。使用 GitHub 实际生成的声明值；例如，如果您作业中的工作流程声明为 deploy，就使用该值。
  • workflow_ref：工作流程文件的路径和引用，例如 my-org/my-repo/.github/workflows/deploy.yml@refs/heads/main。
  • environment：作业使用环境时的 GitHub 环境名称，例如 production。
  • run_id、run_number、run_attempt 和 job_workflow_ref：运行和作业的标识符，可用于审计或更高级的信任规则。

有关完整的声明列表和主体格式，请参阅 GitHub 的 OpenID Connect 参考资料。

验证 Token

配置工作负载身份联合之前，请将 GitHub OIDC Token 导出为 TOKEN，然后在工作流程运行器中运行此脚本，检查其中的声明：

const parts = process.env.TOKEN?.split(".") ?? [];
if (parts.length !== 3) {
  throw new Error("Expected a compact JWT with three segments");
}
if (!/^[A-Za-z0-9_-]+$/.test(parts[1]) || parts[1].length % 4 === 1) {
  throw new Error("JWT payload is not valid Base64URL");
}

const bytes = Buffer.from(parts[1], "base64url");
if (bytes.toString("base64url") !== parts[1]) {
  throw new Error("JWT payload is not valid Base64URL");
}
const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
const claims = JSON.parse(decoded);
if (claims === null || Array.isArray(claims) || typeof claims !== "object") {
  throw new Error("JWT payload is not a JSON object");
}
console.log(decoded);

此命令会解码 JWT 载荷，但不会验证 Token 签名。对于生产环境 Token，请使用本地解码器，避免将其粘贴到第三方工具中。切勿将原始 GitHub OIDC Token 或换取的 OpenAI 访问令牌记录到日志中。

解码后的 GitHub Actions OIDC Token 类似如下：

{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://api.openai.com/v1",
  "sub": "repo:my-org/my-repo:environment:production",
  "repository": "my-org/my-repo",
  "repository_owner": "my-org",
  "ref": "refs/heads/main",
  "workflow": "deploy",
  "workflow_ref": "my-org/my-repo/.github/workflows/deploy.yml@refs/heads/main",
  "environment": "production",
  "run_id": "1234567890",
  "run_attempt": "1"
}

使用解码后的载荷，将您收到的 Token 与 OpenAI 中配置的签发方、受众和映射值进行比较。在交换 Token 之前，检查 iss、aud、repository、ref 和 workflow_ref 声明，就能发现大多数配置问题。

设置工作负载身份联合

在 OpenAI 中为 GitHub Actions 创建工作负载身份提供方，然后添加服务账户映射，使其匹配您信任的 GitHub 工作流程声明。

先配置工作负载身份提供方，再创建服务账户映射。

设置工作负载身份提供方

  1. 创建工作负载身份提供方。 将 名称 设为唯一值，例如 github-actions-prod。填写 描述（例如 Production GitHub Actions workflows），帮助管理员识别该提供方。

  2. 设置签发方和受众。 将 OIDC 签发方 URL 设为 https://token.actions.githubusercontent.com。将 受众 设为与您的工作流程请求的受众完全一致的值，例如 your-wif-audience 或 https://api.openai.com/v1。

  3. 使用 GitHub OIDC 发现机制。 保持 使用上传的 JWKS 验证 Token 处于禁用状态。OpenAI 使用 GitHub 的 OIDC 发现元数据和 JWKS 来验证由 GitHub 签名的 Token。

  4. 仅在需要派生映射属性时添加属性转换。 原始 GitHub 声明（例如 repository、ref 和 workflow）可以直接用于映射断言。如果您创建派生属性，控制台会自动添加 openai. 前缀；例如，输入 github_repository 并将表达式设为 assertion.repository，即可创建 openai.github_repository。对于 openai. 映射键，系统会忽略本身已以 openai. 开头的原始 Token 声明，除非配置了匹配的转换。

设置服务账户映射

  1. 创建服务账户映射。 将 名称 设为在该工作负载身份提供方内唯一的值，例如 github-actions-main-deploy。填写 描述（例如 Production deploy workflow on main），说明哪个工作流程可以使用该映射。

  2. 添加精确匹配的声明断言。 为每个必须匹配的 GitHub 声明添加一行 键 和 值 。只有所有配置行都匹配，OpenAI 才会签发访问令牌。对于生产环境部署工作流程，可使用如下断言：

    iss == "https://token.actions.githubusercontent.com"
aud == "https://api.openai.com/v1"
repository == "my-org/my-repo"
ref == "refs/heads/main"
workflow_ref == "my-org/my-repo/.github/workflows/deploy.yml@refs/heads/main"

    对于具有特权的映射，优先使用 workflow_ref 而非 workflow，因为管理员通常希望信任的是特定的工作流程文件路径和引用。工作流程名称可以更改，多个工作流程文件也可以使用相同的名称。

    在映射界面中，将这些内容逐行输入为键值对，例如： 键 为 repository， 值 为 my-org/my-repo； 键 为 ref， 值 为 refs/heads/main； 键 为 workflow_ref， 值 为 my-org/my-repo/.github/workflows/deploy.yml@refs/heads/main。如果作业使用 GitHub 环境，还应添加一行， 键 为 environment， 值 为 production。

    注意： 避免使用范围过宽的映射，例如仅信任 repository_owner == "my-org"，除非该所有者命名空间下的每个代码仓库都应能够获取 OpenAI 访问令牌。

  3. 选择 OpenAI 目标。 将 项目 设为目标服务账户所属的 OpenAI 项目。将 服务账户 设为 GitHub 工作流程可以使用的 OpenAI 服务账户，例如 github-actions-prod-deploy。

  4. 根据需要收窄 API 权限。 选择适当的 权限 ，例如 api.model.request 和 api.vector_store.read，以进一步限制通过此映射签发的访问令牌的权限。将权限留空，则不会添加 WIF 特有的作用域限制；该令牌仍以映射的服务账户身份获得授权。

在工作流程中使用 Token

配置您的 OpenAI SDK 客户端，使其请求 GitHub OIDC Token，并将其换取为 OpenAI 签发的访问令牌。

工作流程必须授予 id-token: write 权限，并将工作负载身份联合设置传递给 SDK 代码。SDK 使用 GitHub 向作业提供的 ACTIONS_ID_TOKEN_REQUEST_URL 和 ACTIONS_ID_TOKEN_REQUEST_TOKEN 环境变量请求 GitHub OIDC Token，然后使用换取的 OpenAI 访问令牌对 API 请求进行身份验证。

例如，通过如下工作流程运行您的应用程序代码：

name: deploy

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - name: Run OpenAI SDK code
        env:
          OPENAI_WIF_AUDIENCE: ${{ vars.OPENAI_WIF_AUDIENCE }}
          OPENAI_IDENTITY_PROVIDER_ID: ${{ vars.OPENAI_IDENTITY_PROVIDER_ID }}
          OPENAI_SERVICE_ACCOUNT_ID: ${{ vars.OPENAI_SERVICE_ACCOUNT_ID }}
        run: node ./scripts/call-openai.js

将 OPENAI_WIF_AUDIENCE、OPENAI_IDENTITY_PROVIDER_ID 和 OPENAI_SERVICE_ACCOUNT_ID 存储为 GitHub Actions 变量。它们用于标识提供方和服务账户，但不是持有者凭据。

以下示例使用自定义主体 Token 提供方初始化 OpenAI 客户端。该提供方为配置的受众请求 GitHub OIDC Token，并将其用作工作负载身份联合的主体 Token。

使用 GitHub Actions OIDC Token 进行身份验证
import OpenAI from "openai";

const identityProviderId = process.env.OPENAI_IDENTITY_PROVIDER_ID;
const serviceAccountId = process.env.OPENAI_SERVICE_ACCOUNT_ID;
const audience = process.env.OPENAI_WIF_AUDIENCE;
const requestURL = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;

if (
  !identityProviderId ||
  !serviceAccountId ||
  !audience ||
  !requestURL ||
  !requestToken
) {
  throw new Error(
    "Set OPENAI_IDENTITY_PROVIDER_ID, OPENAI_SERVICE_ACCOUNT_ID, OPENAI_WIF_AUDIENCE, and run inside GitHub Actions with id-token: write"
  );
}

function githubActionsOIDCTokenProvider(requestURL, requestToken, audience) {
  return {
    tokenType: "jwt",
    getToken: async () => {
      const url = new URL(requestURL);
      url.searchParams.set("audience", audience);

      const response = await fetch(url, {
        headers: { Authorization: `bearer ${requestToken}` },
      });

      if (!response.ok) {
        throw new Error(
          `Failed to request GitHub OIDC token: ${response.status} ${response.statusText}`
        );
      }

      const body = await response.json();
      if (!body.value) {
        throw new Error("GitHub OIDC token response did not include a value.");
      }

      return body.value;
    },
  };
}

const client = new OpenAI({
  workloadIdentity: {
    identityProviderId,
    serviceAccountId,
    provider: githubActionsOIDCTokenProvider(
      requestURL,
      requestToken,
      audience
    ),
  },
});

const response = await client.responses.create({
  model: "gpt-5.6-terra",
  input: "Say hello from GitHub Actions workload identity federation.",
});

console.log(response.output_text);

GitHub Actions 最佳实践

  • 为生产环境部署使用环境保护措施。要求工作流经过审批或满足分支限制后，才能访问生产环境中的 OpenAI 资源。
  • 按代码仓库限制映射。尽可能匹配特定于代码仓库的声明，而不是允许组织内的所有代码仓库访问。
  • 按分支或工作流程限制映射。考虑匹配 repository、ref、environment 或 workflow_ref 等声明，以限制 Token 的签发。
  • 为 CI/CD 和生产环境工作负载使用不同的 OpenAI 服务账户。构建流水线所需的权限通常不同于已部署的应用程序。
  • 避免向来自不受信任的派生代码仓库的 Pull Request 授予访问权限。来自派生代码仓库的 Pull Request 可能执行攻击者控制的代码，不应获得生产环境凭据。
  • 采用短期 Token 交换。GitHub OIDC Token 用于临时身份验证，应仅在需要时进行交换。
  • 审计代码仓库所有权变更。代码仓库的转移、重命名和权限变更可能影响现有映射所依据的安全假设。
  • 优先采用精确的声明匹配。匹配 repository、ref 和 environment 等声明，而不是依赖覆盖整个组织的信任关系。