GitHub Pages for Websites: When Free Hosting Becomes Extra Work

A site can be live on GitHub Pages, look finished and still fail its first useful test: someone opens a link to an inner page, refreshes it and gets a 404.

Or the pages work, but the enquiry form cannot send anything. Or a small content edit fails to publish because a configuration file has invalid indentation. These are less exciting than a free-hosting headline, but they are the questions that decide whether the setup is sensible.

Our verdict: GitHub Pages is a reasonable home for a developer's portfolio, project documentation or a modest public information site with a capable maintainer. We would not choose it by default for an organisation's main website when non-technical staff need to edit content, enquiries matter to the business, or the site requires logins and transactions. The team proposing it should demonstrate how those needs will be handled.

Updated 5 November 2026. This review draws on developer discussions, including Reddit, practical tutorials and accounts of moving away from Pages. Those reports informed the questions and test scenarios below; they are not a measure of failure rates. Technical restrictions were checked against official documentation.

Table of contents

1. The useful part of the bargain
2. A working page is not a working website
3. The URL works until someone refreshes it
4. A small edit can become a publishing problem
5. Previewing changes is another job to solve
6. Domain and SEO work do not disappear
7. The limits that can rule it out
8. Where we would use it, and where we would not
9. Frequently asked questions

The useful part of the bargain

Pages publishes static files. It does not run a PHP application for each visitor, and GitHub explicitly excludes server-side languages such as PHP, Ruby and Python from the serving environment. A build tool can generate the pages beforehand; that does not turn the hosting into an application server. [1]

For content that suits this model, the simplicity is valuable. You can keep the source and change history together, avoid maintaining a public database just to display text, and move the generated files elsewhere if the project changes. There is no reason to build a complicated backend for a small documentation site.

The catch is that this works best when the people maintaining the site are comfortable with its tools. A developer calling something easy may mean that they know how to fix it. That is a different promise from saying an office manager can operate it without help.

A working page is not a working website

Contact forms expose the gap quickly. A form can have all the right fields, validation messages and styling while its Send button posts to an address that cannot process the submission. Public support discussions include exactly this situation: a finished-looking static page followed by a 405 response when the owner tests the form.

The underlying constraint is straightforward. Receiving a message, checking spam, storing it and sending an email require a processing service. Those jobs do not happen merely because HTML for the form exists. Pages' static runtime explains the limitation. [1]

A separate form endpoint can be a perfectly reasonable solution. It also introduces another account, another failure point and another place where personal data may be stored. Someone must understand its limits, own the subscription and notice when delivery stops.

What we would require: send a real test enquiry, confirm its destination, simulate a rejected submission and check the visitor's error message. Record who investigates missing messages. A success animation is not evidence of delivery.

The same reasoning applies to bookings, customer accounts and private documents. You can connect a static front end to other systems, but you are now operating those systems too. If they are central to the business, plan the web application before choosing where its public pages live.

The URL works until someone refreshes it

Two different problems are often mixed together here.

Client-side navigation hides a missing route

A JavaScript application may switch from the homepage to /services/design without asking the server for a new document. That can look correct during a quick demonstration. Opening the same address in a new tab makes the server handle it directly. If the build has not produced a matching page and the host has no appropriate routing arrangement, the result can be a 404.

This is a concrete complaint in the React and Svelte discussions we reviewed. It is not proof that either framework is unsuitable. It means the app's routing assumptions and the deployment need to agree.

Generating real pages for public routes, choosing suitable hash-based navigation, or using hosting with the required routing controls are different solutions with different compromises. A custom 404 page that starts the app may make the screen look right while leaving an error status behind. Google treats HTTP error responses differently from successful pages, so inspect the response as well as the rendered result. [2]

A custom domain changes the asset paths

There is a separate trap when moving from username.github.io/project/ to example.com/. The HTML may load while scripts and styles still point into the old project directory. The symptom is a blank or unstyled page, despite a successful deployment.

Vite's own guide distinguishes these cases: a repository project URL needs the repository path as its base; a domain-root deployment uses /. That is a build setting, not something DNS will repair. [3]

What we would require: open several deep links directly, refresh them, inspect failed asset requests and test the final domain. Testing only the homepage on the temporary address is not enough.

A small edit can become a publishing problem

One of the more revealing discussion threads ends with a very ordinary fix: a YAML list item had the wrong indentation. The important lesson is not that GitHub broke the site. It is that changing a contact setting required understanding a build error.

That distinction matters. Invalid configuration, incompatible theme updates and dependency changes are not all platform outages. But from the owner's perspective, the outcome can still be that an urgent correction is stuck until a developer is available.

GitHub documents build failures caused by configuration syntax, invalid dates, missing includes and unsupported plugins. Replacing the application server with a build pipeline changes the maintenance work; it does not eliminate it. [4]

We would expect a reproducible build, recorded tool versions, dependency lockfiles where applicable, a check before publication and someone responsible for reviewing failures. Keep a known-good deployable version as well as the editable source. An old commit is less useful if nobody can rebuild it with the required tools.

For a team updating pages regularly, the decisive test is an ordinary edit performed by the actual editor. Have them replace an image and correct a paragraph. If the answer is always to ask the developer, include that dependency in the cost comparison. A WordPress editing workflow or another managed CMS may be a better operational fit.

