신뢰할 수 있는 퍼블리셔

신뢰할 수 있는 퍼블리셔 (Trusted Publishers)

CI에서 HF_TOKEN 시크릿을 저장하지 않고도 Hub에 푸시할 수 있어요. CI 작업이 CI 제공자의 단기 OpenID Connect(OIDC) 토큰으로 Hugging Face에 자신의 정체를 증명하면, 그 대가로 단기 유효한 Hugging Face 토큰을 받습니다. 시크릿으로 저장하거나 순환시킬 HF 토큰이 전혀 필요 없어요.

출처: 문서

본문

CI에서 HF_TOKEN 시크릿을 저장하지 않고 Hub에 푸시하세요.

CI 작업이 CI 제공자의 단기 OpenID Connect(OIDC) 토큰을 사용해 Hugging Face에 자신의 정체를 증명하고, 그 대가로 단기 유효한 Hugging Face 토큰을 받습니다. 시크릿으로 저장하거나 순환시킬 HF 토큰이 없어요.

	개인 액세스 토큰 (Personal Access Token)	신뢰할 수 있는 퍼블리셔 (Trusted Publisher)
수명 (Lifetime)	취소할 때까지	1시간
저장 (Storage)	CI 시크릿	저장할 것 없음
순환 (Rotation)	수동	자동, 매 실행마다
유출 시 (If leaked)	취소하기 전까지 유효	최대 약 1시간, 그리고 한 저장소로 한정

Trusted Publishers는 PyPI의 Trusted Publishers 및 npm의 Trusted Publishing과 같은 아이디어예요.

빠른 예시: GitHub Actions에서 모델 퍼블리시하기

HF Hub에서 acme/awesome-model을 관리하고 있고, 외부에서 호스팅되는 acme/awesome-model-training 저장소(GitHub, GitLab, 또는 OIDC 호환 제공자 어디든)의 CI가 새 체크포인트를 푸시하길 원한다고 가정해요 — HF_TOKEN 시크릿 없이요.

1. Hub에서 신뢰할 수 있는 퍼블리셔를 설정

https://huggingface.co/acme/awesome-model/settings에서 Trusted Publishers를 열고 다음을 추가하세요:

Provider: GitHub Actions
Claims (교환이 성공하려면 모두 일치해야 해요):
- repository = acme/awesome-model-training
- branch = main
- workflow = publish.yml

[!TIP] repository만으로도 퍼블리셔를 GitHub 저장소에 한정할 수 있어요. branch 및/또는 workflow를 추가해 브랜치나 워크플로 파일에도 고정할 수 있습니다 — 권장합니다.

2. 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에서 hf CLI(huggingface_hub>=1.19.0)가 제공자를 감지해 교환을 수행하고 결과 토큰을 자동으로 사용합니다. HF_OIDC_RESOURCE만 설정하면 돼요.

[!TIP] 한 번의 실행에서 여러 저장소(예: 모델 과 데이터셋)에 퍼블리시하고 싶나요? HF_OIDC_RESOURCE를 단계별로 설정하면 각 토큰이 해당 단계가 푸시하는 저장소로 한정됩니다.

다른 CI 제공자 (Other CI providers)

hf CLI는 지금은 GitHub Actions에서만 ID 토큰을 네이티브로 발급해요. 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 정체성

변형 (Flavor)	설정 위치	얻는 것	용도
저장소 신뢰 퍼블리셔 (Repo trusted publisher)	저장소의 Settings → Trusted Publishers	그 저장소 한 곳에 쓰기 권한을 가진 토큰	CI에서 모델, 데이터셋, Space, kernel, bucket 퍼블리시
계정 CI/CD 정체성 (Account CI/CD identity)	계정의 Authentication settings → CI/CD Access	`gated-repos` 스코프를 가진 읽기 전용 토큰, 그리고 선택하면 `inference-api` 추가	액세스 권한이 있는 게이트된 저장소를 읽고, 나의 요율 한도를 사용하며, 선택적으로 CI에서 Inference Providers 호출

두 토큰 모두 60분 후 만료됩니다. Hub 저장소에서 Trusted Publisher를 관리하려면 Write 역할이 필요해요.

CI에서 게이트된 저장소 접근하기

게이트된 저장소를 읽기만 하면 된다면(예: 작업에서 모델 다운로드), 특정 저장소 대신 계정의 Authentication settings → CI/CD Access에 CI/CD 정체성을 추가하고, resource로 사용자 이름을 사용하세요.

GitHub Actions에서 hf CLI가 교환을 대신 수행하므로 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

결과 토큰은 액세스 권한이 있는 게이트된 저장소를 읽고, 계정의 요율 한도를 사용할 수 있어요. 아무것도 쓸 수 없고, 내 비공개 저장소도 읽을 수 없습니다.

