Adding an AI chatbot to a GitHub Pages site

GitHub Pages serves static files, so a chatbot can’t run on it by itself. Most results for “github pages chatbot” are repositories for building your own, and each of those relies on a server somewhere else to run the AI. The shorter route is a hosted chatbot that goes into your pages as one script tag. We read GitHub’s documentation and the prices below on 23 September 2026.

Deacon is an AI customer support agent you add to a GitHub Pages site with one script tag in your layout, and nothing to host. It answers visitors in seconds from your published docs and pages, and shows you what they ask about most. The free plan gives you 50 answers a month, needs no card and has no end date.

Why a chatbot on GitHub Pages needs a service behind it

GitHub calls Pages a static site hosting service that takes HTML, CSS and JavaScript straight from a repository. Nothing runs on the server when a visitor asks a question, so the AI behind a chatbot has to live somewhere else.

Putting an AI provider’s key in your page’s JavaScript doesn’t get round that, because every visitor can read it. The repository doesn’t hide it either. GitHub’s guide to creating a site points out that a Pages site is public on the internet even when its repository is private.

Three ways to add a chatbot, and what each costs

Here are the three routes a site owner has, with prices read on 23 September 2026.

Biel.ai’s free access is for non-commercial projects under an OSI-approved licence, such as MIT or Apache 2.0, which it checks when you apply. Its trial covers one project, 500 indexed pages and 2,000 interactions a month for 14 days.

Where the script tag goes on a GitHub Pages site

It depends on how GitHub builds your site. You can see which under your repository’s Settings › Pages, in the Build and deployment section, where the source is either a branch or GitHub Actions. After you push, a change can take up to 10 minutes to appear.

A Jekyll site published from a branch

When you publish from a branch, GitHub builds the site with Jekyll unless the branch has a .nojekyll file. Jekyll wraps each page in a layout, and your theme brings its own, so you take over the theme’s layout in your repository. GitHub’s guide to themes gives the steps.

1. Open your theme’s source repository, such as pages-themes/minimal for the Minimal theme, and copy its _layouts/default.html.
2. In the folder your site publishes from, the repository’s root or its /docs folder, create _layouts/default.html with that content.
3. Paste the tag on the line above </body>.
4. Commit to the branch your site publishes from.

Jekyll uses your copy instead of the theme’s, because it looks in your site’s own folders first. A page Jekyll doesn’t process won’t get the tag, though. Jekyll only processes an HTML file that starts with front matter, so one without it goes out as it is. Add the tag to those by hand.

Plain HTML

If your site is hand-written HTML with no generator, each page is published as it is. Paste the tag above </body> in every page you want the chat on.

A site built by a GitHub Actions workflow

Sites built with Hugo, MkDocs, Docusaurus, Astro or another generator publish either through a GitHub Actions workflow or by pushing the built site to a branch such as gh-pages, as mkdocs gh-deploy and docusaurus deploy do, so Settings › Pages may show a branch. Either way, the tag goes in the base layout or template your generator wraps every page in, in your source files, and it goes live the next time you build and deploy.

What survives a change of theme

Your copy of _layouts/default.html stays in your repository when you switch themes, so the new theme’s pages are still wrapped in the old theme’s layout. Copy the new theme’s _layouts/default.html over yours and paste the tag in again. On other generators, a new theme usually brings a new base layout, so check the tag is still in it.

What Deacon does on a GitHub Pages site

A project’s docs answer most of what people ask, yet the same questions keep arriving as GitHub issues and emails. Deacon answers them where people read, in seconds and in the visitor’s language, from your published docs, often with a link to the page it used. If your docs keep translated copies in top-level folders such as /fr/ or /de/ on your user site or custom domain, a crawl of your whole site on a paid plan skips them when your pages name them in hreflang tags. Without the tags it keeps them and points out the ones that look like translations. Either way, Deacon replies in each visitor’s own language. On a project site, where every path starts with the repository’s name, leave those copies unticked once the crawl ends.

When the docs don’t cover something, Deacon doesn’t improvise an answer. It says it doesn’t know and asks for the visitor’s email. You get an email when they leave one or ask for a person, and your reply from the dashboard shows up in their chat while it’s open.

Each gap then makes Deacon better. A question your docs didn’t cover sits in your dashboard with an Answer this button. Write the answer and press Save & check, and Deacon asks itself the question again to show you its new reply, and, when it now answers, how many other open questions your answer covers too. The answer becomes a source Deacon answers from, so it can answer the next visitor who asks, and it needs you less each time.

