GitHub Pages lets you turn any repository into a live website for free. Go to your repository's Settings → Pages, select the branch containing your HTML files, click Save, and wait 1-3 minutes. GitHub gives you a URL like yourusername.github.io/repo-name where anyone can view your site.
What Is GitHub Pages and How Does It Work
GitHub Pages is a free hosting service built into GitHub. It takes the files in your repository (HTML, CSS, JavaScript) and serves them as a live website. Every time you update your repository, GitHub automatically rebuilds and redeploys the site.
Key concepts to understand:
- **Static sites only.** GitHub Pages hosts static files — HTML, CSS, JavaScript, and images. It cannot run server-side code like Node.js, Python, or PHP. If your project needs a backend, you will need a separate hosting service. - **Branch-based deployment.** You choose which branch contains your website files. Usually this is `main` or `gh-pages`. GitHub reads the files from that branch and publishes them. - **URL structure.** Your site is available at `yourusername.github.io/repository-name`. For example, if your GitHub username is 'janedoe' and your repo is 'my-portfolio,' the URL is `janedoe.github.io/my-portfolio`. - **Build time.** After enabling Pages or pushing changes, it takes 1-3 minutes for the site to go live or update.
This is perfect for previewing projects you have built with AI tools like V0 or Lovable — just export the static build files to a GitHub repository and enable Pages.
Prerequisites
- A GitHub account (free tier works for public repositories)
- A repository containing at least an index.html file
- The repository must be public (on free accounts) for Pages to work
Step-by-step guide
Open your repository settings
Open your repository settings
Navigate to your repository on GitHub. You should see your files listed on the main code page. Click the **Settings** tab in the top navigation bar (it is the last tab, with a gear icon). If you do not see the Settings tab, you may not have admin access to this repository — ask the repository owner to enable Pages or grant you admin permissions.
Expected result: You are on the repository's Settings page with a sidebar of configuration options on the left.
Navigate to the Pages settings
Navigate to the Pages settings
In the left sidebar of the Settings page, scroll down to the **Code and automation** section and click **Pages**. This is the GitHub Pages configuration panel where you control how your site is built and published.
Expected result: You see the GitHub Pages settings page with a 'Source' section.
Enable GitHub Pages by selecting a branch
Enable GitHub Pages by selecting a branch
Under the **Build and deployment** section, find the **Source** dropdown. Make sure it is set to **Deploy from a branch**. Below that, click the **Branch** dropdown (it may say 'None' if Pages is not yet enabled). Select **main** (or whichever branch contains your HTML files). Leave the folder dropdown set to **/ (root)** unless your site files are in a `/docs` folder. Click the **Save** button. GitHub will begin building your site.
Expected result: A message appears saying 'GitHub Pages source saved.' The site will be available shortly.
Wait for the deployment and find your URL
Wait for the deployment and find your URL
After clicking Save, stay on the Pages settings page. Within 1-3 minutes, refresh the page and a green banner will appear at the top showing your site URL: **yourusername.github.io/repository-name**. Click the URL or the **Visit site** button to open your live website in a new tab. If you see an orange banner instead, the build is still in progress. Wait another minute and refresh. If you see a red error, there is an issue with your files (most often a missing index.html).
Expected result: A green banner shows your live site URL, and clicking it opens your website in the browser.
Check the deployment status for errors
Check the deployment status for errors
To see detailed build information, go back to your repository's main page and click the **Actions** tab in the top navigation bar. You will see a list of workflow runs — the most recent one should be your GitHub Pages deployment. A green checkmark means success. A red X means the build failed. Click on a failed run to see the error details. Common issues include: missing index.html at the root, broken file references, or invalid HTML. Fix the issue in your repository and GitHub will automatically rebuild.
Expected result: The Actions tab shows a green checkmark for a successful Pages deployment.
Update your site by pushing changes
Update your site by pushing changes
Every time you edit files in your repository — whether through the GitHub web editor (pencil icon on any file), GitHub Desktop, or by merging a pull request — GitHub automatically rebuilds your Pages site. Changes typically appear within 1-3 minutes after the commit. To edit a file directly: navigate to the file in your repository, click the **pencil icon** to edit, make your changes, and click **Commit changes**. Then wait a minute or two and refresh your live site URL.
Expected result: Your live site reflects the changes you made to the repository files.
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 GitHub Pages Site</title>7 <style>8 body {9 font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;10 max-width: 700px;11 margin: 0 auto;12 padding: 2rem;13 background: #f8f9fa;14 color: #1a1a2e;15 }16 h1 { color: #0d1117; }17 a { color: #0969da; }18 </style>19</head>20<body>21 <h1>Welcome to My Site</h1>22 <p>This page is hosted for free on GitHub Pages.</p>23 <p>Edit index.html in your repository to update this content.</p>24</body>25</html>Common mistakes when previewing a Website With GitHub Pages
Why it's a problem: Repository is private on a free GitHub account
How to avoid: GitHub Pages requires a public repository on the free tier. Either make the repository public (Settings → Danger Zone → Change visibility) or upgrade to GitHub Pro.
Why it's a problem: Missing index.html file at the root of the repository
How to avoid: GitHub Pages looks for index.html in the root (or /docs folder if configured). Make sure your main HTML file is named exactly index.html.
Why it's a problem: Checking the site immediately after enabling Pages
How to avoid: The first build takes 1-3 minutes. Wait and refresh the Pages settings page to see the green banner with your URL.
Why it's a problem: Selecting the wrong branch or folder
How to avoid: Verify that the branch you selected actually contains your HTML files. Check the folder setting — use / (root) if files are at the top level.
Best practices
- Always name your main page index.html — GitHub Pages uses this as the default entry point.
- Use relative paths for links and images (e.g., ./images/photo.jpg) rather than absolute paths.
- Check the Actions tab after each commit to verify the deployment succeeded.
- For projects built with AI tools like V0 or Lovable, export the static build (dist/ folder contents) to the repository root for Pages compatibility.
- Add a descriptive title and meta description in your HTML head for better search engine visibility.
- Bookmark your Pages URL for easy access: yourusername.github.io/repository-name.
- Keep images optimized (under 1MB each) to ensure fast loading on your GitHub Pages site.
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I have a GitHub repository with HTML and CSS files. Walk me through enabling GitHub Pages step by step using only the web interface. My repository is public and files are in the root directory.
Frequently asked questions
Is GitHub Pages really free?
Yes. GitHub Pages is free for public repositories on all account types. There are soft limits: 1GB storage, 100GB bandwidth per month, and 10 builds per hour. For most personal and small business sites, these limits are more than enough.
Can I use a custom domain with GitHub Pages?
Yes. In the Pages settings, there is a Custom domain field where you enter your domain name. You also need to add a CNAME DNS record at your domain registrar pointing to yourusername.github.io. GitHub provides free HTTPS for custom domains.
Can I host a React or Next.js app on GitHub Pages?
React apps built with Vite or Create React App can be hosted after running the build command and deploying the output. Next.js apps with server-side features cannot use GitHub Pages — use Vercel instead. For static Next.js exports, Pages works.
How long does it take for changes to appear on my site?
Usually 1-3 minutes after committing changes. If your site does not update after 5 minutes, check the Actions tab for build errors. You can also try a hard refresh in your browser (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows).
Can I use GitHub Pages for a project built with an AI tool?
Yes. If your AI tool (like V0 or Lovable) exports static HTML/CSS/JS files, you can put them in a GitHub repository and enable Pages. For full-stack apps with a backend, you would need a different hosting platform like Vercel or Railway.
Can RapidDev help me set up GitHub Pages for my project?
Yes. RapidDev can help you configure GitHub Pages, set up custom domains, troubleshoot build errors, and optimize your site for production deployment.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation