Apply for AI Grants India

GitHub Pages is useful for publishing a machine learning demo, portfolio project, or documentation site—but it is static hosting. It serves HTML, CSS, JavaScript, images, and downloadable assets; it does not run Flask, FastAPI, PyTorch, or scikit-learn code on the server.

That distinction determines the right deployment design. You can run a suitably converted model in the browser, or host the frontend on GitHub Pages and connect it to an external inference API. This guide explains both approaches, with practical deployment steps and checks relevant to Indian builders, students, researchers, and startups.

Choose the right deployment architecture

Start by deciding where inference will happen:

• Browser inference: Convert the model to TensorFlow.js, ONNX Runtime Web, or another browser-compatible format. GitHub Pages hosts the application and model files, while the user’s device performs prediction.
• External API: Keep the model in Python or another server environment and call it from JavaScript. GitHub Pages hosts only the user interface.
• Static showcase: Publish screenshots, sample predictions, metrics, and a reproducible notebook when the model is too large or sensitive to run publicly.

Browser inference is attractive for privacy, low operating cost, and simple hosting. It works well for compact image, text, and tabular models. An API is usually better for large models, GPU workloads, proprietary weights, retrieval pipelines, authentication, or centralised monitoring.

If you are building a portfolio, first define the project clearly using ideas from machine learning portfolio projects for beginners in India. A deployed demo should show the problem, dataset, evaluation method, limitations, and a working interaction—not just a prediction button.

Prerequisites

You will need:

• A GitHub account and repository
• Git installed locally, or permission to edit the repository in the browser
• A frontend built with HTML, CSS, and JavaScript, or a static-site framework
• A model converted for browser use, or a publicly reachable HTTPS inference endpoint
• Sample inputs and expected outputs for testing
• Basic familiarity with browser developer tools and GitHub Actions

Do not commit API keys, private datasets, credentials, or unrestricted access tokens. Store secrets in the backend platform’s secret manager, not in frontend JavaScript. Anything shipped to a GitHub Pages site can be inspected and downloaded by visitors.

Option 1: Run the model in the browser

This is the simplest genuinely serverless approach.

Convert and test the model

Choose a format supported by your target runtime. TensorFlow models can often be converted for TensorFlow.js; many PyTorch and scikit-learn workflows can be exported to ONNX and run with ONNX Runtime Web. Conversion may change supported operators, numerical precision, preprocessing, or output names, so compare browser predictions with the original Python implementation.

For a useful demo, document:

• Training data and licence
• Input shape, units, and preprocessing
• Model size and expected loading time
• Accuracy, F1 score, latency, or other relevant metrics
• Known failure cases and responsible-use limits

A computer-vision project may also benefit from the workflow in how to build computer vision models on GitHub, especially when you need reproducible assets and clear repository structure.

Build the frontend

A minimal page can load the model, collect input, run inference, and render a result:

<form id="predict-form">
  <input id="value" type="number" step="any" required>
  <button type="submit">Predict</button>
</form>
<p id="status" aria-live="polite">Loading model…</p>
<p id="result"></p>
<script type="module" src="./app.js"></script>

In app.js, load the model once, disable the submit button until loading completes, validate inputs, and catch failures. Show units and confidence carefully; a confidence score is not automatically a probability of correctness. Use relative paths such as ./model/model.json because repository sites are commonly served under /repository-name/, not at the domain root.

Large model files can make first load frustrating. Quantisation, pruning, compression, lazy loading, and smaller input sizes can help. Test on a mid-range mobile connection, not only on a development laptop.

Option 2: Host the model behind an API

Use this design when the model needs Python dependencies, a GPU, private weights, database access, or server-side controls. Deploy the backend to a platform that runs containers, serverless functions, or managed inference. Enable HTTPS and configure CORS for the exact GitHub Pages origin.

The browser request might look like this:

const response = await fetch("https://api.example.com/predict", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ value: Number(input.value) })
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const prediction = await response.json();
result.textContent = prediction.label;

The API should validate payloads, limit request size and rate, return predictable error formats, and avoid logging personal data by default. Add authentication where needed. If your system involves multiple tools or long-running reasoning, treat it as an application backend rather than forcing it into GitHub Pages; deployment patterns in how to build a voice agent illustrate why latency, state, and service boundaries matter.

Deploy the static frontend with GitHub Actions

Create a repository with a structure such as:

project/
├── index.html
├── app.js
├── styles.css
├── model/
└── README.md

Commit the files and push them to the default branch:

git add .
git commit -m "Add ML demo"
git push origin main

In Settings → Pages, select GitHub Actions as the build and deployment source. For a plain static site, GitHub’s static HTML workflow is usually sufficient. If you use a framework, configure its build command and publish directory, then verify that the workflow has permission to deploy Pages.

After deployment, open the generated URL and test the production path. Check browser console errors, network requests, model asset paths, API responses, mobile layout, and direct navigation to any subpage. Repository sites often expose mistakes in absolute paths, case-sensitive filenames, and client-side routing.

Test before sharing

Use a small acceptance checklist:

• The page loads over HTTPS without mixed-content warnings.
• The model or API fails gracefully when offline.
• Invalid, empty, oversized, and unusual inputs are handled.
• Predictions match a known test set within an agreed tolerance.
• No secrets or private files appear in the repository or browser bundle.
• The README explains setup, model licence, dataset source, metrics, and limitations.
• The demo works on a mobile device and a slower network.
• Accessibility basics—labels, keyboard navigation, focus states, and status messages—are present.

For an educational project, link the demo to the source code and explain how another learner can reproduce it. Open-source contribution practices covered in how to contribute to AI GitHub repositories in India can help turn a one-off showcase into a maintainable project.

Common failures and fixes

• 404 for model files: Use relative paths, check filename capitalisation, and confirm the files exist in the deployed branch.
• CORS errors: Configure the backend for the exact Pages origin and send the required preflight headers.
• Blank page after framework deployment: Set the correct base path for the repository name and inspect the Actions build log.
• Slow or failed loading: Reduce model size, split assets, or move inference to an API.
• Incorrect predictions: Reproduce preprocessing exactly, including tokenisation, scaling, colour channels, and label mapping.
• Exposed credentials: Revoke the key immediately, remove it from Git history where appropriate, and move authentication to a backend.

When GitHub Pages is not enough

GitHub Pages is excellent for a frontend, documentation, and lightweight browser inference. It is not a substitute for a production inference service, private model registry, GPU runtime, queue, database, observability stack, or access-control layer. For production AI systems, separate the public interface from the service that owns model execution and data governance.

For most student and early-stage projects, the strongest setup is a fast static demo, a transparent README, a small evaluation set, and an honest explanation of limitations. That combination is more credible than claiming production readiness because a page is online.