Turning a repository into a live website can take a single setting. For designers with a portfolio, product teams with documentation, or anyone with a landing page built by an AI tool, GitHub Pages is often the quickest way to get something online at no cost. The same repository that stores the files can publish them, with no separate hosting account to manage.

GitHub Pages publishes the files in a repository as a website, either directly from a branch or through an automated workflow. Every site gets a github.io address and can use a custom domain instead. Changes go live after each update, usually within minutes. Pages serves static files only, like HTML, CSS, images, and JavaScript that runs in the browser, so apps that need a server or a database have to live somewhere else. A published site is public on the internet, which matters when a repository holds anything private.

Knowing what Pages can host saves time before you start. Static sites fit it perfectly, while anything with logins or stored data needs a different home. For everything else, it's one of the fastest ways to share a working page with the world.

Static sites on GitHub Pages

GitHub Pages is a hosting service that publishes HTML, CSS, and JavaScript files straight from a repository as a website [1]. It's built for static sites: pages made of files that are sent to visitors exactly as they're stored, like a portfolio, a landing page, or project documentation.

There are two kinds of site. A user or organization site lives in a repository named after the account, like sweetcrumbs.github.io, and each account gets one. A project site can be published from any other repository, so one account can run many of them.

Pages is free for public repositories and needs no separate hosting account, which makes it a popular first step from a design file or an AI-built prototype to something anyone can open.

Turning on GitHub Pages

Turning on GitHub Pages

Pages is switched on in a repository's Settings, under Pages. In the Build and deployment section, setting the source to Deploy from a branch, choosing a branch like main and a folder, either the root or /docs, and selecting Save publishes the site [2].

The chosen folder needs a homepage at its top level: a file named index.html, index.md, or README.md[3]. Without one, the site has nothing to show at its main address.

The first publish takes a few minutes. When it's done, the same settings page shows the site's address and a Visit site button.

Publishing from a branch or a workflow

Pages offers two publishing sources. Deploy from a branch publishes the files stored in one branch, from its root or a /docs folder. GitHub Actions runs a workflow that builds the site first and then publishes the result [4].

Branch publishing suits sites that are already finished files, like hand-written HTML or an export from a design or AI tool. Workflows suit sites that need a build step, like those made with a framework that turns source files into finished pages.

Either way, a change to the repository is what updates the live site. Committing to the publishing branch, or running the workflow, sends the new version out.

Finding the site's address

Finding the site's address

Every Pages site gets a github.io address. A project site lives at an address like https://sweetcrumbs.github.io/bakery-website/, combining the account name and the repository name, while a user site uses just https://sweetcrumbs.github.io[5].

The Pages settings show the current address under a message that the site is live, with a Visit site button next to it.

Because a project site sits in a subfolder of the address, links inside it need care. A link to /menu.html points to the account's root, not to the project, so it breaks. A relative link like menu.html stays inside the project and works wherever the site lives.

Using a custom domain

A Pages site can use a custom domain, like sweetcrumbs.com or www.sweetcrumbs.com, instead of its github.io address. The domain is entered under Custom domain in the Pages settings, and a DNS record at the domain provider points it to GitHub [6].

Subdomains like www use a CNAME record, while a bare domain uses an A, ALIAS, or ANAME record. DNS changes can take up to 24 hours to spread, so a new domain may not work right away. Once it does, Enforce HTTPS makes sure visitors always get a secure connection.

GitHub recommends verifying the domain in account settings first, which stops anyone else from pointing it at their own Pages site.

Who can see a Pages site

A GitHub Pages site is public on the internet, even when its repository is private [7]. On free plans, Pages needs a public repository anyway. On paid plans, the repository can stay private, but anyone with the address can still open the published site.

That's easy to forget when a prototype is published from a private repository. Draft pricing, internal notes, or test data in the published folder are visible to anyone who finds the link.

Only organizations on GitHub Enterprise Cloud can limit a Pages site to people with access to its repository. For everyone else, the rule is simple: publish only what's fine for the whole internet to see.

When changes go live

A Pages site updates after each change to its publishing source, but not instantly. It can take up to 10 minutes for a change to appear after it reaches GitHub [8].

When a site still hasn't changed after that, the repository's Actions tab is the first place to check. Publishing runs there in the background, and a failed run explains what went wrong, which is far more useful than assuming the change was lost.

Browsers also keep old copies of pages. A hard refresh, or opening the site in a private window, confirms whether the live site has really changed.

Pro Tip! Publishing many small changes in a row can hit Pages' soft limit of 10 builds per hour, so grouping edits helps on busy days.

What GitHub Pages can't run

Pages serves files exactly as they're stored. It doesn't run server-side languages such as PHP, Ruby, or Python, and it has no database [9]. Anything that needs to remember users, process orders, or store data has to rely on another service.

This matters for AI-built apps. Many builders generate projects with logins, a backend, or a database, and publishing such a repository to Pages produces a page that loads but doesn't work. Those projects need a host that runs servers.

GitHub's limits also rule out using Pages to run an online business or for sensitive transactions like passwords or card payments [10]. Within those limits, it's a fast, free home for portfolios, documentation, and landing pages.