How to Deploy Machine Learning on GitHub Pages

GitHub Pages can host a useful machine learning demo, but it cannot run Python, Flask, FastAPI, or any other server-side process. The workable pattern is browser inference: convert a trained model into a web-compatible format, publish its files as static assets, and execute predictions on the visitor’s device with JavaScript.

This approach is well suited to student portfolios, research demonstrations, lightweight computer-vision tools, offline-friendly utilities, and early product prototypes. It is not a replacement for a private inference API or a large-model serving stack. Before choosing the architecture, compare the project with machine learning portfolio projects for beginners in India and define a small, measurable user workflow.

What GitHub Pages can—and cannot—do

GitHub Pages serves HTML, CSS, JavaScript, images, and downloadable model files. The user’s browser performs preprocessing and inference using the CPU, WebGL, WebGPU, or WebAssembly.

The deployment flow is:

Train and validate the model in Python.
Convert it to TensorFlow.js or ONNX.
Place the model and weights in the web project.
Load the files from JavaScript.
Convert user input into the exact tensor shape and numerical range expected by the model.
Display the prediction and confidence responsibly.

GitHub Pages cannot protect model weights, run secrets, queue jobs, or guarantee a particular amount of memory. Every public asset should be treated as downloadable. If you need private weights, billing controls, audit logs, or GPU inference, use a backend instead. For comparison, a deployment such as how to deploy deep learning models on GKE is more appropriate for server-managed workloads.

Choose the right browser runtime

TensorFlow.js is a straightforward choice for Keras and TensorFlow models. The converter produces a model.json file plus binary weight shards. It supports browser backends such as WebGL and WebGPU.

ONNX Runtime Web is often the better option for PyTorch, scikit-learn pipelines that support ONNX conversion, and teams seeking a framework-neutral model format. It can use WebAssembly, WebGL, or WebGPU depending on the model and browser.

WebAssembly is useful for portable CPU execution and supporting older hardware, although it may be slower for image-heavy neural networks. Do not select a runtime solely because it is popular: test the complete model, including preprocessing and post-processing, on representative mobile devices.

For a computer-vision project, first review how to build computer vision models on GitHub and establish a reproducible input pipeline. Differences in resizing, colour order, normalisation, or tokenisation are common causes of apparently incorrect browser predictions.

Convert and validate the model

For a Keras model, install the converter and create a web directory:

python -m pip install tensorflowjs
tensorflowjs_converter \
  --input_format=keras \
  model.keras \
  public/models/classifier

Load the result with TensorFlow.js:

import * as tf from '@tensorflow/tfjs';

const model = await tf.loadLayersModel('./models/classifier/model.json');
const input = tf.tensor2d([[1.0, 2.0, 3.0, 4.0]], [1, 4]);
const output = model.predict(input);
const values = await output.data();
output.dispose();
input.dispose();
console.log(values);

For ONNX, export with the framework’s supported opset and inspect the graph’s input and output names:

import * as ort from 'onnxruntime-web';

const session = await ort.InferenceSession.create('./models/model.onnx', {
  executionProviders: ['wasm']
});
const input = new ort.Tensor('float32', Float32Array.from(data), [1, 4]);
const result = await session.run({ input: input });
console.log(result);

Do not rely on a successful export alone. Run a fixed validation set through both Python and the browser runtime, then compare outputs within a defined tolerance. Record the model version, preprocessing rules, class labels, expected tensor shape, and accuracy metrics in the repository.

Structure the GitHub Pages project

A simple repository can look like this:

index.html
src/main.js
src/style.css
public/models/model.onnx
public/labels.json
package.json

Use a build tool such as Vite if you need imports, bundling, or asset hashing. Configure the repository base path correctly: a project site is usually served at https://username.github.io/repository-name/, not at the domain root. Prefer imported assets or a configured base URL over hard-coded /models/... paths.

In GitHub, open Settings → Pages, select the deployment branch or a GitHub Actions workflow, and verify the generated URL. A workflow is preferable when conversion, tests, and deployment should be repeatable. Keep large generated files out of unnecessary build artefacts and document the exact command used to reproduce them.

Reduce download time and memory use

The first visit must download the model, so model size directly affects the experience—especially on mobile networks and lower-cost devices in India.

Apply pruning or quantisation where the runtime supports it.
Prefer a compact architecture such as MobileNet for image demos when accuracy allows.
Split large TensorFlow.js weights into shards.
Load the model only when the user reaches the relevant feature.
Cache the model through normal browser caching or a service worker after validating update behaviour.
Dispose of tensors after each prediction to prevent memory growth.
Display download and inference states instead of leaving the interface blank.

The practical trade-offs are covered in AI model optimization for mobile devices. Test on budget Android phones, throttled 4G, and browsers with limited memory—not only on a developer laptop.

Handle browser and security constraints

Use HTTPS, which GitHub Pages provides for standard sites. Avoid putting API keys, private datasets, or personal information in client-side code. Because inputs stay in the browser, client inference can improve privacy, but your analytics scripts, third-party libraries, and accidental logging can still expose data.

Some ONNX multi-threading configurations require cross-origin isolation through COOP and COEP headers. GitHub Pages does not offer arbitrary response-header configuration. Start with the WebAssembly single-threaded backend; only adopt advanced threading after confirming that your hosting arrangement can provide the required headers. A service-worker workaround may help in some cases, but it adds complexity and should be tested across browsers.

Test the finished demo

A credible deployment needs more than a green GitHub Pages URL. Test:

A clean first visit with an empty cache.
Repeat visits after a model update.
Mobile portrait and landscape layouts.
Unsupported browsers and WebGPU fallback.
Malformed, oversized, or missing inputs.
Predictions near class boundaries.
Accessibility: keyboard use, labels, focus states, and readable error messages.
Model and UI versions that are visible to users.

If the project is intended as a learning artefact, link the source, dataset licence, limitations, and evaluation results. Developers looking for comparable implementation practice can also explore best machine learning projects for computer science students.

When GitHub Pages is the wrong choice

Use a server or managed inference platform when the model is too large for practical browser download, requires confidential weights, depends on Python-only libraries, needs scheduled batch processing, or must deliver consistent latency and hardware. LLM agents and tool-using systems generally need a backend; see how to deploy Llama 3 agents for a different deployment pattern.

For a compact, public, privacy-conscious demo, however, GitHub Pages remains a strong zero-cost option. Treat the repository as a reproducible product: pin dependencies, validate browser outputs against Python, optimise for mobile bandwidth, and explain exactly what runs on the user’s device.

Apply for AI Grants India