huggingface_hub is the Python client at the base of the Hugging Face ecosystem. transformers, datasets, diffusers, sentence-transformers and dozens of other libraries depend on it to talk to the Hub. Every week we don't ship a new release is a week of fixes and features stuck on main.
For a long time we released every 4 to 6 weeks. We now release every week from a single GitHub Actions workflow. We built it using open-source tools and open-weights models and kept a human in the loop at the one place where judgment matters. Nothing in this post requires a vendor contract, a closed model, or infrastructure you can't run yourself. That was a design goal from the start since we wanted a workflow other maintainers could pick up and adapt.
\nBy the end of this post, you'll have everything you need to build your own.
\nThe old process was partly automated, mostly manual.
\nAlready in CI:
\nStill manual, every single time:
\n__init__.py, committing, tagging, pushing.git log dump.main to the next dev0.Writing good notes for a new version was the heavy part, aggregating tens of PRs on different topics. Nothing technically hard but a few hours of focused attention. Add the announcements on top and a minor release was easily a half-day of work spread over several days.
\nSo we decided to streamline the whole thing. Looking at that list, the work splits in two.
\nSome steps are purely mechanical and can be automated: bumping the version, committing, tagging, pushing, opening downstream test branches, opening the post-release PR. Nobody needs to think about those. They just have to happen in the right order, every time, which is what a CI workflow is good at.
\nThe rest is different. Writing release notes, deciding what to highlight, phrasing an announcement for a human audience: that's brain work. It's the kind of judgment that kept the release manual for years. This is where AI comes in, turning a blank page into a solid first draft in seconds. It's also where we have to be careful because a draft that looks confident and is subtly wrong is worse than no draft at all.
\nWhen we decided to fix this, we set one constraint up front: every moving part had to be something any maintainer could run themselves. No closed model behind an API we couldn't swap, no proprietary release platform, no secret sauce.
\nHere's the entire stack:
\n| Part | \nWhat it does | \n
|---|---|
| GitHub Actions | \nOrchestrates the whole release | \n
| OpenCode | \nAgent runtime that drives the model | \n
| An open-weights model (currently GLM-5.2 from Z.ai) | \nDrafts the release notes and Slack announcement | \n
| HF Inference Providers | \nServes the model | \n
| PyPI Trusted Publishing | \nPublishes the package | \n
The second principle: the model drafts, a human decides. Language models are good at turning thirty terse PR titles into readable release notes. They are not good at being trusted blindly. So the workflow is human-supervised: the model does the first pass, a deterministic script checks its work, and a human reviews and edits before anything ships (more on that below).
\nThe full workflow is a single file, .github/workflows/release.yml, triggered by hand from the Actions UI. It takes exactly one input:
on:\n workflow_dispatch:\n inputs:\n release_type:\n type: choice\n options:\n - minor-prerelease # cut an RC from main\n - minor-release # promote the RC to final\n - patch-release # bugfix on an existing release branch\nFrom there, the jobs run roughly in this order:
\n__version__, commit, tag, push.huggingface_hub. In parallel, build and upload the hf CLI as its own PyPI package.transformers, datasets, diffusers, sentence-transformers with the RC pinned, so their CI tells us fast if we broke something.main bumping to the next dev0.hf CLI skill docs.The remaining manual steps are reviewing and publishing the draft release notes, and reviewing and posting an internal Slack message. Those two steps are where we want a human in the loop.
\nHere's the failure mode everyone worries about with AI-generated release notes: the model quietly drops a PR or invents one that isn't in this release. A changelog that's almost right is worse than no changelog because nobody re-checks it.
\nWe don't trust the generated release notes to be complete on the first try, we verify it deterministically. Before the model runs, a Python script retrieves all PRs that belong to the release and stores them as ground truth.
\n# Deterministic: extract PR numbers from squash-merge commits in the range.\n = \n\n = \n # the source of truth\nThen model drafts the notes from them. Once done, we check its output against the initial list of PRs:
\n = # what should be there\n = # what the model wrote (#1234 -> 1234)\n\n = - # silently dropped\n = - # belongs to a different release\nIf anything is missing or extra, we don't fail and we don't ship a wrong file. We hand the discrepancy back to the agent and ask it to fix exactly those PRs:
\n\n , = \n \n break # matches the manifest exactly\n \nThis is the pattern that makes the whole thing trustworthy: a non-deterministic model wrapped in deterministic guardrails. The model is great at writing prose and unreliable at being exhaustive. So we let it write and let code enforce the consistency.
\nCompleteness is one half. Accuracy is the other. A model summarizing a PR from its title alone will cheerfully invent a code example that doesn't match the real API.
\nTo prevent that, when we fetch PR metadata we also pull the actual documentation diffs from each PR: the unified diff of any .md file under docs/ that the PR touched.
\n return \nThat diff goes into the model's context so when it writes "here's the new CLI command," it's quoting the example the PR author actually wrote in the docs. That's the same logic as before: give the model real source material and a narrow job.
\nThe prompts themselves live as Skills: small Markdown files (SKILL.md plus reference templates) checked into the repo. The release-notes skill spells out how to pick highlights, how to structure sections, when to add a doc link, etc. It reads like onboarding instructions, which is exactly the right mental model.
After the RC is published, the draft GitHub release sits there with the AI's first pass in it. This is where the human comes in:
\nminor-release run, which promotes the RC to final.The reviewer's time goes into polishing, turning a half-day of writing into a fifteen-minute editing session.
\nWe also keep a paper trail to improve over time. We archive two files side by side to a Hugging Face Bucket: the raw AI draft, uploaded at RC time before anyone touches it, and the human-edited version, uploaded when the final release is cut.
\n# at RC time: straight from the model, untouched\n\n\n# at release time: after the human review\n\nCollecting both every week gives us a growing dataset of "what the model wrote" versus "what we wished it wrote". Dataset that we can then reuse to update the agent's skill.
\nRevamping the release process was a good opportunity to tighten security, especially against supply-chain attacks.
\nNo PyPI token. Publishing uses Trusted Publishing: PyPI verifies a short-lived OIDC token minted by GitHub for this exact workflow, and issues PEP 740 attestations / Sigstore provenance for every artifact. There's no long-lived secret to leak or rotate.
\npermissions:\n id-token: write # mint the OIDC token for PyPI\n attestations: write # generate Sigstore provenance\n# ...\n- uses: pypa/gh-action-pypi-publish@v1.14.0\n with:\n attestations: true # no password, no API token, just OIDC\nThe agent runtime is pinned and verified. We don't curl | bash the latest OpenCode and hope. We pin a version and check its SHA256 before running it:
| \n | \nOpen tooling doesn't mean careless tooling.
\nAlmost nothing. A full release (notes plus the Slack announcement, across 20-40 PRs and a few rounds of prompting) costs about $0.25 on Inference Providers. With open weights billed pay-as-you-go, the only real question each week is "is there something worth shipping?", and there always is.
\nThe cadence went from one release every 4 to 6 weeks to once a week. The secondary effects were the interesting ones:
\nThis is the part we cared about most. The workflow is shaped around huggingface_hub but the structure is generic.
Reusable almost as-is:
\nminor-prerelease then minor-release then patch-release).Specific to us:
\nTo adapt it: fork the workflow file and scripts, point it at your package, rewrite the skill Markdown for your project's voice, set two repo variables (the model ID and your OpenCode version), set up Trusted Publishing on PyPI, and delete the downstream-testing job if you don't have downstreams. The trust-but-verify loop is the part worth reusing as-is. It's what makes a generated artifact safe to ship.
\nThe parts of a release that used to need a half-day of focused human work (writing notes, drafting announcements, coordinating downstream checks) are the parts a model is good at drafting. Everything else is mechanical and fits in a YAML file. The trick was never just "let the AI do it". It's to let the model draft, let deterministic code verify, and let a human decide. It's built entirely from open tools and open weights so the cost rounds to zero and anyone can run it.
\nThe full workflow file is public. If you maintain a Python library, fork it, adapt it, and let us know how it goes!
\n", "content_markdown": "`huggingface_hub` is the Python client at the base of the Hugging Face ecosystem. `transformers`, `datasets`, `diffusers`, `sentence-transformers` and dozens of other libraries depend on it to talk to the Hub. Every week we don't ship a new release is a week of fixes and features stuck on `main`.\n\nFor a long time we released every 4 to 6 weeks. We now release every week from a single GitHub Actions workflow. We built it using open-source tools and open-weights models and kept a human in the loop at the one place where judgment matters. Nothing in this post requires a vendor contract, a closed model, or infrastructure you can't run yourself. That was a design goal from the start since we wanted a workflow other maintainers could pick up and adapt.\n\nBy the end of this post, you'll have everything you need to build your own.\n\n## Where we started\n\nThe old process was partly automated, mostly manual.\n\nAlready in CI:\n\n- Publishing to PyPI once a tag was pushed.\n- Opening test branches in downstream libraries with the release candidate pinned.\n\nStill manual, every single time:\n\n- Creating the release branch, bumping the version in `__init__.py`, committing, tagging, pushing.\n- Watching the downstream CI runs and triaging failures.\n- Reading through every PR merged since the last release and writing release notes by hand: grouped by theme, with context, in a voice that didn't read like a `git log` dump.\n- Cutting the stable release after the RC period.\n- Drafting an internal Slack announcement and social posts.\n- Opening the post-release PR to bump `main` to the next `dev0`.\n\nWriting good notes for a new version was the heavy part, aggregating tens of PRs on different topics. Nothing technically hard but a few hours of focused attention. Add the announcements on top and a minor release was easily a half-day of work spread over several days.\n\n## Two kinds of work\n\nSo we decided to streamline the whole thing. Looking at that list, the work splits in two.\n\nSome steps are purely mechanical and can be automated: bumping the version, committing, tagging, pushing, opening downstream test branches, opening the post-release PR. Nobody needs to think about those. They just have to happen in the right order, every time, which is what a CI workflow is good at.\n\nThe rest is different. Writing release notes, deciding what to highlight, phrasing an announcement for a human audience: that's brain work. It's the kind of judgment that kept the release manual for years. This is where AI comes in, turning a blank page into a solid first draft in seconds. It's also where we have to be careful because a draft that looks confident and is subtly wrong is worse than no draft at all.\n\n## The design principle: open parts, reusable by anyone\n\nWhen we decided to fix this, we set one constraint up front: every moving part had to be something any maintainer could run themselves. No closed model behind an API we couldn't swap, no proprietary release platform, no secret sauce.\n\nHere's the entire stack:\n\n| Part | What it does |\n| -------------------------------------------------------------------------------------------------- | ----------------------------------------------- |\n| **GitHub Actions** | Orchestrates the whole release |\n| **[OpenCode](https://opencode.ai/)** | Agent runtime that drives the model |\n| **An open-weights model** (currently [GLM-5.2](https://huggingface.co/zai-org/GLM-5.2) from Z.ai) | Drafts the release notes and Slack announcement |\n| **[HF Inference Providers](https://huggingface.co/docs/inference-providers/index)** | Serves the model |\n| **[PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)** | Publishes the package |\n\nThe second principle: the model drafts, a human decides. Language models are good at turning thirty terse PR titles into readable release notes. They are not good at being trusted blindly. So the workflow is human-supervised: the model does the first pass, a deterministic script checks its work, and a human reviews and edits before anything ships (more on that below).\n\n## A tour of the pipeline\n\nThe full workflow is a single file, [`.github/workflows/release.yml`](https://github.com/huggingface/huggingface_hub/blob/main/.github/workflows/release.yml), triggered by hand from the Actions UI. It takes exactly one input:\n\n```yaml\non:\n workflow_dispatch:\n inputs:\n release_type:\n type: choice\n options:\n - minor-prerelease # cut an RC from main\n - minor-release # promote the RC to final\n - patch-release # bugfix on an existing release branch\n```\n\nFrom there, the jobs run roughly in this order:\n\n- **Prepare.** Compute the next version, create or reuse the release branch, bump `__version__`, commit, tag, push.\n- **Publish to PyPI.** Build and upload `huggingface_hub`. In parallel, build and upload the `hf` CLI as its own PyPI package.\n- **Release notes.** Diff the commit range since the last tag, pull PR metadata from the GitHub API, and have the model draft a structured changelog ([here's a recent one](https://github.com/huggingface/huggingface_hub/releases/tag/v1.20.0)). Saved as a *draft* GitHub release.\n- **Downstream test branches.** For RCs, open a branch in `transformers`, `datasets`, `diffusers`, `sentence-transformers` with the RC pinned, so their CI tells us fast if we broke something.\n- **Slack announcement.** Read the notes and produce an internal announcement in our team voice.\n- **Archive notes.** Upload both the raw AI draft and the human-edited version to a Hugging Face Bucket, side by side.\n- **Post-release bump.** After a stable release, open a PR on `main` bumping to the next `dev0`.\n- **Comment on shipped PRs.** Leave a \"this shipped in vX.Y.Z\" comment on every PR in the release.\n- **Sync CLI docs.** Open a PR to our [skills](https://github.com/huggingface/skills) repo with the regenerated `hf` CLI skill docs.\n- **Report to Slack.** Every step posts its status as a thread reply; a final job updates the root message with ✅ or ❌.\n\nThe remaining manual steps are reviewing and publishing the draft release notes, and reviewing and posting an internal Slack message. Those two steps are where we want a human in the loop.\n\n## Trust but verify: the human-in-the-loop core\n\nHere's the failure mode everyone worries about with AI-generated release notes: the model quietly drops a PR or invents one that isn't in this release. A changelog that's almost right is worse than no changelog because nobody re-checks it.\n\nWe don't trust the generated release notes to be complete on the first try, we verify it deterministically. Before the model runs, a Python script retrieves all PRs that belong to the release and stores them as ground truth.\n\n```python\n# Deterministic: extract PR numbers from squash-merge commits in the range.\nPR_NUMBER_PATTERN = re.compile(r\"\\(#(\\d+)\\)$\")\n\npr_numbers = [\n int(m.group(1))\n for commit in commits_since_last_tag\n if (m := PR_NUMBER_PATTERN.search(commit.title))\n]\nsave_manifest(pr_numbers) # the source of truth\n```\n\nThen model drafts the notes from them. Once done, we check its output against the initial list of PRs:\n\n```python\nexpected = set(load_manifest()) # what should be there\nfound = extract_pr_refs(notes_md) # what the model wrote (#1234 -> 1234)\n\nmissing = expected - found # silently dropped\nextra = found - expected # belongs to a different release\n```\n\nIf anything is missing or extra, we don't fail and we don't ship a wrong file. We hand the discrepancy back to the agent and ask it to fix exactly those PRs:\n\n```python\nfor _ in range(MAX_ITERATIONS):\n missing, extra = validate(notes)\n if not missing and not extra:\n break # matches the manifest exactly\n run_agent_fix(missing_prs=missing, extra_prs=extra)\n```\n\nThis is the pattern that makes the whole thing trustworthy: a non-deterministic model wrapped in deterministic guardrails. The model is great at writing prose and unreliable at being exhaustive. So we let it write and let code enforce the consistency.\n\n## Grounding the model so it doesn't make things up\n\nCompleteness is one half. Accuracy is the other. A model summarizing a PR from its title alone will cheerfully invent a code example that doesn't match the real API.\n\nTo prevent that, when we fetch PR metadata we also pull the actual documentation diffs from each PR: the unified diff of any `.md` file under `docs/` that the PR touched.\n\n```python\ndef fetch_doc_diffs(pr):\n return [\n {\"filename\": f.filename, \"status\": f.status, \"patch\": f.patch}\n for f in pr.get_files()\n if f.filename.startswith(\"docs/\") and f.filename.endswith(\".md\") and f.patch\n ]\n```\n\nThat diff goes into the model's context so when it writes \"here's the new CLI command,\" it's quoting the example the PR author actually wrote in the docs. That's the same logic as before: give the model real source material and a narrow job.\n\nThe prompts themselves live as [Skills](https://github.com/huggingface/huggingface_hub/tree/main/.opencode/skills/hf-release-notes): small Markdown files (`SKILL.md` plus reference templates) checked into the repo. The release-notes skill spells out how to pick highlights, how to structure sections, when to add a doc link, etc. It reads like onboarding instructions, which is exactly the right mental model.\n\n## The human checkpoint\n\nAfter the RC is published, the draft GitHub release sits there with the AI's first pass in it. This is where the human comes in:\n\n1. A reviewer reads the draft, edits for tone and emphasis, fixes anything the model over- or under-weighted.\n2. Only then do they trigger the `minor-release` run, which promotes the RC to final.\n\nThe reviewer's time goes into polishing, turning a half-day of writing into a fifteen-minute editing session.\n\nWe also keep a paper trail to improve over time. We archive two files side by side to a Hugging Face Bucket: the raw AI draft, uploaded at RC time before anyone touches it, and the human-edited version, uploaded when the final release is cut.\n\n```bash\n# at RC time: straight from the model, untouched\nhf cp release_notes_raw.txt \"hf://buckets/huggingface/releases/huggingface_hub/${V}/release_notes_raw.txt\"\n\n# at release time: after the human review\nhf cp release_notes_edited.txt \"hf://buckets/huggingface/releases/huggingface_hub/${V}/release_notes_edited.txt\"\n```\n\nCollecting both every week gives us a growing dataset of \"what the model wrote\" versus \"what we wished it wrote\". Dataset that we can then reuse to update the agent's skill.\n\n## Open and secure plumbing\n\nRevamping the release process was a good opportunity to tighten security, especially against supply-chain attacks.\n\n**No PyPI token.** Publishing uses [Trusted Publishing](https://docs.pypi.org/trusted-publishers/): PyPI verifies a short-lived OIDC token minted by GitHub for this exact workflow, and issues [PEP 740](https://peps.python.org/pep-0740/) attestations / Sigstore provenance for every artifact. There's no long-lived secret to leak or rotate.\n\n```yaml\npermissions:\n id-token: write # mint the OIDC token for PyPI\n attestations: write # generate Sigstore provenance\n# ...\n- uses: pypa/gh-action-pypi-publish@v1.14.0\n with:\n attestations: true # no password, no API token, just OIDC\n```\n\n**The agent runtime is pinned and verified.** We don't `curl | bash` the latest OpenCode and hope. We pin a version and check its SHA256 before running it:\n\n```bash\ncurl -fsSL https://opencode.ai/install | bash -s -- --version \"${OPENCODE_VERSION}\"\necho \"${OPENCODE_SHA256} $(which opencode)\" | sha256sum -c -\n```\n\nOpen tooling doesn't mean careless tooling.\n\n## So, what did it cost?\n\nAlmost nothing. A full release (notes plus the Slack announcement, across 20-40 PRs and a few rounds of prompting) costs about **$0.25** on Inference Providers. With open weights billed pay-as-you-go, the only real question each week is \"is there something worth shipping?\", and there always is.\n\n## What changed in practice\n\nThe cadence went from one release every 4 to 6 weeks to once a week. The secondary effects were the interesting ones:\n\n- **Notes got better, not worse.** A first draft always exists, so review time goes to polishing. Grouping is more consistent and we omit fewer things.\n- **Breakages surface earlier.** Downstream test branches on every RC catch integration issues during the candidate window.\n- **Contributor loops shortened.** The automatic \"shipped in vX.Y.Z\" comment turned out to matter more than we expected. When someone reports an issue on a closed PR, everyone can immediately see which release the fix is in. That used to be a manual tag hunt.\n\n## Make it yours\n\nThis is the part we cared about most. The workflow is shaped around `huggingface_hub` but the structure is generic.\n\n**Reusable almost as-is:**\n\n- The trigger and version-bump logic (`minor-prerelease` then `minor-release` then `patch-release`).\n- The trust-but-verify loop: deterministic manifest, model draft, validate, re-prompt. This is the transferable idea, independent of what you're generating.\n- OIDC Trusted Publishing, pinned and checksum-verified runtime, Slack threading.\n- The skill-based prompts: swap the templates, keep the structure.\n\n**Specific to us:**\n\n- The downstream repo list and their dependency-pin formats.\n- The exact section taxonomy and tone in the skills.\n- The Slack and bucket destinations.\n\nTo adapt it: fork the [workflow file](https://github.com/huggingface/huggingface_hub/blob/main/.github/workflows/release.yml) and [scripts](https://github.com/huggingface/huggingface_hub/tree/main/utils/release_notes), point it at your package, rewrite the [skill Markdown](https://github.com/huggingface/huggingface_hub/blob/main/.opencode/skills/hf-release-notes/SKILL.md) for your project's voice, set two repo variables (the model ID and your OpenCode version), set up Trusted Publishing on PyPI, and delete the downstream-testing job if you don't have downstreams. The trust-but-verify loop is the part worth reusing as-is. It's what makes a generated artifact safe to ship.\n\n## What's next\n\n- **Auto-triaging downstream failures.** Today the workflow opens test branches and a human reads the CI. An obvious next step is to check the failing logs to report them in the internal slack message.\n- **Extending the pattern.** Most of this is generic. We expect to reuse large parts across other Python libraries in our ecosystem.\n\n## Takeaway\n\nThe parts of a release that used to need a half-day of focused human work (writing notes, drafting announcements, coordinating downstream checks) are the parts a model is good at drafting. Everything else is mechanical and fits in a YAML file. The trick was never just \"let the AI do it\". It's to let the model draft, let deterministic code verify, and let a human decide. It's built entirely from open tools and open weights so the cost rounds to zero and anyone can run it.\n\nThe full workflow file is public. If you maintain a Python library, [fork it](https://github.com/huggingface/huggingface_hub/blob/main/.github/workflows/release.yml), adapt it, and let us know how it goes!\n", "dateCreated": "2026-10-19T01:26:53.998049939+00:00", "date_created": "2026-06-23T00:00:00+00:00", "date_modified": "2026-06-23T00:00:00+00:00", "date_published": "2026-06-23T00:00:00+00:00", "description": "huggingface_hub is the Python client at the base of the Hugging Face ecosystem. transformers, datasets, diffusers, sentence-transformers and dozens of other libraries depend on it to talk to the Hub. Every week we don't ship a new release…", "external_url": "https://huggingface.co/blog/huggingface-hub-release-ci", "git": { "commit": "ebb0941c5c06a2ab2377342d607535262a3e969e", "path": "items/huggingface-co/2026/06/2026-06-23-shipping-huggingface-hub-every-week-with-ai-open-tools-and.md", "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/ebb0941c5c06a2ab2377342d607535262a3e969e/items/huggingface-co/2026/06/2026-06-23-shipping-huggingface-hub-every-week-with-ai-open-tools-and.md" }, "id": "urn:aggr:item:757263ad88cb66349e835262b480b8c641c38146", "isBasedOn": { "@id": "https://huggingface.co/blog/huggingface-hub-release-ci" }, "mainEntity": { "@id": "https://huggingface.co/blog/huggingface-hub-release-ci", "@type": "CreativeWork", "archivedAt": { "@id": "https://aggr.aymericbeaumet.com/items/huggingface-co/2026-06-23-shipping-huggingface-hub-every-week-with-ai-open-tools-and/#webpage" }, "dateModified": "2026-06-23T00:00:00+00:00", "datePublished": "2026-06-23T00:00:00+00:00", "headline": "Shipping huggingface_hub every week with AI, open tools, and a human in the loop", "image": { "@type": "ImageObject", "caption": null, "height": 90, "url": "https://huggingface.co/blog/assets/huggingface-hub-release-ci/thumbnail.png", "width": 160 }, "timeRequired": "PT10M", "url": "https://huggingface.co/blog/huggingface-hub-release-ci", "wordCount": 2218 }, "name": "Archived snapshot: Shipping huggingface_hub every week with AI, open tools, and a human in the loop", "preview": { "alt": null, "color": null, "height": 90, "placeholder": { "data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=", "hash": "" }, "url": "https://huggingface.co/blog/assets/huggingface-hub-release-ci/thumbnail.png", "width": 160 }, "reading_minutes": 10, "replicated_at": null, "source": "huggingface-co", "source_name": "Hugging Face - Blog", "summary": null, "tags": [], "temporalCoverage": "2026-10-19T01:26:53.998049939+00:00", "title": "Shipping huggingface_hub every week with AI, open tools, and a human in the loop", "url": "https://aggr.aymericbeaumet.com/items/huggingface-co/2026-06-23-shipping-huggingface-hub-every-week-with-ai-open-tools-and/", "word_count": 2218 }