Previewing changes is another job to solve

Being able to review a code change is not the same as having a shareable preview of the finished website. A manager may need to check a draft on a phone, send the link to a colleague and approve it before the public pages change.

Developer accounts describe solving this with additional deployments or preview folders. Those approaches can work. They also need decisions about cleanup, asset paths, analytics and whether unfinished content becomes publicly reachable.

Our requirement would be a demonstrated approval workflow. Show where the preview lives, who can access it, how it is kept out of the production navigation and what happens when the proposed change is abandoned. A difficult-to-guess URL is not access control.

GitHub also distinguishes a private source repository from a private Pages website. Restricted publication is an eligible Enterprise Cloud project-site feature, not an automatic consequence of hiding the repository. [5]

If confidential previews are a routine requirement, compare platforms that provide the required workflow directly. A custom workaround should have a clear benefit over the additional work it creates.

Domain and SEO work do not disappear

The domain complaints we reviewed are a useful warning against treating a green DNS check as a complete launch test. Some involved conflicting records; others were unresolved or apparently affected by caching. Those reports do not establish a mysterious GitHub defect in every case.

There is also a documented publishing trap. With branch-based publication, a build or force push can overwrite the CNAME file. With a custom Actions publishing workflow, GitHub says that file is ignored and is not required. Applying the same fix to both setups can waste time. [6]

Check the actual deployment method, DNS records and Pages settings together. Assign ownership of the domain and account to the organisation, and record what must change when the site moves away.

For an existing site, URL changes deserve their own plan. A script that sends a browser somewhere else is not an HTTP 301 response. Google recommends permanent server-side redirects where possible and treats JavaScript redirection as a fallback. Do not accept a migration solely because the final screen looks correct. [7]

Ask to see several old URLs tested against the proposed solution, including status codes and destinations. If redirects, response headers or other routing requirements need another service in front of Pages, include that layer in the architecture and maintenance estimate. Our web development planning covers those requirements before the host is chosen.

The limits that can rule it out

There is no point engineering around technical issues before checking permitted use. GitHub restricts using Pages as free hosting for operating an online business, ecommerce or sites primarily facilitating commercial transactions or commercial SaaS. It also warns against sensitive transactions involving passwords and card details. Read the actual rule rather than treating a confident forum answer as permission. [8]

The published site is limited to 1 GB, bandwidth has a soft limit of 100 GB per month and deployments time out after ten minutes. There is also a soft limit of ten builds per hour, with an exception for custom Actions publishing workflows. Media-heavy sites and frequent publishing need a realistic estimate. [8]

Cost comparisons should be accurate too. GitHub's billing documentation lists standard hosted runners for Pages as free. Other automation and storage rules can differ. The stronger criticism is the work around the hosting: content support, form processing, previews, monitoring and recovery. Those are project costs, not an invented mandatory Pages build fee. [9]

If saving a hosting subscription creates an ongoing need for developer assistance, compare the complete operating cost. Free can still be good value. It just needs to survive that comparison.

Where we would use it, and where we would not

The test is whether the team can operate the system after the initial developer leaves. Who can publish a correction? Who gets the failure alert? Who owns the form account? Can a replacement developer reproduce the build?

For a developer-owned site, these answers may be easy. For an organisation that needs to get on with its work, they may justify a different platform. Agree the maintenance responsibilities and security boundaries before calling the project finished.

You can keep the code on GitHub while hosting the website elsewhere. Choosing another host does not require abandoning version control or rebuilding everything as WordPress. The right decision is the one that meets the editing, functionality and support requirements with an acceptable amount of extra machinery.

Frequently asked questions

Is GitHub Pages unreliable?

The discussions reviewed do not establish a failure rate or justify that blanket conclusion. They show practical problems to investigate. Separate hosting incidents from configuration mistakes, build failures and features the platform does not provide.

Can GitHub Pages run a contact form?

It can display the form, but receiving and processing submissions needs an external endpoint or backend. Confirm delivery, spam handling and error behaviour before launch. Pages does not provide a general server-side runtime. [1]

Why does the homepage work but an inner page return 404?

Check whether the requested route exists in the deployed output and whether the app depends on client-side routing. Also check the build's base path, especially after changing domains. A successful build does not prove that every URL works. [3]

Does moving to another host mean leaving GitHub?

No. Source storage, the build process and public hosting are separate choices. Keep the build reproducible and document its inputs so the publishing destination can change.

Technical references

The review is informed by public developer discussions and practical migration and deployment accounts. These are individual experiences, not controlled reliability tests. The following official references support the platform facts and technical checks; the recommendations are our editorial assessment.

1. GitHub: publishing static files and the server-side runtime limitation
2. Google: how HTTP status codes affect crawling
3. Vite: deployment base paths for GitHub Pages and custom domains
4. GitHub: configuration, content and dependency-related build failures
5. GitHub: private publication and access-control requirements
6. GitHub: custom domains, CNAME behaviour and publishing methods
7. Google: server-side redirects, meta refresh and JavaScript redirects
8. GitHub: permitted use and operating limits
9. GitHub: Actions billing and the Pages runner exception