信頼できるパブリッシャー

Push to the Hub from CI without storing an HF_TOKEN secret.

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 だけです。

1回の実行で複数のリポジトリに公開する場合（モデルとデータセットなど）は、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

2つのタイプ: リポジトリの公開者とCI/CDのアイデンティティ

両方のトークンは60分後に失効します。Hubリポジトリの信頼できるパブリッシャーを管理するには、そのリポジトリにWriteロールが必要です。

CIからゲート付きリポジトリにアクセスする

ゲート付きリポジトリの読み取りのみが必要な場合（ジョブからモデルをダウンロードするなど）、特定のリポジトリではなく、アカウントのAuthentication settings → CI/CD AccessにCI/CDアイデンティティを追加し、リソースとして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が指す対象にスコープが設定されます。

読み取り専用リポジトリの公開者

デフォルトでは、リポジトリの信頼済みパブリッシャーは、そのリポジトリにプッシュできるトークンを発行します。ワークロードがリポジトリのpullのみを必要とする場合（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からInference Providersを呼び出す

CI/CDアイデンティティのトークンは、デフォルトで読み取り専用です。Inference Providersの呼び出しも許可するには、アイデンティティの追加時にAllow Inference Providers callsにチェックを付けてください。これにより、交換されたトークンはgated-reposに加えてinference-apiスコープを持ち、リストには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プロバイダー

設定UIには、以下のプロバイダー用のプリセットが同梱されていますが、OIDC準拠のプロバイダーであればすべて動作します（AWS、GCP、Buildkite、独自のIdPなど）。

IDトークンを取得した後、交換呼び出しはプロバイダー間で同一です。異なるのは、Hub側で設定するclaimsのみです。

仕組み

1. CIプロバイダーは、ジョブ（リポジトリ、ブランチ、ワークフローなど）を記述する短期有効なOIDC IDトークンを発行します。
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"
}

セキュリティモデル

• トークンは短命です。 交換時刻から60分間有効です。カウントダウンはワークフローの開始時ではなく、エンドポイントを呼び出した時点から始まります。リフレッシュトークンは存在しないため、長時間実行されるジョブでは再交換を行う必要があります。
• リポジトリトークンはリポジトリ単位のスコープを持ちます。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 統合