[!TIP] 토큰 자체가 필요하나요(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가 가리키는 것에 한정됩니다.

CI에서 Inference Providers 호출하기

CI/CD 정체성의 토큰은 기본적으로 읽기 전용이에요. Inference Providers도 호출하게 하려면 정체성을 추가할 때 Allow Inference Providers calls를 체크하세요 — 그러면 교환된 토큰이 gated-repos에 더해 inference-api 스코프를 가지게 되고, 목록의 항목에 Inference 배지가 표시됩니다.

Inference 사용량은 내 계정으로 청구됩니다 — 마치 직접 요청한 것처럼요. 그러니 이 기능을 켜기 전에 claims를 빡빡하게 고정(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 제공자 (Supported CI providers)

설정 UI는 아래 제공자에 대한 프리셋을 제공하지만, OIDC 호환 제공자라면 아무거나 동작합니다(AWS, GCP, Buildkite, 내 IdP 등).

제공자 (Provider)	Issuer	ID 토큰 얻는 방법
GitHub Actions	`https://token.actions.githubusercontent.com`	`permissions: id-token: write`를 설정한 뒤, `audience=https://huggingface.co`로 메타데이터 엔드포인트를 호출. Docs.
GitLab CI	`https://gitlab.com` (또는 셀프 호스팅 URL)	작업에 `id_tokens: { HF_ID_TOKEN: { aud: https://huggingface.co } }`를 선언하고 `$HF_ID_TOKEN`을 읽음. Docs.
CircleCI	`https://oidc.circleci.com/org/<org-uuid>`	`$CIRCLE_OIDC_TOKEN_V2` 사용 (v2는 프로젝트 설정에서 audience 설정 가능). Docs.
Bitbucket Pipelines	`https://api.bitbucket.org/2.0/workspaces/<workspace>/pipelines-config/identity/oidc`	단계에 `oidc: true` 설정 후 `$BITBUCKET_STEP_OIDC_TOKEN` 읽음. Docs.

ID 토큰을 얻으면 교환 호출은 제공자 간에 동일합니다 — Hub 쪽에서 설정하는 claims만 다를 뿐이에요.

작동 방식 (How it works)

CI 제공자가 작업을 설명하는(어떤 저장소, 어떤 브랜치, 어떤 워크플로 등) 단기 OIDC ID 토큰을 발급합니다.
워크플로가 그 토큰을 resource(접근하고 싶은 저장소 또는 사용자 이름)와 함께 https://huggingface.co/oauth/token에 POST합니다.
Hub가 그 resource에 대해 설정한 퍼블리셔와 토큰의 서명·claims를 대조해 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 레퍼런스 (API reference)

엔드포인트, 요청, 응답

Endpoint: POST https://huggingface.co/oauth/token with Content-Type: application/json.

클라이언트 인증은 필요 없습니다 — OIDC ID 토큰이 요청을 인증해요. 교환은 RFC 8693 — OAuth 2.0 Token Exchange를 따릅니다.

Request body:

필드	필수	값
`grant_type`	예	`urn:ietf:params:oauth:grant-type:token-exchange`
`subject_token_type`	예	`urn:ietf:params:oauth:token-type:id_token`
`subject_token`	예	CI 제공자의 원시 OIDC ID 토큰(JWT). `aud` claim은 반드시 `https://huggingface.co`여야 합니다.
`resource`	예	Hub 저장소(`namespace/name`, `datasets/namespace/name`, `spaces/namespace/name`, `kernels/namespace/name`, `buckets/namespace/name`) 또는 사용자 한정 토큰을 위한 Hub 사용자 이름(슬래시 없음).

성공 응답:

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

오류 — OAuth 스타일 본문과 함께 400 Bad Request:

`error`	이유
`invalid_request`	파라미터 누락/형식 오류, 또는 잘못된 `resource` 형식.
`invalid_grant`	저장소나 사용자를 찾을 수 없음; 이 issuer와 일치하는 퍼블리셔 없음; 설정한 claims 불일치; 서명 또는 audience 검사 실패; 계정 잠김.

hf CLI가 교환을 수행할 때 실패하면 error 코드가 (Request ID: …)와 함께 표시됩니다 — 문제를 보고할 때 이 Request ID를 포함하면 로그에서 교환을 추적할 수 있어요.

보안 모델 (Security model)

토큰은 단기 유효합니다. 교환 시점부터 60분 — 워크플로가 시작될 때가 아니라 엔드포인트를 호출한 시점부터 시계가 돌아요. 리프레시 토큰이 없으므로 오래 걸리는 작업은 다시 교환해야 합니다.
저장소 토큰은 저장소 한정입니다. acme/awesome-model용 토큰은 acme/anything-else를 건드릴 수 없어요. 푸시는 합성 [OIDC] 시스템 사용자로 귀속되며, 발급자와 subject에 대한 참조가 함께 기록됩니다.
사용자 토큰은 읽기 전용입니다. 기본적으로 gated-repos 스코프 — 쓰기 없음, 비공개 저장소 없음, 계정 관리 없음. 선택적 inference-api 스코프는 Inference Providers 호출을 추가하지만(계정으로 청구), 여전히 쓰기나 비공개 저장소 접근은 없습니다.
claims는 정확히 일치해야 합니다. 정규식이나 접두사 매칭이 없어요.
감사 로그 (Audit logs). 퍼블리셔 추가/제거가 기록되고, 성공적인 교환은 last used 시간을 갱신합니다.

더 알아보기 (Learn more)

Trusted Publisher는 CI에서 HF_TOKEN 시크릿 없이 Hub에 푸시할 수 있게 해주는 OIDC 기반 인증 방식이에요. GitLab 같은 다른 제공자는 HF_OIDC_ID_TOKEN으로 ID 토큰을 직접 발급해 전달하고, 게이트된 저장소만 읽으려면 계정 CI/CD 정체성에 HF_OIDC_RESOURCE로 사용자 이름을 지정하면 됩니다. HF_TOKEN 없이 토큰 자체가 필요하면 hf auth token으로 단기 토큰(1시간 유효)을 얻을 수 있어요. 자세한 흐름은 User Access Tokens와 OAuth 문서를 참고하세요.

신뢰할 수 있는 퍼블리셔