Migrating Your GitHub CI to Hugging Face Jobs
Log In<br>Sign Up
Back to Articles
Migrating Your GitHub CI to Hugging Face Jobs
Published<br>June 9, 2026<br>Update on GitHub<br>Upvote 8
+2
Abubakar Abid abidlabs Follow
If you have a GitHub repository and you have GitHub Actions enabled, you probably use GitHub-hosted runners for CI. That is the default for many projects because it is simple: add a workflow, write runs-on: ubuntu-latest, and GitHub gives you a machine.
That default is convenient, but it also has limits. GitHub Actions can be slow or down for maintenance, the hosted machines are generic, and GPU access is not something most open-source projects can just turn on. For Trackio, those limits started to matter. We wanted both reliable CPU CI for basic unit tests and frontend checks, but also GPU CI for tests that need to run on actual CUDA hardware.
So built an alternative: keep GitHub Actions in charge of CI, but run the jobs on Hugging Face Jobs.
The result: Trackio's CI now runs on Hugging Face Jobs and streams back real-time logs, cutting our CI time for CPU jobs by about 30% and enabling a whole new test suite that runs on GPU machines !
In this article, we explain step-by-step how to recreate the same setup for your GitHub repo. If you are using an agent, you can point it to this article, since we provide CLI instructions alongside browser-based instructions for us humans.
Let's start with a quick intro to Hugging Face Jobs!
What is Hugging Face Jobs?
Hugging Face Jobs lets you run commands or scripts on Hugging Face's serverless infrastructure with almost any hardware flavor. A Job is essentially:
a command to run
a Docker image, from Docker Hub or a Hugging Face Space
a hardware flavor, such as CPU or t4-small or h200 GPU
optional environment variables and secrets
For example, you can run:
hf jobs run python:3.12 python -c "print('Hello world')"
or
hf jobs uv run --flavor a10g-small "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py"
That makes Jobs a natural fit for CI. CI jobs are already command-driven, already run in clean environments, and often benefit from choosing exactly the right hardware. For ML libraries, the GPU case is especially compelling: you can run a test suite on real GPU hardware without maintaining your own always-on runner.
The key step is connecting GitHub Actions to HF Jobs, which we describe below.
The architecture
For this setup, we created huggingface/jobs-actions, a small bridge that turns a GitHub Actions job into an ephemeral self-hosted runner running inside an HF Job.
The complete flow looks like this:
A pull request triggers a GitHub Actions workflow.
GitHub queues any job whose runs-on label is not available, for example hf-jobs-cpu-upgrade or hf-jobs-t4-small, and sends a signed workflow_job.queued webhook to the dispatcher through the GitHub App.
The dispatcher Space verifies the webhook, checks for an hf-jobs-* label, mints a short-lived GitHub runner registration token, and starts an HF Job on the matching hardware.
The HF Job boots an ephemeral GitHub Actions runner and registers it with the repo using that one-shot token.
GitHub assigns the pending workflow job to that runner; the runner executes the CI job, reports status back to GitHub, and exits.
From GitHub's point of view, this is just a self-hosted runner. From Hugging Face's point of view, it is just a Job that launches a container to run the workflow steps from the repo’s GitHub Actions.
Step 1: Duplicate the dispatcher Space
The first thing you need is the dispatcher. This is a small Docker Space that receives GitHub workflow_job webhook events and launches HF Jobs in response.
Create this first because the GitHub App needs a webhook URL, and that URL comes from the Space. This Space should be under your own namespace or under a Hugging Face org that you have write access to.
Web setup
Go to huggingface/jobs-actions-dispatcher and click Duplicate this Space .
Use:
Owner: your HF user or org<br>Name: jobs-actions-dispatcher<br>Hardware: cpu-upgrade
Use cpu-upgrade for real CI so the dispatcher stays available for GitHub webhooks. cpu-basic is fine for testing and will probably work, but it can sleep after inactivity; if GitHub's webhook arrives while it is waking up, the workflow may stay queued forever.
After it builds, open the duplicated Space. You will see a section that says "Required Space secrets," which you can ignore for now. The landing page should display the GitHub App webhook URL you need in the next step. It will look like this:
https://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space/webhook
CLI setup
If you'd prefer to set up the dispatcher Space with an agent or use a CLI workflow:
export HF_NAMESPACE=your-hf-user-or-org<br>export SPACE_ID="$HF_NAMESPACE/jobs-actions-dispatcher"
hf repo duplicate huggingface/jobs-actions-dispatcher "$SPACE_ID" \<br>--type space \<br>--flavor cpu-upgrade \<br>--exist-ok
Then set:
export...