Доверенные издатели

Загрузка в Hub из CI без хранения секрета HF_TOKEN.

Ваша CI-задача подтверждает свою личность перед Hugging Face с помощью короткоживущего токена OpenID Connect (OIDC) от вашего CI-провайдера и в ответ получает короткоживущий токен Hugging Face. Не нужно хранить токен HF как секрет или регулярно его обновлять.

Trusted Publishers — это та же идея, что и Trusted Publishers в PyPI и Trusted Publishing в npm.

Быстрый пример: публикация модели из GitHub Actions

Вы поддерживаете acme/awesome-model на HF Hub и хотите настроить CI во внешнем репозитории acme/awesome-model-training (на GitHub, GitLab или любом другом OIDC-совместимом провайдере) для загрузки новых контрольных точек — без секрета 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, чтобы также зафиксировать ветку или файл workflow — это рекомендуется.

2. Добавьте workflow в ваш репозиторий 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 CLI hf (huggingface_hub>=1.19.0) определяет провайдера, выполняет обмен и автоматически использует полученный токен. Вам нужно только задать HF_OIDC_RESOURCE.

Публикация в несколько репозиториев за один запуск (например, модель и набор данных)? Укажите HF_OIDC_RESOURCE для каждого шага, чтобы каждый токен был ограничен репозиторием, в который этот шаг выполняет публикацию.

Другие провайдеры CI

CLI hf в настоящее время формирует ID-токен нативно только в GitHub Actions. В 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 CLI hf выполняет обмен за вас, достаточно установить 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, используйте вместо этого read-only repo publisher.

Нужен сам токен (для curl, git clone или инструмента, который читает HF_TOKEN)? hf auth token выполняет обмен и выводит кратковременный токен в stdout:

Скопировано

      - 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.

Издатели репозиториев только для чтения

По умолчанию доверенный издатель репозитория выпускает токены, которые позволяют выполнять push в репозиторий. Если рабочей нагрузке требуется только 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

Токены от 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-токена вызов обмена идентичен для всех провайдеров — различаются только claims, которые вы настраиваете на стороне Hub.

Как это работает

1. Ваш CI-провайдер выпускает короткоживущий OIDC ID-токен, описывающий задание (какой репозиторий, какая ветка, какой workflow, …).
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. Операции push выполняются от имени синтетического системного пользователя [OIDC] с указанием исходного издателя и субъекта. Токены от издателя с правами только на чтение позволяют лишь читать этот репозиторий.
• Токены пользователя доступны только для чтения. По умолчанию используется область gated-repos — без записи, без частных репозиториев и без управления аккаунтом. Необязательная область inference-api добавляет вызовы Inference Providers (тарифицируются на вашем аккаунте), но по-прежнему не предоставляет доступа на запись или к частным репозиториям.
• Заявления сопоставляются точно или по префиксу, если это требуется пресетом провайдера (например, workflow_ref в GitHub). Регулярные выражения не используются.
• Журналы аудита. Добавление или удаление издателя фиксируется в журнале, а успешные обмены обновляют время последнего использования.

См. также

• Токены доступа пользователя — правильный выбор для людей и одноразовых скриптов
• OAuth / вход через HF — тот же эндпоинт /oauth/token, используемый для интерактивных сценариев
• Управление Spaces с помощью GitHub Actions
• Интеграция GitHub Actions с Hub