[Auth] Keyless CI/CD auth via OIDC token exchange by hanouticelina · Pull Request #4326 · huggingface/huggingface_hub

hanouticelina · 2026-06-08T16:53:23Z

This PR lets CI jobs authenticate to the Hub without storing an HF_TOKEN secret, using the Hub's Trusted Publishers. Set HF_OIDC_RESOURCE to the repo (or username) to scope a short-lived token to, and huggingface_hub does the OIDC exchange under the hood, no token, no setup code.

Example: publish a model and a dataset from one training run

name: Publish to the Hub

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write    # required so the job can mint 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: Train
        run: ./train.sh    # produces ./model and ./dataset

      # Scope `HF_OIDC_RESOURCE` per step to the repo that step pushes to.
      - name: Push the model
        env:
          HF_OIDC_RESOURCE: acme/awesome-model
        run: hf upload acme/awesome-model ./model .

      - name: Push the dataset
        env:
          HF_OIDC_RESOURCE: datasets/acme/awesome-dataset
        run: hf upload acme/awesome-dataset ./dataset . --repo-type dataset

Under the hood, get_token() gains a last-resort source: when HF_OIDC_RESOURCE is set and a supported CI provider is detected, it mints the provider's OIDC id token, exchanges it at POST /oauth/token for a short-lived Hub token, and caches it.

Note

High Risk
Changes core authentication in get_token() and introduces token exchange; misconfiguration or exchange failures affect all Hub calls when HF_OIDC_RESOURCE is set.

Overview
Adds Trusted Publishers keyless CI auth: CI jobs can authenticate to the Hub via OIDC token exchange instead of storing HF_TOKEN.

A new internal _oidc module mints GitHub Actions OIDC id tokens (when permissions: id-token: write is set) and exchanges them at POST /oauth/token (RFC 8693), scoped with resource. Other providers can pass a pre-minted id token via HF_OIDC_ID_TOKEN.

get_token() now tries OIDC last when HF_OIDC_RESOURCE is set (repo or username to scope the token). Failures raise OIDCError instead of silently returning unauthenticated. Exchanged tokens are cached with refresh before expiry for auto-minted GitHub flows.

Debug HF_DEBUG curl logging redacts OAuth body fields such as subject_token.

^{Reviewed by Cursor Bugbot for commit a48753a. Configure here.}

…dc-trusted-publishers

bot-ci-comment · 2026-06-08T17:05:07Z

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

coyotte508

Nice!

coyotte508 · 2026-06-09T09:57:57Z

+def detect_provider() -> str | None:
+    """Detect the CI provider able to mint an OIDC id token, or `None` if not in a supported CI."""
+    if os.environ.get("GITHUB_ACTIONS") == "true":
+        return GITHUB
+    return None
+


maybe add a way to pass the ID token directly for other providers than Github

eg HF_OIDC_ID_TOKEN=... HF_OIDC_RESOURCE=... hf upload ...

so the Gitlab example can also be simplified!

in addition of HF_OIDC_ID_TOKEN we could also support Gitlab, etc. natively (can be a follow-up PR)

…ingface_hub into oidc-trusted-publishers

Wauplin

Thanks for the PR! I left some cosmetic changes but otherwise looks good to me.

Could you also update the PR description with a more up-to-date example? e.g. install hf CLI using installer. Also potentially could be a more complex example pushing to both a dataset and a model at the end of a training step => would need to set HF_OIDC_RESOURCE per step targeting different resources. (asking because example will likely be copied to release notes)

Once merged the follow-up would be:

update hub-docs
add support/examples for more providers

Wauplin

Thank you!

Co-authored-by: Lucain <lucain@huggingface.co>

hanouticelina · 2026-06-10T12:56:39Z

@Wauplin updated the PR description with a better example ✔️

hanouticelina · 2026-06-10T12:57:34Z

I'm talking care of the follow-up PRs as well

julien-c

This is very elegantly implemented! kudos

huggingface-hub-bot · 2026-06-11T12:33:49Z

This PR has been shipped as part of the v1.19.0 release.

hanouticelina added 2 commits June 8, 2026 18:50

keyless ci auth via oidc

4d0f85f

Merge branch 'main' of github.com:huggingface/huggingface_hub into oi…

14eca75

…dc-trusted-publishers

coyotte508 reviewed Jun 9, 2026

View reviewed changes

raise on failure, add HF_OIDC_ID_TOKEN, OIDCError

3816dba

coyotte508 reviewed Jun 10, 2026

View reviewed changes

Comment thread src/huggingface_hub/utils/_auth.py

hanouticelina added 5 commits June 10, 2026 11:19

drop the margin for HF_OIDC_ID_TOKEN

a644a69

Merge branch 'main' into oidc-trusted-publishers

3d4f745

useless

abb46b2

Merge branch 'oidc-trusted-publishers' of github.com:huggingface/hugg…

dd43986

…ingface_hub into oidc-trusted-publishers

curlify redaction and endpoint

a48753a

hanouticelina marked this pull request as ready for review June 10, 2026 10:01

hanouticelina requested review from Wauplin and coyotte508 June 10, 2026 10:01

Wauplin reviewed Jun 10, 2026

View reviewed changes

Wauplin added the highlight PR will be highlighted in the release notes. label Jun 10, 2026

review suggestions and fixes

ba99c8e

Wauplin approved these changes Jun 10, 2026

View reviewed changes

Comment thread src/huggingface_hub/cli/_errors.py Outdated

Update src/huggingface_hub/cli/_errors.py

4bf646b

Co-authored-by: Lucain <lucain@huggingface.co>

hanouticelina merged commit e3b6d5b into main Jun 10, 2026
23 of 25 checks passed

hanouticelina deleted the oidc-trusted-publishers branch June 10, 2026 13:26

hanouticelina mentioned this pull request Jun 10, 2026

Trusted Publishers: use the hf CLI for the OIDC exchange huggingface/hub-docs#2546

Merged

julien-c reviewed Jun 10, 2026

View reviewed changes

Conversation

hanouticelina commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bot-ci-comment Bot commented Jun 8, 2026

Uh oh!

coyotte508 left a comment

Choose a reason for hiding this comment

Uh oh!

coyotte508 Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Wauplin Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Wauplin left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Wauplin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hanouticelina commented Jun 10, 2026

Uh oh!

hanouticelina commented Jun 10, 2026

Uh oh!

Uh oh!

julien-c left a comment

Choose a reason for hiding this comment

Uh oh!

huggingface-hub-bot Bot commented Jun 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hanouticelina commented Jun 8, 2026 •

edited

Loading

coyotte508 Jun 9, 2026 •

edited

Loading

Wauplin left a comment •

edited

Loading