It also shows you what people want from the project. Every conversation is saved and searchable by what the visitor asked. Topics groups similar questions, counts how many people asked and labels most groups as a bug report, a feature ask, a how-to and so on, so you know what to fix and what to build next. The same script counts your site’s visitors, where they came from and the goals they reach.

The key in Deacon’s snippet is meant to be public, so it’s fine in a public repository, and the widget only appears on the domains you list. There’s no AI provider key to hide and no backend to host. Every feature is on every plan, the free one included, nothing is billed past your plan’s answers and no plan upgrades itself. The pricing page has the paid plans.

Adding Deacon to your GitHub Pages site

Deacon’s snippet looks like this, with your own key in place of the placeholder.

<script src="https://heydeacon.com/widget/v1/loader.js" data-key="pk_your_widget_key" async></script>

It takes a few minutes, most of them waiting for GitHub to publish.

1. Sign up with your email or Google, and give Deacon your site’s address, such as owner.github.io, your custom domain or a project’s owner.github.io/repository. The free plan needs no card. Deacon reads that page and up to four pages it links to that visitors ask about first, such as your docs or FAQ.
2. On the Install page, check your site’s address is listed, and add it if it isn’t. The website you gave when you signed up is already there, with your snippet ready. owner.github.io covers your user site and every project site under it, because they share one address. Add your custom domain if you use one, and Deacon treats its www and non-www forms as one site.
3. Add the snippet to your layout as above, or press Copy the prompt on Deacon’s Install page and paste it into Claude Code, Cursor or Codex. The agent reads Deacon’s install guide, adds the tag in your repository and checks it’s live.
4. Push, and wait for the Pages build to finish.
5. Once Deacon has read your pages, untick any in Knowledge Sources you’d rather it didn’t use, such as one from another project under the same owner.github.io address. Add other pages one at a time by their address.
6. Ask it the questions your issues keep getting, in the Playground, before anyone else sees it.

What to check after you push

These take a couple of minutes once the build is done.

1. Check the latest Pages run finished, under your repository’s Actions tab.
2. Open your site in a private window and look for the chat button, since your browser may still hold the old page.
3. Look at the top of Deacon’s Install page. It says whether Deacon is live on your site and when it was last seen, and it keeps checking by itself.
4. Ask one question your docs answer and one they don’t. The first should get an answer, often with a link, and the second an honest “I don’t know” with a box for an email address.
5. Open a page that doesn’t use your layout, if you have one, and add the tag to it if the button is missing.

Questions about chatbots on GitHub Pages

Is there a free chatbot for GitHub Pages?

A few, with conditions. Biel.ai is free for qualifying non-commercial open-source projects, and building your own costs what your host and AI provider charge. Deacon’s free plan gives any site 50 answers a month, with no card and no end date.

Can I build a chatbot that runs on GitHub Pages alone?

Not practically. Pages runs no code on the server, so a chatbot built only from your pages has to call an AI provider from the visitor’s browser with your key in the page, where anyone can read it and run up your bill, or download a whole model into each visitor’s browser.

Does one Deacon domain cover all my project sites?

Yes, if they’re on github.io. Project sites live at owner.github.io/repository, the same address as your user site, so one entry covers them all. With a custom domain on your user site, GitHub serves project sites without their own domain under that domain, and that one entry covers them too.

Can Deacon read my repository or README?

Not from GitHub itself. Deacon reads your published site, files you upload and answers you write. To teach it your README or other docs that aren’t on the site, upload them as Markdown files, up to 10 MB each, and they start answering as soon as they’ve been read.

Does Deacon work on a privately published site?

The widget does, once you add the site’s own pages.github.io address on the Install page. GitHub Enterprise Cloud can publish a project site that only people with read access can open, and Deacon’s crawl can’t sign in to it, so teach Deacon with uploaded files or pasted text instead.

Can my startup’s website live on GitHub Pages?

Check GitHub’s rules first. Its limits page says Pages isn’t for running an online business, a shop or commercial software as a service, and caps a published site at 1 GB with a soft limit of 100 GB of bandwidth a month.

What happens when Deacon’s free answers run out?

Visitors get a short, fixed reply saying Deacon can’t look into it right now, with a request for their email unless they’ve already left it in that chat. You can still read and answer every conversation. Nothing is billed past your plan, and it never upgrades itself.