如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

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

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

如果工作流作业具有 id-token: write 权限并请求身份令牌,GitHub 就可以为该作业签发带有签名的 OIDC JWT。OpenAI 会先验证令牌的签发方、受众、签名和映射属性,再签发 OpenAI 访问令牌。

配置 GitHub Actions

授予工作流或作业请求 GitHub OIDC 令牌的权限:

permissions:
  id-token: write
  contents: read

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

请求令牌时,指定的受众必须与您在 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:令牌签发方。对于 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:工作流文件路径及其 Git 引用,例如 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 参考文档。

验证令牌

配置工作负载身份联合之前,请将 GitHub OIDC 令牌导出为环境变量 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 载荷,但不会验证令牌签名。请使用本地解码器处理生产环境的令牌,避免将这些令牌粘贴到第三方工具中。切勿将原始 GitHub OIDC 令牌或换取的 OpenAI 访问令牌写入日志。

解码后的 GitHub Actions OIDC 令牌类似于以下示例:

{
  "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"
}

将解码后的令牌载荷与 OpenAI 中配置的签发方、受众和映射值逐项核对。在交换令牌之前,检查 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 验证令牌选项关闭。OpenAI 使用 GitHub 的 OIDC 发现元数据和 JWKS 来验证由 GitHub 签名的令牌。

  4. 仅在需要派生映射属性时添加属性转换。您可以在映射断言中直接使用 GitHub 的原始声明,例如 repository、ref 和 workflow。创建派生属性时,控制台会自动添加 openai. 前缀。例如,输入 github_repository 并将表达式设为 assertion.repository,即可创建 openai.github_repository。对于以 openai. 开头的原始令牌声明,除非您配置了对应的属性转换,否则系统在匹配带有 openai. 前缀的映射键时会忽略这些声明。

配置服务账号映射

  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,因为管理员通常只希望信任特定 Git 引用下指定路径的工作流文件。工作流可以改名,而且多个工作流文件可以使用相同的工作流名称。

    在映射界面中,将这些断言逐行输入为键值对。例如,将键设为 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。

    注意:请避免设置范围过宽的映射。例如,只有当某个所有者名下的每个代码仓库都应能获取 OpenAI 访问令牌时,才可以仅凭 repository_owner == "my-org" 建立信任。

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

  4. 按需缩小 API 权限范围。选择适当的权限,例如 api.model.request 和 api.vector_store.read,以进一步限制通过此映射签发的访问令牌的权限范围。如果无需为工作负载身份联合设置额外的权限范围限制,请将权限留空。此时,访问令牌仍使用所映射服务账号的权限。

在工作流中使用令牌

配置 OpenAI SDK 客户端,使其请求 GitHub OIDC 令牌,并用该令牌换取由 OpenAI 签发的访问令牌。

工作流必须授予作业 id-token: write 权限,并将工作负载身份联合设置传递给 SDK 代码。SDK 使用 GitHub 提供给作业的 ACTIONS_ID_TOKEN_REQUEST_URL 和 ACTIONS_ID_TOKEN_REQUEST_TOKEN 环境变量请求 GitHub OIDC 令牌,然后使用换取的 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

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - 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 --experimental-strip-types ./scripts/call-openai.mts

将 OPENAI_WIF_AUDIENCE、OPENAI_IDENTITY_PROVIDER_ID 和 OPENAI_SERVICE_ACCOUNT_ID 存储为 GitHub Actions 变量。这些变量用于标识提供方和服务账号,并非持有者凭据。

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

使用 GitHub Actions OIDC 令牌进行身份验证
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: string | URL,
  requestToken: string,
  audience: string
) {
  return {
    tokenType: "jwt" as const,
    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-6.1-terra",
  input: "Say hello from GitHub Actions workload identity federation.",
});

console.log(response.output_text);

GitHub Actions 最佳实践

  • 为生产部署启用环境保护。要求工作流先通过审批或满足分支限制条件,才能访问生产环境中的 OpenAI 资源。
  • 按代码仓库限制映射范围。尽可能匹配特定代码仓库的声明,避免允许组织内的所有代码仓库访问资源。
  • 按分支或工作流限制映射范围。可以匹配 repository、ref、environment 或 workflow_ref 等声明,限制令牌的签发范围。
  • 为 CI/CD 和生产工作负载使用不同的 OpenAI 服务账号。构建流水线与部署后的应用通常需要不同的权限。
  • 避免向来自不受信任的派生代码仓库的 pull requests 授予访问权限。处理此类 pull requests 时可能会执行攻击者控制的代码,因此不应向其提供生产环境的凭据。
  • 按需交换短期令牌。GitHub OIDC 令牌用于短期身份验证,请仅在需要时用它换取访问令牌。
  • 审计代码仓库所有权的变更。代码仓库转移、重命名和权限变更都可能影响现有映射所依赖的安全假设。
  • 优先采用声明精确匹配。匹配 repository、ref 和 environment 等声明,避免依赖覆盖整个组织的信任关系。