{ "@context": "https://schema.org", "@id": "https://aggr.aymericbeaumet.com/items/huggingface-co/2026-06-09-migrating-your-github-ci-to-hugging-face-jobs/#webpage", "@type": [ "WebPage", "ArchiveComponent" ], "articleBody": "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.\n\nThat 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](https://github.com/gradio-app/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.\n\nSo built an alternative: keep GitHub Actions in charge of CI, but run the jobs on [Hugging Face Jobs](https://huggingface.co/docs/hub/en/jobs-overview).\n\nThe 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**!\n\nIn 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.\n\nLet's start with a quick intro to Hugging Face Jobs!\n\n## What is Hugging Face Jobs?\n\n[Hugging Face Jobs](https://huggingface.co/docs/hub/en/jobs-overview) lets you run commands or scripts on Hugging Face's serverless infrastructure with almost any hardware flavor. A Job is essentially:\n\n- a command to run\n- a Docker image, from Docker Hub or a Hugging Face Space\n- a hardware flavor, such as CPU or `t4-small` or `h200` GPU\n- optional environment variables and secrets\n\nFor example, you can run:\n\n```bash\nhf jobs run python:3.12 python -c \"print('Hello world')\"\n```\n\nor\n\n```bash\nhf jobs uv run --flavor a10g-small \"https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py\" \n```\n\nThat 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.\n\nThe key step is connecting GitHub Actions to HF Jobs, which we describe below.\n\n## The architecture\n\nFor this setup, we created [`huggingface/jobs-actions`](https://github.com/huggingface/jobs-actions), a small bridge that turns a GitHub Actions job into an ephemeral self-hosted runner running inside an HF Job.\n\nThe complete flow looks like this:\n\n1. A pull request triggers a GitHub Actions workflow.\n2. 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.\n3. 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.\n4. The HF Job boots an ephemeral GitHub Actions runner and registers it with the repo using that one-shot token.\n5. GitHub assigns the pending workflow job to that runner; the runner executes the CI job, reports status back to GitHub, and exits.\n\nFrom 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.\n\n## Step 1: Duplicate the dispatcher Space\n\nThe 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.\n\nCreate 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.\n\n#### Web setup\n\nGo to [`huggingface/jobs-actions-dispatcher`](https://huggingface.co/spaces/huggingface/jobs-actions-dispatcher) and click **Duplicate this Space**.\n\n![image](https://github.com/user-attachments/assets/c8b450c3-b801-43dc-97ff-954d9bbaf975)\n\nUse:\n\n```text\nOwner: your HF user or org\nName: jobs-actions-dispatcher\nHardware: cpu-upgrade\n```\n\nUse `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.\n\nAfter 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:\n\n```text\nhttps://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space/webhook\n```\n\n#### CLI setup\n\nIf you'd prefer to set up the dispatcher Space with an agent or use a CLI workflow:\n\n```bash\nexport HF_NAMESPACE=your-hf-user-or-org\nexport SPACE_ID=\"$HF_NAMESPACE/jobs-actions-dispatcher\"\n\nhf repo duplicate huggingface/jobs-actions-dispatcher \"$SPACE_ID\" \\\n --type space \\\n --flavor cpu-upgrade \\\n --exist-ok\n```\n\nThen set:\n\n```bash\nexport DISPATCHER_URL=\"https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space\"\n```\n\n## Step 2: Create and install the GitHub App\n\nNext, create and install the GitHub App from the dispatcher Space itself. This App needs permission to listen for queued workflow jobs and create ephemeral self-hosted runner registration tokens.\n\n### Web setup\n\nOpen your duplicated dispatcher Space:\n\n```text\nhttps://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space\n```\n\nIn the setup form, enter the GitHub repo whose CI should run on HF Jobs:\n\n```text\nYOUR-GITHUB-ORG/YOUR-REPO\n```\n\nThen click the button to create the GitHub App. GitHub will ask you to choose a name for the App; the name can be anything, as long as it is available in your GitHub account or org. After you submit, the final screen tells you exactly how to upload the App credentials to the dispatcher Space with the `hf` CLI.\n\n**Important note**: you will need to provide an [Hugging Face token](https://huggingface.co/settings/tokens) that has permissions to launch Jobs, corresponding to your personal account or an org under which Jobs should be charged. This token should be saved as the `HF_TOKEN` secret in your dispatcher Space.\n\nFinally, you will install the App on the same GitHub repo you entered in the Space. In the Trackio setup, we installed it on `gradio-app/trackio`.\n\n### Agent-assisted setup\n\nThe GitHub App manifest flow is still browser-based, but an agent can follow the same Space-driven path:\n\n```bash\nexport HF_NAMESPACE=your-hf-user-or-org\nexport GITHUB_REPO=YOUR-GITHUB-ORG/YOUR-REPO\nopen \"https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space\"\n```\n\nPaste `$GITHUB_REPO` into the Space, click the GitHub App creation button, choose any available App name, and follow the generated GitHub instructions.\n\nAfter the App exists, install it on your repo from the App settings page. For a GitHub org, the installation settings are under:\n\n```text\nhttps://github.com/organizations/YOUR-GITHUB-ORG/settings/installations\n```\n\n## Step 3: Final dispatcher settings\n\nAt this point, the dispatcher Space should be configured. The GitHub App setup flow generated the commands that upload the App credentials, webhook secret, and Hugging Face token to the Space.\n\n![image](https://github.com/user-attachments/assets/0fc8ac73-f93a-419b-bd80-70da2756f50c)\n\nBy default, HF Jobs are launched under the same namespace as the dispatcher Space. Optionally, set `HF_NAMESPACE` as a Space variable if you want to bill jobs to a different Hugging Face user or org:\n\n```bash\nexport SPACE_ID=YOUR-HF-NAMESPACE/jobs-actions-dispatcher\nhf spaces variables add \"$SPACE_ID\" -e HF_NAMESPACE=your-billing-namespace\nhf spaces restart \"$SPACE_ID\"\n```\n\nThe token you set in Step 2 should correspond to this namespace.\n\n## Step 4: Change `runs-on`\n\nThe actual workflow change is small. Instead of:\n\n```yaml\nruns-on: ubuntu-latest\n```\n\nuse one of the labels handled by the dispatcher:\n\n```yaml\nruns-on: hf-jobs-cpu-upgrade\n```\n\nFor GPU tests, use a GPU label:\n\n```yaml\nruns-on: hf-jobs-t4-small\n```\n\nFor any GitHub Action you'd like to run on HF Jobs, this 1-line change is all you need!\n\n## Step 5: Test it out\n\nTo add a minimal smoke-test workflow from the CLI:\n\n```bash\nmkdir -p .github/workflows\ncat > .github/workflows/hf-jobs-test.yml <<'EOF'\nname: HF Jobs Test\n\non:\n pull_request:\n push:\n branches: [main]\n workflow_dispatch:\n\njobs:\n test:\n runs-on: hf-jobs-cpu-upgrade\n steps:\n - uses: actions/checkout@v4\n - run: echo \"Hello from Hugging Face Jobs\"\nEOF\n\ngit add .github/workflows/hf-jobs-test.yml\ngit commit -m \"Run CI on Hugging Face Jobs\"\ngit push\n```\n\nTo verify from the CLI:\n\n```bash\ngh run list --repo YOUR-GITHUB-ORG/YOUR-REPO --limit 5\nhf jobs ps --namespace \"$HF_NAMESPACE\"\nhf spaces logs \"$SPACE_ID\"\n```\n\nYou should be able to see logs just like a regular GitHub Action—for example, in this [Trackio PR #565](https://github.com/gradio-app/trackio/pull/565).\n\nAnd that's it!\n\n*Note on choosing the right Docker image*\n\nOur first CPU setup used `ubuntu:22.04` and installed missing system packages during every run. That worked, but it was slower than it needed to be. GitHub's `ubuntu-latest` image includes a lot of developer tooling by default; a bare Ubuntu image does not.\n\nFor Trackio, the UI tests need Playwright browsers, Node, ffmpeg, sqlite, git, and normal Linux build dependencies. Hugging Face Jobs supports using any [Docker image](https://huggingface.co/docs/hub/jobs-popular-images), so we switched to the Microsoft Playwright image, which worked well:\n\n```text\nmcr.microsoft.com/playwright:v1.60.0-jammy\n```\n\nFor GPU jobs, we used:\n\n```text\nnvidia/cuda:12.4.0-runtime-ubuntu22.04\n```\n\n## Results\n\nHere are the numbers from the Trackio CI:\n\n| Runner setup | Runtime | Compared to GitHub average |\n| ------------------------------- | ------- | ----------------------------- |\n| GitHub `ubuntu-latest` baseline | `1m40s` | baseline |\n| HF Jobs CPU, Playwright image | `1m10s` | `-30s`, about `30%` faster |\n| HF Jobs GPU, `t4-small` label | `45s` | no GitHub-hosted GPU baseline |\n\nThe biggest win was GPU CI. The Trackio GPU check ran on HF Jobs and passed in `45s`, costing less than a cent at the `t4-small` rate for that duration.\n\nThe CPU result was also encouraging. With the right image, the Linux test job was faster than the GitHub-hosted baseline. That suggests HF Jobs can be a practical CI backend, especially for ML projects that need custom images or accelerators.\n\nLogs were another pleasant surprise. GitHub Actions logs are useful, but the web UI can be heavy for large logs. HF Jobs logs are easy to fetch from the CLI:\n\n```bash\nhf jobs logs > logs.txt\n```\n\nThat makes them easy to inspect with local tools or coding agents. In our bridge, we also mirrored the GitHub Actions job log into the HF Job log, so either system had enough information to debug a run.\n\nFinally, although we didn't need them for Trackio's CI, HF Jobs also [supports mounting volumes](https://huggingface.co/docs/huggingface_hub/en/guides/jobs#mount-a-volume), which can be very helpful if you need to load datasets or models from Hugging Face quickly as part of your CI.\n\nHopefully, this gives you all you need to try HF Jobs for running your GitHub Actions!\n", "authors": [], "captured_at": "2026-10-19T01:26:53.998049939+00:00", "category": "ai", "content_html": "

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.

\n

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.

\n

So built an alternative: keep GitHub Actions in charge of CI, but run the jobs on Hugging Face Jobs.

\n

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!

\n

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.

\n

Let's start with a quick intro to Hugging Face Jobs!

\n

What is Hugging Face Jobs?

\n

Hugging Face Jobs lets you run commands or scripts on Hugging Face's serverless infrastructure with almost any hardware flavor. A Job is essentially:

\n\n

For example, you can run:

\n
hf jobs run python:3.12 python -c "print('Hello world')"\n
\n

or

\n
hf jobs uv run --flavor a10g-small "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py" \n
\n

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.

\n

The key step is connecting GitHub Actions to HF Jobs, which we describe below.

\n

The architecture

\n

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.

\n

The complete flow looks like this:

\n
    \n
  1. A pull request triggers a GitHub Actions workflow.
    2. \n
  2. 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.
    3. \n
  3. 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.
    4. \n
  4. The HF Job boots an ephemeral GitHub Actions runner and registers it with the repo using that one-shot token.
    5. \n
  5. GitHub assigns the pending workflow job to that runner; the runner executes the CI job, reports status back to GitHub, and exits.
    6. \n
\n

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.

\n

Step 1: Duplicate the dispatcher Space

\n

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.

\n

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.

\n

Web setup

\n

Go to huggingface/jobs-actions-dispatcher and click Duplicate this Space.

\n

\"image\"

\n

Use:

\n
Owner: your HF user or org\nName: jobs-actions-dispatcher\nHardware: cpu-upgrade\n
\n

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.

\n

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:

\n
https://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space/webhook\n
\n

CLI setup

\n

If you'd prefer to set up the dispatcher Space with an agent or use a CLI workflow:

\n
export HF_NAMESPACE=your-hf-user-or-org\nexport SPACE_ID="$HF_NAMESPACE/jobs-actions-dispatcher"\n\nhf repo duplicate huggingface/jobs-actions-dispatcher "$SPACE_ID" \\\n  --type space \\\n  --flavor cpu-upgrade \\\n  --exist-ok\n
\n

Then set:

\n
export DISPATCHER_URL="https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space"\n
\n

Step 2: Create and install the GitHub App

\n

Next, create and install the GitHub App from the dispatcher Space itself. This App needs permission to listen for queued workflow jobs and create ephemeral self-hosted runner registration tokens.

\n

Web setup

\n

Open your duplicated dispatcher Space:

\n
https://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space\n
\n

In the setup form, enter the GitHub repo whose CI should run on HF Jobs:

\n
YOUR-GITHUB-ORG/YOUR-REPO\n
\n

Then click the button to create the GitHub App. GitHub will ask you to choose a name for the App; the name can be anything, as long as it is available in your GitHub account or org. After you submit, the final screen tells you exactly how to upload the App credentials to the dispatcher Space with the hf CLI.

\n

Important note: you will need to provide an Hugging Face token that has permissions to launch Jobs, corresponding to your personal account or an org under which Jobs should be charged. This token should be saved as the HF_TOKEN secret in your dispatcher Space.

\n

Finally, you will install the App on the same GitHub repo you entered in the Space. In the Trackio setup, we installed it on gradio-app/trackio.

\n

Agent-assisted setup

\n

The GitHub App manifest flow is still browser-based, but an agent can follow the same Space-driven path:

\n
export HF_NAMESPACE=your-hf-user-or-org\nexport GITHUB_REPO=YOUR-GITHUB-ORG/YOUR-REPO\nopen "https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space"\n
\n

Paste $GITHUB_REPO into the Space, click the GitHub App creation button, choose any available App name, and follow the generated GitHub instructions.

\n

After the App exists, install it on your repo from the App settings page. For a GitHub org, the installation settings are under:

\n
https://github.com/organizations/YOUR-GITHUB-ORG/settings/installations\n
\n

Step 3: Final dispatcher settings

\n

At this point, the dispatcher Space should be configured. The GitHub App setup flow generated the commands that upload the App credentials, webhook secret, and Hugging Face token to the Space.

\n

\"image\"

\n

By default, HF Jobs are launched under the same namespace as the dispatcher Space. Optionally, set HF_NAMESPACE as a Space variable if you want to bill jobs to a different Hugging Face user or org:

\n
export SPACE_ID=YOUR-HF-NAMESPACE/jobs-actions-dispatcher\nhf spaces variables add "$SPACE_ID" -e HF_NAMESPACE=your-billing-namespace\nhf spaces restart "$SPACE_ID"\n
\n

The token you set in Step 2 should correspond to this namespace.

\n

Step 4: Change runs-on

\n

The actual workflow change is small. Instead of:

\n
runs-on: ubuntu-latest\n
\n

use one of the labels handled by the dispatcher:

\n
runs-on: hf-jobs-cpu-upgrade\n
\n

For GPU tests, use a GPU label:

\n
runs-on: hf-jobs-t4-small\n
\n

For any GitHub Action you'd like to run on HF Jobs, this 1-line change is all you need!

\n

Step 5: Test it out

\n

To add a minimal smoke-test workflow from the CLI:

\n
mkdir -p .github/workflows\ncat > .github/workflows/hf-jobs-test.yml <<'EOF'\nname: HF Jobs Test\n\non:\n  pull_request:\n  push:\n    branches: [main]\n  workflow_dispatch:\n\njobs:\n  test:\n    runs-on: hf-jobs-cpu-upgrade\n    steps:\n      - uses: actions/checkout@v4\n      - run: echo "Hello from Hugging Face Jobs"\nEOF\n\ngit add .github/workflows/hf-jobs-test.yml\ngit commit -m "Run CI on Hugging Face Jobs"\ngit push\n
\n

To verify from the CLI:

\n
gh run list --repo YOUR-GITHUB-ORG/YOUR-REPO --limit 5\nhf jobs ps --namespace "$HF_NAMESPACE"\nhf spaces logs "$SPACE_ID"\n
\n

You should be able to see logs just like a regular GitHub Action—for example, in this Trackio PR #565.

\n

And that's it!

\n

Note on choosing the right Docker image

\n

Our first CPU setup used ubuntu:22.04 and installed missing system packages during every run. That worked, but it was slower than it needed to be. GitHub's ubuntu-latest image includes a lot of developer tooling by default; a bare Ubuntu image does not.

\n

For Trackio, the UI tests need Playwright browsers, Node, ffmpeg, sqlite, git, and normal Linux build dependencies. Hugging Face Jobs supports using any Docker image, so we switched to the Microsoft Playwright image, which worked well:

\n
mcr.microsoft.com/playwright:v1.60.0-jammy\n
\n

For GPU jobs, we used:

\n
nvidia/cuda:12.4.0-runtime-ubuntu22.04\n
\n

Results

\n

Here are the numbers from the Trackio CI:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Runner setupRuntimeCompared to GitHub average
GitHub ubuntu-latest baseline1m40sbaseline
HF Jobs CPU, Playwright image1m10s-30s, about 30% faster
HF Jobs GPU, t4-small label45sno GitHub-hosted GPU baseline
\n

The biggest win was GPU CI. The Trackio GPU check ran on HF Jobs and passed in 45s, costing less than a cent at the t4-small rate for that duration.

\n

The CPU result was also encouraging. With the right image, the Linux test job was faster than the GitHub-hosted baseline. That suggests HF Jobs can be a practical CI backend, especially for ML projects that need custom images or accelerators.

\n

Logs were another pleasant surprise. GitHub Actions logs are useful, but the web UI can be heavy for large logs. HF Jobs logs are easy to fetch from the CLI:

\n
hf jobs logs <job_id> > logs.txt\n
\n

That makes them easy to inspect with local tools or coding agents. In our bridge, we also mirrored the GitHub Actions job log into the HF Job log, so either system had enough information to debug a run.

\n

Finally, although we didn't need them for Trackio's CI, HF Jobs also supports mounting volumes, which can be very helpful if you need to load datasets or models from Hugging Face quickly as part of your CI.

\n

Hopefully, this gives you all you need to try HF Jobs for running your GitHub Actions!

\n", "content_markdown": "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.\n\nThat 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](https://github.com/gradio-app/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.\n\nSo built an alternative: keep GitHub Actions in charge of CI, but run the jobs on [Hugging Face Jobs](https://huggingface.co/docs/hub/en/jobs-overview).\n\nThe 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**!\n\nIn 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.\n\nLet's start with a quick intro to Hugging Face Jobs!\n\n## What is Hugging Face Jobs?\n\n[Hugging Face Jobs](https://huggingface.co/docs/hub/en/jobs-overview) lets you run commands or scripts on Hugging Face's serverless infrastructure with almost any hardware flavor. A Job is essentially:\n\n- a command to run\n- a Docker image, from Docker Hub or a Hugging Face Space\n- a hardware flavor, such as CPU or `t4-small` or `h200` GPU\n- optional environment variables and secrets\n\nFor example, you can run:\n\n```bash\nhf jobs run python:3.12 python -c \"print('Hello world')\"\n```\n\nor\n\n```bash\nhf jobs uv run --flavor a10g-small \"https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py\" \n```\n\nThat 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.\n\nThe key step is connecting GitHub Actions to HF Jobs, which we describe below.\n\n## The architecture\n\nFor this setup, we created [`huggingface/jobs-actions`](https://github.com/huggingface/jobs-actions), a small bridge that turns a GitHub Actions job into an ephemeral self-hosted runner running inside an HF Job.\n\nThe complete flow looks like this:\n\n1. A pull request triggers a GitHub Actions workflow.\n2. 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.\n3. 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.\n4. The HF Job boots an ephemeral GitHub Actions runner and registers it with the repo using that one-shot token.\n5. GitHub assigns the pending workflow job to that runner; the runner executes the CI job, reports status back to GitHub, and exits.\n\nFrom 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.\n\n## Step 1: Duplicate the dispatcher Space\n\nThe 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.\n\nCreate 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.\n\n#### Web setup\n\nGo to [`huggingface/jobs-actions-dispatcher`](https://huggingface.co/spaces/huggingface/jobs-actions-dispatcher) and click **Duplicate this Space**.\n\n![image](https://github.com/user-attachments/assets/c8b450c3-b801-43dc-97ff-954d9bbaf975)\n\nUse:\n\n```text\nOwner: your HF user or org\nName: jobs-actions-dispatcher\nHardware: cpu-upgrade\n```\n\nUse `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.\n\nAfter 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:\n\n```text\nhttps://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space/webhook\n```\n\n#### CLI setup\n\nIf you'd prefer to set up the dispatcher Space with an agent or use a CLI workflow:\n\n```bash\nexport HF_NAMESPACE=your-hf-user-or-org\nexport SPACE_ID=\"$HF_NAMESPACE/jobs-actions-dispatcher\"\n\nhf repo duplicate huggingface/jobs-actions-dispatcher \"$SPACE_ID\" \\\n --type space \\\n --flavor cpu-upgrade \\\n --exist-ok\n```\n\nThen set:\n\n```bash\nexport DISPATCHER_URL=\"https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space\"\n```\n\n## Step 2: Create and install the GitHub App\n\nNext, create and install the GitHub App from the dispatcher Space itself. This App needs permission to listen for queued workflow jobs and create ephemeral self-hosted runner registration tokens.\n\n### Web setup\n\nOpen your duplicated dispatcher Space:\n\n```text\nhttps://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space\n```\n\nIn the setup form, enter the GitHub repo whose CI should run on HF Jobs:\n\n```text\nYOUR-GITHUB-ORG/YOUR-REPO\n```\n\nThen click the button to create the GitHub App. GitHub will ask you to choose a name for the App; the name can be anything, as long as it is available in your GitHub account or org. After you submit, the final screen tells you exactly how to upload the App credentials to the dispatcher Space with the `hf` CLI.\n\n**Important note**: you will need to provide an [Hugging Face token](https://huggingface.co/settings/tokens) that has permissions to launch Jobs, corresponding to your personal account or an org under which Jobs should be charged. This token should be saved as the `HF_TOKEN` secret in your dispatcher Space.\n\nFinally, you will install the App on the same GitHub repo you entered in the Space. In the Trackio setup, we installed it on `gradio-app/trackio`.\n\n### Agent-assisted setup\n\nThe GitHub App manifest flow is still browser-based, but an agent can follow the same Space-driven path:\n\n```bash\nexport HF_NAMESPACE=your-hf-user-or-org\nexport GITHUB_REPO=YOUR-GITHUB-ORG/YOUR-REPO\nopen \"https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space\"\n```\n\nPaste `$GITHUB_REPO` into the Space, click the GitHub App creation button, choose any available App name, and follow the generated GitHub instructions.\n\nAfter the App exists, install it on your repo from the App settings page. For a GitHub org, the installation settings are under:\n\n```text\nhttps://github.com/organizations/YOUR-GITHUB-ORG/settings/installations\n```\n\n## Step 3: Final dispatcher settings\n\nAt this point, the dispatcher Space should be configured. The GitHub App setup flow generated the commands that upload the App credentials, webhook secret, and Hugging Face token to the Space.\n\n![image](https://github.com/user-attachments/assets/0fc8ac73-f93a-419b-bd80-70da2756f50c)\n\nBy default, HF Jobs are launched under the same namespace as the dispatcher Space. Optionally, set `HF_NAMESPACE` as a Space variable if you want to bill jobs to a different Hugging Face user or org:\n\n```bash\nexport SPACE_ID=YOUR-HF-NAMESPACE/jobs-actions-dispatcher\nhf spaces variables add \"$SPACE_ID\" -e HF_NAMESPACE=your-billing-namespace\nhf spaces restart \"$SPACE_ID\"\n```\n\nThe token you set in Step 2 should correspond to this namespace.\n\n## Step 4: Change `runs-on`\n\nThe actual workflow change is small. Instead of:\n\n```yaml\nruns-on: ubuntu-latest\n```\n\nuse one of the labels handled by the dispatcher:\n\n```yaml\nruns-on: hf-jobs-cpu-upgrade\n```\n\nFor GPU tests, use a GPU label:\n\n```yaml\nruns-on: hf-jobs-t4-small\n```\n\nFor any GitHub Action you'd like to run on HF Jobs, this 1-line change is all you need!\n\n## Step 5: Test it out\n\nTo add a minimal smoke-test workflow from the CLI:\n\n```bash\nmkdir -p .github/workflows\ncat > .github/workflows/hf-jobs-test.yml <<'EOF'\nname: HF Jobs Test\n\non:\n pull_request:\n push:\n branches: [main]\n workflow_dispatch:\n\njobs:\n test:\n runs-on: hf-jobs-cpu-upgrade\n steps:\n - uses: actions/checkout@v4\n - run: echo \"Hello from Hugging Face Jobs\"\nEOF\n\ngit add .github/workflows/hf-jobs-test.yml\ngit commit -m \"Run CI on Hugging Face Jobs\"\ngit push\n```\n\nTo verify from the CLI:\n\n```bash\ngh run list --repo YOUR-GITHUB-ORG/YOUR-REPO --limit 5\nhf jobs ps --namespace \"$HF_NAMESPACE\"\nhf spaces logs \"$SPACE_ID\"\n```\n\nYou should be able to see logs just like a regular GitHub Action—for example, in this [Trackio PR #565](https://github.com/gradio-app/trackio/pull/565).\n\nAnd that's it!\n\n*Note on choosing the right Docker image*\n\nOur first CPU setup used `ubuntu:22.04` and installed missing system packages during every run. That worked, but it was slower than it needed to be. GitHub's `ubuntu-latest` image includes a lot of developer tooling by default; a bare Ubuntu image does not.\n\nFor Trackio, the UI tests need Playwright browsers, Node, ffmpeg, sqlite, git, and normal Linux build dependencies. Hugging Face Jobs supports using any [Docker image](https://huggingface.co/docs/hub/jobs-popular-images), so we switched to the Microsoft Playwright image, which worked well:\n\n```text\nmcr.microsoft.com/playwright:v1.60.0-jammy\n```\n\nFor GPU jobs, we used:\n\n```text\nnvidia/cuda:12.4.0-runtime-ubuntu22.04\n```\n\n## Results\n\nHere are the numbers from the Trackio CI:\n\n| Runner setup | Runtime | Compared to GitHub average |\n| ------------------------------- | ------- | ----------------------------- |\n| GitHub `ubuntu-latest` baseline | `1m40s` | baseline |\n| HF Jobs CPU, Playwright image | `1m10s` | `-30s`, about `30%` faster |\n| HF Jobs GPU, `t4-small` label | `45s` | no GitHub-hosted GPU baseline |\n\nThe biggest win was GPU CI. The Trackio GPU check ran on HF Jobs and passed in `45s`, costing less than a cent at the `t4-small` rate for that duration.\n\nThe CPU result was also encouraging. With the right image, the Linux test job was faster than the GitHub-hosted baseline. That suggests HF Jobs can be a practical CI backend, especially for ML projects that need custom images or accelerators.\n\nLogs were another pleasant surprise. GitHub Actions logs are useful, but the web UI can be heavy for large logs. HF Jobs logs are easy to fetch from the CLI:\n\n```bash\nhf jobs logs > logs.txt\n```\n\nThat makes them easy to inspect with local tools or coding agents. In our bridge, we also mirrored the GitHub Actions job log into the HF Job log, so either system had enough information to debug a run.\n\nFinally, although we didn't need them for Trackio's CI, HF Jobs also [supports mounting volumes](https://huggingface.co/docs/huggingface_hub/en/guides/jobs#mount-a-volume), which can be very helpful if you need to load datasets or models from Hugging Face quickly as part of your CI.\n\nHopefully, this gives you all you need to try HF Jobs for running your GitHub Actions!\n", "dateCreated": "2026-10-19T01:26:53.998049939+00:00", "date_created": "2026-06-09T00:00:00+00:00", "date_modified": "2026-06-09T00:00:00+00:00", "date_published": "2026-06-09T00:00:00+00:00", "description": "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…", "external_url": "https://huggingface.co/blog/github-ci-hf-jobs", "git": { "commit": "ebb0941c5c06a2ab2377342d607535262a3e969e", "path": "items/huggingface-co/2026/06/2026-06-09-migrating-your-github-ci-to-hugging-face-jobs.md", "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/ebb0941c5c06a2ab2377342d607535262a3e969e/items/huggingface-co/2026/06/2026-06-09-migrating-your-github-ci-to-hugging-face-jobs.md" }, "id": "urn:aggr:item:9d4ac813c9f57f29e84a903d0c2eff37b2c23c9f", "isBasedOn": { "@id": "https://huggingface.co/blog/github-ci-hf-jobs" }, "mainEntity": { "@id": "https://huggingface.co/blog/github-ci-hf-jobs", "@type": "CreativeWork", "archivedAt": { "@id": "https://aggr.aymericbeaumet.com/items/huggingface-co/2026-06-09-migrating-your-github-ci-to-hugging-face-jobs/#webpage" }, "dateModified": "2026-06-09T00:00:00+00:00", "datePublished": "2026-06-09T00:00:00+00:00", "headline": "Migrating Your GitHub CI to Hugging Face Jobs", "image": { "@type": "ImageObject", "caption": null, "height": 90, "url": "https://huggingface.co/blog/assets/github-ci-hf-jobs/thumbnail.gif", "width": 160 }, "timeRequired": "PT8M", "url": "https://huggingface.co/blog/github-ci-hf-jobs", "wordCount": 1754 }, "name": "Archived snapshot: Migrating Your GitHub CI to Hugging Face Jobs", "preview": { "alt": null, "color": null, "height": 90, "placeholder": { "data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=", "hash": "" }, "url": "https://huggingface.co/blog/assets/github-ci-hf-jobs/thumbnail.gif", "width": 160 }, "reading_minutes": 8, "replicated_at": null, "source": "huggingface-co", "source_name": "Hugging Face - Blog", "summary": null, "tags": [], "temporalCoverage": "2026-10-19T01:26:53.998049939+00:00", "title": "Migrating Your GitHub CI to Hugging Face Jobs", "url": "https://aggr.aymericbeaumet.com/items/huggingface-co/2026-06-09-migrating-your-github-ci-to-hugging-face-jobs/", "word_count": 1754 }