Editores de confianza

Publica en el Hub desde CI sin almacenar un secreto HF_TOKEN.

Tu trabajo de CI demuestra su identidad ante Hugging Face mediante un token de OpenID Connect (OIDC) de corta duración emitido por tu proveedor de CI, y a cambio recibe un token de Hugging Face de corta duración. No es necesario almacenar ni rotar un token de HF como secreto.

Los Trusted Publishers son la misma idea que los Trusted Publishers de PyPI y el Trusted Publishing de npm.

Ejemplo rápido: publicar un modelo desde GitHub Actions

Mantienes acme/awesome-model en el HF Hub y quieres que la CI en un repositorio alojado externamente, acme/awesome-model-training (en GitHub, GitLab o cualquier proveedor compatible con OIDC), suba nuevos checkpoints, sin un secreto HF_TOKEN.

1. Configure el editor de confianza en el Hub

En https://huggingface.co/acme/awesome-model/settings, abre Trusted Publishers y añade:

• Proveedor: GitHub Actions
• Claims (todos deben coincidir para que el intercambio tenga éxito):
  • repository = acme/awesome-model-training
  • branch = main
  • workflow = publish.yml

repository por sí solo limita el alcance del editor a un repositorio de GitHub. Añada branch y/o workflow para fijarlo también a una rama o archivo de flujo de trabajo, lo cual se recomienda.

2. Añade el flujo de trabajo a tu repositorio de 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}"

Eso es todo. En GitHub Actions, la CLI hf (huggingface_hub>=1.19.0) detecta el proveedor, realiza el intercambio y usa el token resultante automáticamente. Solo tienes que establecer HF_OIDC_RESOURCE.

¿Publicar en varios repositorios en una sola ejecución (p. ej., un modelo y un conjunto de datos)? Establece HF_OIDC_RESOURCE por paso para que cada token esté limitado al repositorio al que ese paso sube.

Otros proveedores de CI

El CLI hf genera el token de ID de forma nativa en GitHub Actions por ahora. En GitLab, CircleCI, Bitbucket o cualquier otro proveedor, genera el token de ID usted mismo (consulte Proveedores de CI compatibles) y páselo mediante HF_OIDC_ID_TOKEN: el CLI lo intercambia directamente:

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

Ejemplos completos y funcionales:

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

Dos variantes: editores de repositorios e identidades de CI/CD

Ambos tokens caducan después de 60 minutos. Necesitas el rol Write en un repositorio de Hub para gestionar sus publicadores de confianza.

Acceso a repositorios con control de acceso desde CI

Si solo necesitas leer repositorios con acceso restringido (por ejemplo, descargar un modelo desde un trabajo), añade una identidad de CI/CD en tu cuenta en Authentication settings → CI/CD Access en lugar de en un repositorio específico, y luego usa tu username como recurso.

En GitHub Actions, la CLI hf realiza el intercambio por ti, solo tienes que establecer HF_OIDC_RESOURCE:

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

En otros proveedores, genera el token de ID tú mismo (consulta Otros proveedores de CI) y pásalo mediante 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

El token resultante puede leer repositorios con acceso restringido a los que tienes acceso y utiliza los límites de tasa de tu cuenta. No puede escribir nada y no puede leer tus repositorios privados. Para obtener un repositorio privado desde CI, usa en su lugar un publicador de repositorio de solo lectura.

¿Necesita el propio token (para curl, git clone o una herramienta que lea HF_TOKEN)? hf auth token realiza el intercambio e imprime el token de vida corta en stdout:

Copiado

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

Esto funciona tanto con identidades de CI/CD como con editores de repositorios: el token está limitado a lo que HF_OIDC_RESOURCE apunte.

Publicadores de repositorios de solo lectura

