Publicadores confiáveis

Envie para o Hub a partir de CI sem armazenar um segredo HF_TOKEN.

Seu job de CI prova sua identidade para o Hugging Face usando um token de OpenID Connect (OIDC) de curta duração fornecido pelo seu provedor de CI e, em troca, recebe um token de curta duração do Hugging Face. Não é necessário armazenar um token do HF como segredo ou rotacioná-lo.

Trusted Publishers é a mesma ideia dos Trusted Publishers do PyPI e do Trusted Publishing do npm.

Exemplo rápido: publique um modelo a partir do GitHub Actions

Você mantém acme/awesome-model no HF Hub e deseja que o CI em um repositório hospedado externamente, acme/awesome-model-training (no GitHub, GitLab ou qualquer provedor compatível com OIDC), envie novos checkpoints — sem o segredo HF_TOKEN.

1. Configure o publicador confiável no Hub

Em https://huggingface.co/acme/awesome-model/settings, abra Trusted Publishers e adicione:

• Provedor: GitHub Actions
• Claims (todos devem corresponder para que a troca tenha sucesso):
  • repository = acme/awesome-model-training
  • branch = main
  • workflow = publish.yml

repository sozinho limita o escopo do publicador a um repositório do GitHub. Adicione branch e/ou workflow para fixá-lo também a um branch ou arquivo de workflow — recomendado.

2. Adicione o workflow ao seu repositório do 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}"

É isso. No GitHub Actions, o CLI hf (huggingface_hub>=1.19.0) detecta o provedor, executa a troca e usa o token resultante automaticamente. Você só precisa definir HF_OIDC_RESOURCE.

Publicando em vários repositórios em uma única execução (por exemplo, um modelo e um conjunto de dados)? Defina HF_OIDC_RESOURCE por etapa para que cada token seja limitado ao repositório para o qual a etapa envia os dados.

Outros provedores de CI

O CLI hf gera o ID token nativamente apenas no GitHub Actions, por enquanto. No GitLab, CircleCI, Bitbucket ou qualquer outro provedor, gere o ID token você mesmo (veja Provedores de CI suportados) e passe-o via HF_OIDC_ID_TOKEN — o CLI o troca diretamente:

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

Exemplos completos e funcionais:

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

Duas variações: publicadores de repositórios e identidades de CI/CD

Ambos os tokens expiram após 60 minutos. Você precisa da função Write em um repositório do Hub para gerenciar seus publicadores confiáveis.

Acessando repositórios restritos a partir de CI

Se você precisa apenas ler repositórios com acesso restrito (por exemplo, baixar um modelo de um job), adicione uma identidade de CI/CD na sua conta em Authentication settings → CI/CD Access em vez de em um repositório específico e, em seguida, use seu username como o recurso.

No GitHub Actions, o CLI hf faz a troca por você, basta definir HF_OIDC_RESOURCE:

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

Em outros provedores, emita o ID token você mesmo (veja Outros provedores de CI) e passe-o via 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

O token resultante pode ler repositórios com controle de acesso aos quais você tem acesso e utiliza os limites de taxa da sua conta. Ele não pode escrever nada e não pode ler seus repositórios privados. Para obter um repositório privado de um CI, use um publicador de repositório somente leitura em vez disso.

Precisa do próprio token (para curl, git clone ou uma ferramenta que lê HF_TOKEN)? hf auth token realiza a troca e imprime o token de vida curta no 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"

Isso funciona tanto com identidades de CI/CD quanto com publicadores de repositório — o token é limitado ao que HF_OIDC_RESOURCE aponta.

Publicadores de repositórios somente leitura

Por padrão, um publisher confiável de um repositório emite tokens que podem fazer push no repositório. Se uma carga de trabalho precisar apenas pull de um repositório (por exemplo, para baixar um modelo ou conjunto de dados privado de um job de CI ou de uma plataforma externa que emite seus próprios tokens OIDC), marque Somente leitura ao adicionar o publisher. Os tokens trocados poderão então ler o conteúdo do repositório, mas não poderão gravar nele, e a entrada exibirá um selo Somente leitura na lista. Isso funciona para modelos, conjuntos de dados, Spaces, kernels e buckets.

A troca em si permanece inalterada. Aponte HF_OIDC_RESOURCE (ou resource) para o repositório.

    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 em outras configurações de editora, a permissão é fixada na criação. Para alterá-la, exclua a editora e adicione-a novamente.

Chamando provedores de inferência a partir de CI

Tokens de uma identidade de CI/CD são somente leitura por padrão. Para permitir que eles também chamem Inference Providers, marque Allow Inference Providers calls ao adicionar a identidade — os tokens trocados então carregam o escopo inference-api em adição a gated-repos, e a entrada exibe um selo Inference na lista.

O uso de inferência é cobrado na sua conta, exatamente como se você tivesse feito as solicitações você mesmo — portanto, defina as permissões de forma restrita (repository e branch e/ou workflow) antes de ativá-lo.

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

Publicadores de repositórios não são elegíveis — seus tokens têm escopo de repositório e não podem chamar Inference Providers. A capacidade é fixada na criação; para alterá-la, exclua a identidade e adicione-a novamente.

Provedores de CI suportados

A interface de configurações inclui presets para os provedores abaixo, mas qualquer provedor compatível com OIDC funciona (AWS, GCP, Buildkite, seu próprio IdP, ...).

Uma vez que você tenha o token de ID, a chamada de troca é idêntica entre os provedores — apenas as claims que você configura no lado do Hub diferem.

Como funciona

1. Seu provedor de CI emite um token de ID OIDC de curta duração descrevendo o job (qual repositório, qual branch, qual workflow, …).
2. Seu fluxo de trabalho envia um POST com esse token para https://huggingface.co/oauth/token, junto com um resource (o repositório ou nome de usuário ao qual ele deseja acessar).
3. O Hub verifica a assinatura e as reivindicações do token em relação aos publicadores que você configurou para esse recurso e retorna um token do Hugging Face.

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

Referência da 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 segurança

• Tokens têm validade curta. 60 minutos a partir do momento da troca — o cronômetro só começa quando você chama o endpoint, não quando o workflow inicia. Não há refresh token; jobs longos devem reexecutar a troca.
• Os tokens de repositório têm escopo limitado ao repositório. Um token para acme/awesome-model não pode acessar acme/anything-else. Os pushes são atribuídos a um usuário de sistema sintético [OIDC], com uma referência ao emissor e ao assunto de origem. Tokens de um publisher somente de leitura podem apenas ler esse repositório.
• Tokens de usuário são somente leitura. Escopo gated-repos por padrão — sem gravações, sem repositórios privados, sem gerenciamento de conta. O escopo opcional inference-api adiciona chamadas de Inference Providers (cobradas na sua conta), mas ainda sem acesso para gravação ou repositórios privados.
• As reivindicações são correspondidas exatamente ou por prefixo, quando um preset de provedor exige (o workflow_ref do GitHub). Sem regex.
• Registros de auditoria. A adição ou remoção de um publisher é registrada, e as trocas bem-sucedidas atualizam a última vez de uso.

Veja também

• Tokens de acesso do usuário — a escolha certa para humanos e scripts de uso único
• OAuth / Entrar com HF — o mesmo endpoint /oauth/token, usado para fluxos interativos
• Gerenciando Spaces com GitHub Actions
• Integração do GitHub Actions com o Hub