受信任的发布者

在 CI 中推送到 Hub，而无需存储 HF_TOKEN 密钥。

您的 CI 作业使用来自 CI 提供方的短期 OpenID Connect (OIDC) 令牌向 Hugging Face 证明其身份，并以此换取一个短期的 Hugging Face 令牌。无需将 HF 令牌作为机密存储或轮换。

Trusted Publishers 与 PyPI 的 Trusted Publishers 和 npm 的 Trusted Publishing 是相同的概念。

快速示例：从 GitHub Actions 发布模型

您在 HF Hub 上维护 acme/awesome-model，并希望在一个外部托管的 acme/awesome-model-training 仓库（位于 GitHub、GitLab 或任何符合 OIDC 标准的提供商）中配置 CI，以推送新的检查点——无需 HF_TOKEN 密钥。

1. 在 Hub 上配置受信任的发布者

在 https://huggingface.co/acme/awesome-model/settings 上，打开 Trusted Publishers 并添加：

• 提供商：GitHub Actions
• Claims (（所有声明必须匹配，交换才能成功）：
  • repository = acme/awesome-model-training
  • branch = main
  • workflow = publish.yml

仅使用 repository 会将发布者限定为某个 GitHub 仓库。建议同时添加 branch 和/或 workflow，以将其固定到特定分支或工作流文件。

2. 将工作流添加到您的 GitHub 仓库

.github/workflows/publish.yml:

name: Publish to Hugging Face

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  publish:
    runs-on: ubuntu-latest

    permissions:
      id-token: write  # required so the job can request an OIDC token
      contents: read

    steps:
      - uses: actions/checkout@v4

      - name: Install the hf CLI
        run: |
          curl -LsSf https://hf.co/cli/install.sh | bash
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Upload checkpoint
        env:
          # The HF repo to publish to. For non-model repos, prefix accordingly:
          #   datasets/acme/awesome-dataset, spaces/acme/awesome-space, kernels/acme/awesome-kernel
          HF_OIDC_RESOURCE: acme/awesome-model
        run: hf upload acme/awesome-model ./checkpoint . --commit-message "Publish from ${GITHUB_SHA::7}"

就是这样。在 GitHub Actions 上，hf CLI（huggingface_hub>=1.19.0）会检测提供商，执行交换，并自动使用生成的令牌。你只需设置 HF_OIDC_RESOURCE。

在一次运行中发布到多个仓库（例如一个模型和一个数据集）？请为每个步骤设置HF_OIDC_RESOURCE，以便每个令牌的作用范围仅限于该步骤推送到的仓库。

其他 CI 提供商

目前，hf CLI 仅在 GitHub Actions 上原生铸造 ID 令牌。在 GitLab、CircleCI、Bitbucket 或其他提供商上，请自行铸造 ID 令牌（参见 支持的 CI 提供商），并通过 HF_OIDC_ID_TOKEN 传递——CLI 会直接对其进行交换：

# GitLab CI (.gitlab-ci.yml)
publish:
  id_tokens:
    HF_ID_TOKEN:
      aud: https://huggingface.co
  script:
    - curl -LsSf https://hf.co/cli/install.sh | bash
    - export PATH="$HOME/.local/bin:$PATH"
    - HF_OIDC_ID_TOKEN="$HF_ID_TOKEN" HF_OIDC_RESOURCE="acme/awesome-model" hf upload acme/awesome-model ./checkpoint .

完整可运行的示例：

• GitHub Actions — github.com/coyotte508/publish-to-hf
• GitLab CI — gitlab.com/coyotte508/publish-to-hf

两种类型：仓库发布者和 CI/CD 身份

两个令牌均在 60 分钟后过期。要管理 Hub 仓库的可信发布者，您需要该仓库的 Write 角色。

从 CI 访问受限制仓库

如果只需要读取受控仓库（例如从任务中下载模型），请在您的账户下添加 CI/CD 身份，路径为Authentication settings → CI/CD Access，而不是在特定仓库上添加，然后使用您的username作为资源。

在 GitHub Actions 上，hf CLI 会为您完成交换，只需设置 HF_OIDC_RESOURCE：

      - name: Download a gated model
        env:
          HF_OIDC_RESOURCE: your-hf-username
        run: hf download acme/gated-model

在其他提供商上，请自行铸造 ID 令牌（参见其他 CI 提供商），并通过HF_OIDC_ID_TOKEN传递：

# $ID_TOKEN is the OIDC token your provider minted (e.g. $HF_ID_TOKEN on GitLab)
HF_OIDC_ID_TOKEN="$ID_TOKEN" HF_OIDC_RESOURCE="your-hf-username" hf download acme/gated-model

生成的令牌可以读取您有权限访问的受保护仓库，并使用您账户的速率限制。它无法写入任何内容，也无法读取您的私有仓库。若要从 CI 拉取私有仓库，请改用只读仓库发布者。

需要令牌本身（用于 curl、git clone 或读取 HF_TOKEN 的工具）？hf auth token 会执行交换操作，并将短期令牌打印到标准输出：

已复制

      - name: Get a short-lived HF token
        env:
          HF_OIDC_RESOURCE: your-hf-username  # or a repo, e.g. acme/awesome-model
        run: echo "HF_TOKEN=$(hf auth token)" >> "$GITHUB_ENV"

此功能同时适用于 CI/CD 身份和仓库发布者——令牌的作用域由 HF_OIDC_RESOURCE 指向的资源决定。

只读仓库发布者

默认情况下，仓库可信发布者会签发能够向该仓库推送内容的令牌。如果工作负载仅需拉取仓库（例如，从 CI 作业或签发自身 OIDC 令牌的外部平台下载私有模型或数据集），请在添加发布者时勾选Read-only。交换后的令牌即可读取仓库内容，但无法写入，且该条目在列表中会显示Read-only徽章。此功能适用于模型、数据集、Spaces、内核和存储桶。

交换本身没有变化。将 HF_OIDC_RESOURCE（或 resource）指向该仓库。

    permissions:
      id-token: write  # required so the job can request an OIDC token

    steps:
      - name: Download a private model
        env:
          HF_OIDC_RESOURCE: acme/private-model
        run: hf download acme/private-model

与其他发布者设置一样，该权限在创建时即已固定。如需更改，请删除该发布者并重新添加。

从 CI 调用推理提供商

来自 CI/CD 身份的令牌默认是只读的。若要允许其调用 Inference Providers，请在添加身份时勾选 Allow Inference Providers calls——交换后的令牌将额外携带 inference-api 作用域（除 gated-repos 外），并且该条目在列表中会显示 Inference 徽章。

推理使用量将计入您的账户，就如同您亲自发起请求一样——因此，在启用之前，请严格限定权限范围（repository 和 branch 和/或 workflow）。

      - name: Run inference from CI
        env:
          HF_OIDC_RESOURCE: your-hf-username
        run: |
          export HF_TOKEN="$(hf auth token)"
          python inference_script.py

仓库发布者不符合条件——其令牌的作用域仅限于仓库，无法调用 Inference Providers。该权限在创建时即已固定；如需更改，请删除该身份并重新添加。

支持的 CI 提供商

设置界面为以下提供商提供了预设，但任何符合 OIDC 标准的提供商均可使用（AWS、GCP、Buildkite、您自己的 IdP 等）。

获取 ID 令牌后，各提供商的交换调用完全相同——唯一不同的是您在 Hub 端配置的 claims。

工作原理

1. 您的 CI 提供商会签发一个短生命周期的 OIDC ID token，用于描述该任务（所属仓库、分支、工作流等）。
2. 您的工作流会将该令牌通过 POST 请求发送到 https://huggingface.co/oauth/token，并附带一个 resource（即它想要访问的仓库或用户名）。
3. Hub 会针对您为该资源配置的发布者，检查令牌的签名和声明，并返回一个 Hugging Face 令牌。

┌──────────┐  1. mint ID token   ┌──────────┐  2. exchange   ┌────────────┐
│ CI job   │ ─────────────────▶  │ CI OIDC  │ ──────────────▶│ huggingface│
│          │                     │ issuer   │                │  /oauth/   │
│          │ ◀──────────────────────────────────────────────│  token     │
└──────────┘        3. short-lived HF token (valid 1 h)      └────────────┘

API 参考

{
  "access_token":      "hf_jwt_…",   // "hf_oauth_…" for user resources
  "token_type":        "bearer",
  "expires_in":        3600,
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

安全模型

• Token 的有效期很短。 从交换时刻起 60 分钟——计时器仅在你调用端点时开始，而非工作流启动时。没有刷新 Token；长时间运行的任务应重新交换。
• 仓库令牌的作用范围仅限于该仓库。针对 acme/awesome-model 的令牌无法访问 acme/anything-else。推送操作归属于一个合成的 [OIDC] 系统用户，并包含对原始颁发者和主体的引用。来自只读发布者的令牌只能读取该仓库。
• 用户令牌为只读。 默认情况下，gated-repos 作用域不包含写入、私有仓库或账户管理权限。可选的 inference-api 作用域会添加 Inference Providers 调用（费用计入您的账户），但仍不提供写入或私有仓库访问权限。
• 声明通过精确匹配或前缀匹配进行匹配（当提供商预设需要时）（例如 GitHub 的 workflow_ref）。不使用正则表达式。
• 审计日志。添加或删除发布者时会被记录，成功的交换操作会更新最后使用时间。

另请参阅

• 用户访问令牌 — 适用于人类用户和一次性脚本
• OAuth / 使用 HF 登录 — 相同的 /oauth/token 端点，用于交互式流程
• 使用 GitHub Actions 管理 Spaces
• Hub 的 GitHub Actions 集成