Por defecto, un publisher de confianza de un repositorio emite tokens que pueden realizar push en el repositorio. Si una carga de trabajo solo necesita pull de un repositorio (por ejemplo, para descargar un modelo o conjunto de datos privado desde un trabajo de CI o una plataforma externa que emite sus propios tokens OIDC), marca Solo lectura al agregar el publisher. Los tokens intercambiados podrán leer el contenido del repositorio, pero no escribir en él, y la entrada mostrará una insignia de Solo lectura en la lista. Esto funciona para modelos, conjuntos de datos, Spaces, kernels y buckets.

El intercambio en sí no ha cambiado. Apunta HF_OIDC_RESOURCE (o resource) al repositorio.

    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

Como ocurre con otras configuraciones de editor, el permiso se fija en el momento de la creación. Para cambiarlo, elimina el editor y vuelve a añadirlo.

Llamada a proveedores de inferencia desde CI

Los tokens de una identidad de CI/CD son de solo lectura de forma predeterminada. Para permitir que también llamen a Inference Providers, marca Allow Inference Providers calls al agregar la identidad: los tokens intercambiados llevarán entonces el ámbito inference-api además de gated-repos, y la entrada mostrará una insignia de Inference en la lista.

El uso de inferencia se factura a tu cuenta, exactamente como si hubieras realizado las solicitudes tú mismo, por lo que restringe los permisos de forma estricta (repository y branch y/o workflow) antes de habilitarlo.

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

Los publicadores de repositorios no son elegibles: sus tokens tienen alcance de repositorio y no pueden llamar a los proveedores de inferencia. La capacidad se fija en la creación; para cambiarla, elimina la identidad y vuelve a añadirla.

Proveedores de CI admitidos

La interfaz de configuración incluye presets para los proveedores que se indican a continuación, pero cualquier proveedor compatible con OIDC funciona (AWS, GCP, Buildkite, su propio IdP, …).

Una vez que tengas el token de ID, la llamada de intercambio es idéntica en todos los proveedores; solo difieren las claims que configures en el lado del Hub.

Cómo funciona

1. Tu proveedor de CI emite un token de ID de OIDC de vida corta que describe el trabajo (qué repositorio, qué rama, qué flujo de trabajo, …).
2. Su flujo de trabajo POST ese token a https://huggingface.co/oauth/token, junto con un resource (el repositorio o nombre de usuario al que desea acceder).
3. El Hub verifica la firma y las afirmaciones del token contra los editores que configuraste para ese recurso y devuelve un token de Hugging Face.

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

Referencia de la 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"
}

Modelo de seguridad

• Los tokens tienen una vida útil corta. 60 minutos desde el momento del intercambio: el reloj solo comienza cuando se llama al punto de acceso, no cuando se inicia el flujo de trabajo. No hay token de actualización; las tareas largas deben volver a intercambiar.
• Los tokens de repositorio tienen alcance limitado al repositorio. Un token para acme/awesome-model no puede acceder a acme/anything-else. Los pushes se atribuyen a un usuario de sistema sintético [OIDC], con una referencia al emisor y al sujeto de origen. Los tokens de un publisher de solo lectura solo pueden leer ese repositorio.
• Los tokens de usuario son de solo lectura. El alcance gated-repos es el predeterminado: no permite escritura, ni repositorios privados, ni gestión de cuentas. El alcance opcional inference-api añade llamadas a Inference Providers (facturadas a tu cuenta), pero sigue sin permitir escritura ni acceso a repositorios privados.
• Las afirmaciones se coinciden de forma exacta o por prefijo cuando un preset de proveedor lo requiere (el workflow_ref de GitHub). Sin expresiones regulares.
• Registros de auditoría. Se registra la adición o eliminación de un editor, y los intercambios exitosos actualizan la última hora de uso.

Véase también

• Tokens de acceso de usuario — la opción adecuada para personas y scripts de uso único
• OAuth / Iniciar sesión con HF — el mismo punto de acceso /oauth/token, utilizado para flujos interactivos
• Gestión de Spaces con GitHub Actions
• Integración de GitHub Actions con el Hub