GitHub Pages turns your repository into a free live website. The full workflow is: create a repository, add your HTML/CSS/JavaScript files, go to Settings → Pages, select the main branch, and click Save. Within minutes your site is live at yourusername.github.io/repo-name. You can also connect a custom domain for a professional URL.
The Complete GitHub Pages Publishing Workflow
GitHub Pages is GitHub's built-in static site hosting service. It reads HTML, CSS, and JavaScript files from a repository and serves them as a website — completely free for public repositories.
Before diving into steps, here is how the full workflow works:
1. **Repository = your website's home.** All your site files live in a GitHub repository. The repository name becomes part of your URL. 2. **index.html = your front door.** GitHub Pages looks for a file named index.html at the root of your selected branch. This is the first page visitors see. 3. **Enable Pages = flip the switch.** In repository Settings, you tell GitHub which branch to deploy from. GitHub builds and publishes automatically. 4. **Every commit = automatic update.** When you edit files and commit changes, GitHub rebuilds your site within 1-3 minutes. 5. **Custom domain (optional).** You can replace the default github.io URL with your own domain like mysite.com.
This workflow is ideal for portfolios, landing pages, documentation sites, and static exports from AI builders like Lovable or V0. If your project has a backend (database, API, server-side logic), you will need a full hosting platform like Vercel or Railway instead.
Prerequisites
- A GitHub account (free tier works for public repositories)
- HTML files for your website (even a single index.html is enough to start)
- A custom domain (optional, for replacing the default github.io URL)
Step-by-step guide
Create a repository for your website
Create a repository for your website
Go to **github.com** and sign in. Click the **+** icon in the top-right corner and select **New repository**. Give it a descriptive name — this name becomes part of your URL (e.g., `my-portfolio` becomes `yourusername.github.io/my-portfolio`). Set the visibility to **Public** (required for free accounts). Check the box for **Add a README file** and click the green **Create repository** button. Special case: if you name the repository `yourusername.github.io` (replacing 'yourusername' with your actual GitHub username), it becomes your personal site at that exact URL without a subpath.
Expected result: A new public repository is created with a README.md file.
Add your website files to the repository
Add your website files to the repository
On the repository page, click the **Add file** dropdown and select **Upload files**. Drag and drop your website files (index.html, style.css, any JavaScript files, images) into the upload area. Make sure index.html is at the top level — not inside a subfolder. Alternatively, if you are starting from scratch, click **Add file → Create new file**, name it `index.html`, and type or paste your HTML code in the editor. Add a commit message like 'Add website files' and click **Commit changes**.
Expected result: Your repository now contains index.html and any other website files at the root level.
Enable GitHub Pages in repository settings
Enable GitHub Pages in repository settings
Click the **Settings** tab at the top of your repository. In the left sidebar, scroll down to **Code and automation** and click **Pages**. Under **Build and deployment**, make sure Source is set to **Deploy from a branch**. Click the **Branch** dropdown and select **main**. Leave the folder as **/ (root)**. Click **Save**. GitHub begins building your site immediately. A notification appears confirming the source was saved.
Expected result: GitHub Pages is enabled and a build is triggered. The Pages settings page shows a pending or successful deployment.
Access your live website
Access your live website
Wait 1-3 minutes, then refresh the Pages settings page. A green banner appears at the top with a link: **Your site is live at https://yourusername.github.io/repository-name**. Click the link or the **Visit site** button to see your website live on the internet. Share this URL with anyone — it is publicly accessible. Every time you update files in the repository, the site automatically rebuilds.
Expected result: Your website is live and accessible at the github.io URL shown in the green banner.
Connect a custom domain (optional)
Connect a custom domain (optional)
If you own a domain (like mysite.com), you can point it to your GitHub Pages site. On the Pages settings page, scroll down to **Custom domain**. Type your domain name (e.g., `www.mysite.com`) and click **Save**. Next, go to your domain registrar (the service where you bought the domain — GoDaddy, Namecheap, Cloudflare, etc.) and add a **CNAME record**: - **Name/Host**: www - **Value/Points to**: yourusername.github.io For an apex domain (mysite.com without www), add four **A records** pointing to GitHub's IP addresses: - 185.199.108.153 - 185.199.109.153 - 185.199.110.153 - 185.199.111.153 DNS changes take 15 minutes to 24 hours to propagate. Once active, check the **Enforce HTTPS** checkbox on the Pages settings page for a free SSL certificate.
Expected result: Your custom domain serves your GitHub Pages site with HTTPS enabled.
Troubleshoot if the site does not appear
Troubleshoot if the site does not appear
If your site shows a 404 or blank page after enabling Pages: 1. **Check for index.html**: Make sure a file named exactly `index.html` exists at the root of your repository (not in a subfolder). 2. **Check the Actions tab**: Click the **Actions** tab in your repository. Look for the 'pages build and deployment' workflow. A red X means the build failed — click it to see the error message. 3. **Hard refresh your browser**: Press Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows) to clear the cache. 4. **Wait**: The first deployment can take up to 5 minutes. Subsequent updates are usually faster. If you continue to have issues, the RapidDev team can help troubleshoot deployment problems and optimize your Pages configuration.
Expected result: The issue is identified and resolved, and your site loads correctly.
Complete working example
1<!DOCTYPE html>2<html lang="en">3<head>4 <meta charset="UTF-8">5 <meta name="viewport" content="width=device-width, initial-scale=1.0">6 <title>My Project</title>7 <link rel="stylesheet" href="style.css">8</head>9<body>10 <header>11 <h1>My Project</h1>12 <p>Built and published with GitHub Pages</p>13 </header>14 <main>15 <section>16 <h2>About</h2>17 <p>This is a static website hosted for free on GitHub Pages.</p>18 </section>19 <section>20 <h2>Features</h2>21 <ul>22 <li>Fast and reliable hosting</li>23 <li>Automatic HTTPS</li>24 <li>Custom domain support</li>25 <li>Updates on every commit</li>26 </ul>27 </section>28 </main>29 <footer>30 <p>© 2026 My Project. Hosted on GitHub Pages.</p>31 </footer>32</body>33</html>Common mistakes when publishing a Project Using GitHub Pages
Why it's a problem: Putting index.html inside a subfolder instead of the repository root
How to avoid: Move index.html to the root of the repository, or change the Pages folder setting to match (e.g., /docs if your files are in docs/).
Why it's a problem: Using absolute paths for CSS and images (e.g., /style.css)
How to avoid: Use relative paths (e.g., ./style.css or style.css) because your site may be served from a subpath like /repo-name/.
Why it's a problem: Repository is private on a free GitHub account
How to avoid: GitHub Pages requires a public repository on free accounts. Go to Settings → Danger Zone → Change visibility to make it public.
Why it's a problem: DNS records not configured correctly for custom domain
How to avoid: Double-check the CNAME record points to yourusername.github.io (not the repository URL). For apex domains, use the four A record IP addresses listed in GitHub's documentation.
Best practices
- Name your repository descriptively — the name becomes part of your URL.
- Always include an index.html file at the root of your deployment branch.
- Use relative paths for all links, stylesheets, images, and scripts.
- Enable 'Enforce HTTPS' in Pages settings for security and SEO benefits.
- Check the Actions tab after each commit to confirm the deployment succeeded.
- For AI-built projects (Lovable, V0), export the static build output and upload those files — not the source code.
- Test your site on mobile by opening the URL on your phone after deployment.
- Use a custom domain for professional projects — it costs as little as $10/year for a .com domain.
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I want to publish my portfolio website on GitHub Pages. I have HTML, CSS, and JavaScript files ready. Walk me through the entire process including creating the repository, uploading files, enabling Pages, and setting up a custom domain.
Frequently asked questions
Can I host a React or Vite project on GitHub Pages?
Yes, but you need to upload the build output (the contents of the dist/ or build/ folder), not the source code. Build your project locally or with an AI tool, then upload the output files to your repository.
How much does GitHub Pages cost?
GitHub Pages is completely free for public repositories. There are soft limits of 1GB storage and 100GB bandwidth per month, which is sufficient for most personal and small business websites.
Can I use GitHub Pages for an online store?
GitHub Pages can host the frontend of a store, but it cannot process payments or manage a database. You would need to integrate with external services like Stripe for payments and Supabase or Firebase for data storage.
How do I take down a GitHub Pages site?
Go to Settings → Pages, change the Branch dropdown to 'None,' and click Save. The site will be unpublished within minutes. Alternatively, delete the repository entirely.
Can I have multiple GitHub Pages sites?
Yes. Every repository can have its own Pages site at yourusername.github.io/repo-name. You also get one special site at yourusername.github.io if you create a repository with that exact name.
Can RapidDev help deploy my AI-built project to GitHub Pages?
Yes. RapidDev can help you export projects from tools like Lovable or V0, configure the repository correctly, enable GitHub Pages, and connect your custom domain.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation