# Güvenilir Yayıncılar

**Bir `HF_TOKEN` gizli anahtarı saklamadan CI'den Hub'a gönderin.**

CI işiniz, kimliğini Hugging Face'e CI sağlayıcınızdan alınan kısa ömürlü bir OpenID Connect (OIDC) jetonu ile kanıtlar ve karşılığında kısa ömürlü bir Hugging Face jetonu alır. Gizli olarak saklanması veya döndürülmesi gereken bir HF jetonu yoktur.

| | Kişisel Erişim Belirteci | Güvenilir Yayıncı |
| --- | --- | --- |
| Ömür | İptal edilene kadar | 1 saat |
| Depolama | CI gizli bilgisi | Depolanacak bir şey yok |
| Döndürme | Kılavuz | Otomatik, her çalıştırmada |
| Sızdırılırsa | İptal edene kadar geçerli | En fazla ~1 saat ve tek bir depoya sınırlı |

Trusted Publishers, PyPI'nin [Trusted Publishers](https://docs.pypi.org/trusted-publishers/) ve [npm'in Trusted Publishing](https://docs.npmjs.com/trusted-publishers) kavramlarıyla aynı fikirdir.

## Hızlı örnek: GitHub Actions'tan bir model yayımlama

HF Hub üzerinde `acme/awesome-model` modelini yönetiyorsunuz ve harici bir `acme/awesome-model-training` deposunda (GitHub, GitLab veya herhangi bir OIDC uyumlu sağlayıcıda) CI ile yeni checkpoint’leri itmek istiyorsunuz — `HF_TOKEN` gizli anahtarı olmadan.

### 1. Hub'da güvenilir yayıncıyı yapılandırın

`https://huggingface.co/acme/awesome-model/settings` adresinde **Güvenilir Yayıncılar** bölümünü açın ve şunu ekleyin:

- **Sağlayıcı**: GitHub Actions
- **İddialar** (değişimin başarılı olması için tümü eşleşmelidir):
  - `repository` = `acme/awesome-model-training`
  - `branch` = `main`
  - `workflow` = `publish.yml`

> [!TIP]
> `repository` tek başına yayıncıyı bir GitHub deposuna daraltır. Onu bir dal veya iş akışı dosyasına da sabitlemek için `branch` ve/veya `workflow` ekleyin — önerilir.

### 2. İş akışını GitHub deponuza ekleyin

`.github/workflows/publish.yml`:

```yaml
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}"
```

Bu kadar. GitHub Actions üzerinde `hf` CLI (`huggingface_hub>=1.19.0`) sağlayıcıyı algılar, değişimi gerçekleştirir ve oluşan token'ı otomatik olarak kullanır. Sadece `HF_OIDC_RESOURCE` değerini ayarlarsınız.

> [!TIP]
> Tek bir çalıştırmada birden fazla repoya yayınlama (ör. bir model **ve** bir veri seti)? Her adımın gönderdiği repoya göre token'ın kapsamını belirlemek için `HF_OIDC_RESOURCE` değerini adım başına ayarlayın.

#### Diğer CI sağlayıcıları

`hf` CLI şu an için ID token'ı yalnızca GitHub Actions üzerinde yerel olarak oluşturur. GitLab, CircleCI, Bitbucket veya başka bir sağlayıcıda ID token'ı kendiniz oluşturun ([Desteklenen CI sağlayıcıları](#supported-ci-providers) bkz.) ve `HF_OIDC_ID_TOKEN` üzerinden iletin — CLI bunu doğrudan takas eder:

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

Çalışan tam örnekler:

- GitHub Actions — [`github.com/coyotte508/publish-to-hf`](https://github.com/coyotte508/publish-to-hf)
- GitLab CI — [`gitlab.com/coyotte508/publish-to-hf`](https://gitlab.com/coyotte508/publish-to-hf)

## İki tür: depo yayıncıları ve CI/CD kimlikleri

| Lezzet | Şurada yapılandırıldı | Ne elde edersiniz | Bunu şunlar için kullanın… |
| --- | --- | --- | --- |
| **Depo güvenilir yayıncısı** | Bir repozituarın **Ayarlar → Güvenilir Yayıncılar** | O tek repoya **yazma erişimi** (veya [sadece okuma erişimi](#read-only-repo-publishers)) olan bir jeton | CI'den bir model, veri seti, Space, kernel veya bucket yayınlayın ya da özel birini çekin |
| **Hesap CI/CD kimliği** | Hesabınızın [**Kimlik doğrulama ayarları → CI/CD Erişimi**](https://huggingface.co/settings/authentication#ci-cd-access) | `gated-repos` kapsamına sahip salt okunur bir jeton, ayrıca katılırsanız `inference-api` | Erişiminiz olan **gated depoları** okuyun, hız limitlerinizi kullanın ve isteğe bağlı olarak CI'dan Inference Providers'ı çağırın |

Her iki jeton da 60 dakika sonra sona erer. Bir Hub deposunun güvenilir yayıncılarını yönetmek için **Write** rolüne sahip olmanız gerekir.

### CI'den gated depolara erişim

Eğer yalnızca gated depoları *okumanız* gerekiyorsa (ör. bir işten model indirmek), belirli bir depo yerine hesabınızda [**Authentication settings → CI/CD Access**](https://huggingface.co/settings/authentication#ci-cd-access) altında bir CI/CD kimliği ekleyin ve kaynağınız olarak **kullanıcı adınızı** kullanın.

**GitHub Actions** üzerinde `hf` CLI bu değişimi sizin için yapar, yalnızca `HF_OIDC_RESOURCE` değerini ayarlayın:

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

**diğer sağlayıcılarda**, kimlik belirtecini kendiniz oluşturun ([Diğer CI sağlayıcıları](#other-ci-providers) bölümüne bakın) ve `HF_OIDC_ID_TOKEN` üzerinden iletin:

```bash
# $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
```

Oluşturulan jeton, erişiminiz olan gated depoları okuyabilir ve hesabınızın hız sınırlarını kullanır. **Hiçbir şey yazamaz** ve **özel depolarınızı okuyamaz**. CI'dan özel bir depo çekmek için bunun yerine [sadece okunur depo yayıncısı](#read-only-repo-publishers) kullanın.

> [!TIP]
> Kendisi token'a mı ihtiyacınız var (`curl`, `git clone` veya `HF_TOKEN` okuyan bir araç için)? `hf auth token` değişimi gerçekleştirir ve kısa ömürlü token'ı stdout'a basar:
>
> ```yaml
>       - 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"
> ```
>
> Bu, hem CI/CD kimlikleri hem de depo yayıncıları ile çalışır — jeton, `HF_OIDC_RESOURCE`'in işaret ettiği kaynağa göre kapsamlandırılır.

### Salt okunur depo yayıncıları

Varsayılan olarak, bir depo güvenilir yayıncısı, depoya itme (push) yapabilecek jetonlar basar. Bir iş yükü yalnızca bir depoyu *çekmek* (pull) gerekiyorsa (örneğin, bir CI işinden veya kendi OIDC jetonlarını veren harici bir platformdan özel bir model veya veri seti indirmek için), yayıncıyı eklerken **Sadece okunur** seçeneğini işaretleyin. Değiştirilen jetonlar bu durumda depodaki içeriği okuyabilir ancak yazamaz ve listede giriş bir **Sadece okunur** rozeti gösterir. Bu, modeller, veri setleri, Spaces, çekirdekler ve varlık kovaları (buckets) için geçerlidir.

Değiş tokuşun kendisi değişmemiştir. `HF_OIDC_RESOURCE`'u (veya `resource`'i) depoya yönlendirin.

```yaml
    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
```

Diğer yayıncı ayarları gibi, izin oluşturulma anında sabitlenir. Değiştirmek için yayıncıyı silip yeniden ekleyin.

### CI'den Inference Providers'ı Çağırma

CI/CD kimliğinden gelen jetonlar varsayılan olarak salt okunurdur. Bunların Inference Providers çağrılarını da yapmasına izin vermek için, kimliği eklerken **Inference Providers çağrılarını etkinleştir** seçeneğini işaretleyin — bu durumda değiştirilen jetonlar, `gated-repos` ek olarak `inference-api` kapsamını taşır ve listede girişin yanında **Inference** rozeti görünür.

Çalıştırma kullanımı, istekleri kendiniz yapmış gibi **hesabınıza faturalandırılır** — bu nedenle etkinleştirmeden önce iddiaları sıkıca sabitleyin (`repository` *ve* `branch` ve/veya `workflow`).

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

Repo yayıncıları uygun değildir — jetonları repo kapsamındadır ve Inference Providers'ı çağıramazlar. Yetenek, oluşturulma anında sabitlenir; değiştirmek için kimliği silip yeniden ekleyin.

## Desteklenen CI sağlayıcıları

Ayarlar arayüzü, aşağıdaki sağlayıcılar için hazır ayarlarla birlikte gelir, ancak herhangi bir OIDC uyumlu sağlayıcı çalışır (AWS, GCP, Buildkite, kendi IdP'niz, …).

| Sağlayıcı | Çıkarıcı | Kimlik belirteç ID'sini nasıl alacağınız |
| --- | --- | --- |
| **GitHub Actions** | `https://token.actions.githubusercontent.com` | `permissions: id-token: write` olarak ayarlayın, ardından `audience=https://huggingface.co` ile metadata uç noktasını çağırın. [Belgeler](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect). |
| **GitLab CI** | `https://gitlab.com` (veya kendi barındırdığınız URL) | İş üzerinde `id_tokens: { HF_ID_TOKEN: { aud: https://huggingface.co } }` bildirin; `$HF_ID_TOKEN` değerini okuyun. [Belgeler](https://docs.gitlab.com/ci/yaml/#id_tokens). |
| **CircleCI** | `https://oidc.circleci.com/org/<org-uuid>` | `$CIRCLE_OIDC_TOKEN_V2` kullanın (v2, proje ayarlarında izleyiciyi ayarlamanıza olanak tanır). [Belgeler](https://circleci.com/docs/openid-connect-tokens/). |
| **Bitbucket Pipelines** | `https://api.bitbucket.org/2.0/workspaces/<workspace>/pipelines-config/identity/oidc` | Adımda `oidc: true` değerini ayarlayın; `$BITBUCKET_STEP_OIDC_TOKEN` değerini okuyun. [Belgeler](https://support.atlassian.com/bitbucket-cloud/docs/integrate-pipelines-with-resource-servers-using-oidc/). |

ID token'ına sahip olduğunuzda, değişim çağrısı tüm sağlayıcılar arasında aynıdır — yalnızca Hub tarafında yapılandırdığınız **claims** farklıdır.

## Nasıl çalışır

1. CI sağlayıcınız, işi (hangi depo, hangi dal, hangi iş akışı, …) tanımlayan kısa ömürlü bir **OIDC ID token** oluşturur.
2. İş akışınız, o jetonu `resource` (erişmek istediği depo veya kullanıcı adı) ile birlikte `https://huggingface.co/oauth/token` adresine `POST` olarak gönderir.
3. Hub, belirtecin imzasını ve iddialarını, o kaynak için yapılandırdığınız yayıncılarla karşılaştırır ve bir Hugging Face belirteci döndürür.

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

## API referansı

Uç nokta, istek ve yanıt

**Uç nokta:** `POST https://huggingface.co/oauth/token`, `Content-Type: application/json` ile.

İstemci kimlik doğrulaması gerekmez — OIDC kimlik belirteci isteği doğrular. Değişim [RFC 8693 — OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html) standardına uygun olarak gerçekleşir.

**İstek gövdesi:**

| Alan | Zorunlu | Değer |
| --- | --- | --- |
| `grant_type` | evet | `urn:ietf:params:oauth:grant-type:token-exchange` |
| `subject_token_type` | evet | `urn:ietf:params:oauth:token-type:id_token` |
| `subject_token` | evet | CI sağlayıcınızdan gelen ham OIDC kimlik belirteci (JWT). `aud` iddiası **mutlaka** `https://huggingface.co` olmalıdır. |
| `resource` | evet | Bir Hub deposu (`namespace/name`, `datasets/namespace/name`, `spaces/namespace/name`, `kernels/namespace/name`, `buckets/namespace/name`) veya kullanıcı kapsamlı bir jeton için bir Hub **kullanıcı_adı** (eğik çizgi yok). |

**Başarılı yanıt:**

```json
{
  "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"
}
```

**Hatalar** — OAuth tarzı bir gövdeyle `400 Bad Request`:

| `error` | Neden |
| --- | --- |
| `invalid_request` | Eksik/yanlış biçimli parametre veya hatalı `resource` biçimi. |
| `invalid_grant` | Depo veya kullanıcı bulunamadı; bu yayıncıyla eşleşen bir yayıncı yok; yapılandırılan iddialar eşleşmiyor; imza veya kitle kontrolü başarısız oldu; hesap kilitlendi. |

`hf` CLI değişimi gerçekleştirdiğinde, bir hata `error` kodunu ve bir `(Request ID: …)` ile birlikte gösterir. Bir sorun bildirdiğinizde, değişimi günlüklerimizde izleyebilmemiz için o Request ID'yi dahil edin.

## Güvenlik modeli

- **Tokenler kısa ömürlüdür.** Değişim anından itibaren 60 dakika — saat, iş akışının başladığında değil, uç noktayı çağırdığınızda başlar. Yenileme tokenı yoktur; uzun süren işler yeniden değişim yapmalıdır.
- **Depo jetonları depo kapsamındadır.** `acme/awesome-model` için bir jeton, `acme/anything-else` üzerinde işlem yapamaz. Push işlemleri, kaynak sağlayıcıya ve konuya atıfta bulunan sentetik bir `[OIDC]` sistem kullanıcısına atfedilir. Salt okunur bir yayıncıdan gelen jetonlar yalnızca o depoyu okuyabilir.
- **Kullanıcı jetonları salt okunurdur.** Varsayılan olarak `gated-repos` kapsamı — yazma, özel depolar veya hesap yönetimi yoktur. İsteğe bağlı `inference-api` kapsamı Inference Providers çağrılarını ekler (hesabınıza faturalandırılır), ancak yine de yazma veya özel depo erişimi yoktur.
- **Bildirimler tam eşleşmeyle veya bir sağlayıcı ön ayarının gerektirdiği durumlarda önek eşleşmesiyle karşılaştırılır** (GitHub'ın `workflow_ref`'i). Düzenli ifade kullanılmaz.
- **Denetim kayıtları.** Bir yayıncının eklenmesi veya kaldırılması kaydedilir ve başarılı işlemler son kullanım zamanını günceller.

## Bkz.

- [Kullanıcı Erişim Belirteçleri](./security-tokens) — insanlar ve tek seferlik betikler için doğru seçim
- [OAuth / HF ile oturum açma](./oauth) — etkileşimli akışlar için kullanılan aynı `/oauth/token` uç noktası
- [GitHub Actions ile Spaces Yönetimi](./spaces-github-actions)
- [Hub için GitHub Actions entegrasyonu](./repositories-github-actions)