Skip to content

Contact form on GitHub Pages ​

In short: GitHub Pages only serves files, so nothing on it can receive a form. Point your form's action at a form backend instead, which stores each message and emails it to you. With BootForm that's one HTML form and no account to start: it works on a plain HTML site, a Jekyll site and a site built with GitHub Actions alike. The free plan takes 250 submissions a month.

Why GitHub Pages can't receive a form ​

GitHub Pages hosts static files: HTML, CSS, JavaScript and images. No code of yours runs on its servers, so there's no PHP, no serverless function and nothing to handle the POST when a visitor presses Send. The form has to send its data somewhere else.

That somewhere is a form backend. The form stays plain HTML in your repo; only its action points at the backend's address.

The form ​

This works on any GitHub Pages site, whatever builds it:

html
<form action="https://f.bootform.com/{form_id}" method="POST">
  <label for="name">Name</label>
  <input id="name" name="name" required>

  <label for="email">Your email</label>
  <input id="email" name="email" type="email" required>

  <label for="message">Message</label>
  <textarea id="message" name="message" required></textarea>

  <input type="text" name="honeypot" style="position:absolute;left:-9999px" tabindex="-1" autocomplete="off">

  <button type="submit">Send</button>
</form>
  1. Replace {form_id} with a UUID you generate yourself. The UUID generator gives you one. Never copy an ID from an example page, since whoever claims an ID first receives what is sent to it.
  2. Commit and push. Once Pages has published the change, send yourself a test message.
  3. Claim the form within two days of that first test. Messages are held until you do, and from then on each one is emailed to you.

The honeypot field is a spam trap: visitors never see it, bots fill it in. Keep it positioned off screen as shown, not hidden with hidden or display:none. See Spam protection.

A thank-you page on a project site ​

After a successful send, BootForm shows the visitor a short "Thanks" page. To send them to a page of your own, add a hidden _redirect field with the full URL of that page:

html
<input type="hidden" name="_redirect" value="https://yourname.github.io/your-repo-name/thanks/">

A project site (anything except yourname.github.io itself) lives under the repository's name, so a path like /thanks/ on its own points at the wrong place and the visitor lands on a 404, even though the message arrived. On a custom domain, use that domain instead: https://www.example.com/thanks/. The redirect has to be on the same site as the form, or on one of the form's allowed origins; any other URL is ignored.

To stay on the page and show a message in place instead, submit with JavaScript: see Vanilla JS, AJAX submission. Leave _redirect out in that case.

Jekyll sites ​

GitHub Pages builds Jekyll sites itself, and the form above works in any page or include. The Jekyll guide shows how to keep the form ID in _config.yml, reuse the form with an include, and build the thank-you URL with absolute_url so baseurl is always right. None of it needs a plugin.

Sites built with GitHub Actions ​

Hugo, Astro, Eleventy, VitePress and other generators publish to Pages through a workflow. The form is the same HTML, placed in your layout or a component. There are guides for Astro, Hugo, Eleventy, Next.js, React, Vue and Angular, each with the thank-you URL built for a project site. The contact form recipes repository has copy-paste versions for Astro, Hugo, Jekyll, Eleventy, Svelte and VitePress.

Only accept posts from your site ​

Anyone who reads your page's HTML can see the form's address. Once the form is claimed, you can limit it to your own site in the dashboard: add https://yourname.github.io under allowed origins. On a custom domain, add that origin too, for example https://www.example.com. Each origin is matched exactly, so list every one the site is served from.

What doesn't work on GitHub Pages ​

  • Netlify Forms only works on sites hosted on Netlify.
  • PHP's mail() and other server scripts need a server; Pages runs none.
  • Serverless functions aren't available on Pages.
  • A mailto: link isn't a form. It opens the visitor's own mail app, if they have one set up, and puts your address in the page for spammers to collect.

For the other form backends and how their free plans compare, see every option compared.

Let an AI agent set it up ​

If you build the site with Claude Code, Cursor or another agent, connect BootForm's MCP server and ask it to add a contact form. It creates the form, puts the snippet in your page and sets up where the messages go.

Common problems ​

After sending, the visitor lands on a 404. The _redirect URL is missing the repository name of a project site, or still points at github.io after you moved to a custom domain. Open the published page's source and check the field's value.

You sent a test message but no email arrived. The form isn't claimed yet. Nothing is delivered until it is; claim it and the messages sent so far are delivered. Held messages are kept for 48 hours.

Submissions fail with 403 ORIGIN_NOT_ALLOWED. The form has allowed origins set, and the site's address isn't one of them. Add the exact origin the page is served from, including a custom domain.

The form doesn't change after you push. Pages can take a few minutes to publish. Check the Actions tab for the deployment, then reload without the cache.