Free web hosting sounds too good to be true. It’s not.
GitHub Pages lets you publish static websites directly from a repository, no server configuration required. Learning how to host a website on GitHub takes about 15 minutes and zero dollars.
Millions of developers use this method for portfolios, documentation sites, and project demos.
The setup works entirely through your browser. No command line experience needed.
This guide walks you through seven steps: creating an account, setting up a repository, uploading files, enabling GitHub Pages, accessing your live URL, updating content, and connecting a custom domain.
By the end, your site goes live at a github.io address with free HTTPS included.
How to Host a Website on GitHub
Hosting a website on GitHub is the process of publishing static web pages using GitHub Pages directly from a repository.
Users need this when launching portfolios, documentation sites, or project demos without paying for traditional web hosting.
This guide covers 7 steps requiring 15 minutes and a free GitHub account.
If you’re new to the platform, understanding what GitHub actually is will give you useful context before starting.
Prerequisites
Before you begin, gather these requirements:
- GitHub account (free tier works)
- Web browser: Chrome 120+, Firefox 121+, or Edge 120+
- Basic HTML knowledge
- Website files: index.html required; CSS and JavaScript optional
- Time estimate: 10-15 minutes
- Custom domain (optional)
You’ll also want a basic grasp of version control concepts since GitHub tracks every change you make.
Step One: How Do You Create a GitHub Account?
Navigate to github.com and click Sign up in the top-right corner. Enter your email, create a password, choose a username, then verify your email address. Your username becomes part of your website URL.
Action
- Go to: github.com > Sign up button (top right)
- Enter: Email address, password, username (lowercase, no spaces)
- Complete: Email verification via the link GitHub sends you
Purpose
Your GitHub account stores all website files and controls deployment settings.
The username you pick here determines your default site URL: username.github.io.
Choose carefully. Changing it later breaks existing links.
Step Two: How Do You Create a New Repository for Your Website?
Click the green New button on your dashboard or the plus icon in the navigation bar. Name the repository username.github.io (replacing username with your actual GitHub username). Set visibility to Public, check “Add a README file,” then click Create repository.
Action
- Location: Dashboard > New button (green) or top navigation > + icon > New repository
- Repository name: Enter exactly username.github.io (case-sensitive)
- Settings: Select Public visibility; toggle “Add a README file” to on
Purpose
The repository acts as the container for your entire codebase.
The specific naming format (username.github.io) tells GitHub this is a user site, not a project site.
Public visibility is required for free GitHub Pages hosting.
Step Three: How Do You Add Your Website Files to the Repository?
Open your repository and click Add file > Upload files. Drag your index.html, CSS files, and any images into the upload area. Write a brief commit message describing what you’re adding, then click Commit changes.
Action
- Path: Repository main page > Add file dropdown > Upload files
- Upload: Drag index.html plus all CSS, JavaScript, and image files
- Commit: Enter message like “Initial website files” > Click Commit changes
Purpose
The index.html file serves as your website’s entry point.
GitHub Pages looks for this file first when someone visits your URL.
Without it, visitors see your README content or a 404 error. Every file you upload becomes part of your static site deployment.
Learning how to push files to GitHub via command line gives you more control for future updates.
Step Four: Where Do You Enable GitHub Pages in Repository Settings?
Go to your repository’s Settings tab, scroll down to the Pages section in the left sidebar. Under Source, select Deploy from a branch, choose main as the branch, select root as the folder, then click Save.
Action
- Path: Repository > Settings tab > Pages (left sidebar under Code and automation)
- Source: Select “Deploy from a branch” from the dropdown
- Branch: Choose main branch, / (root) folder > Click Save
Purpose
This setting activates GitHub Pages for your repository and triggers the initial build.
The branch and folder selection tells GitHub where to find your website files.
Step Five: How Do You Access Your Published Website URL?
Return to Settings > Pages after saving. GitHub displays your live site URL at the top: https://username.github.io. Click Visit site to verify deployment. Propagation takes up to 10 minutes.
Action
- Location: Settings > Pages > “Your site is live at” message
- URL format: https://username.github.io (your actual username)
- Verify: Click the URL or Visit site button; check for your index.html content
Purpose
The github.io domain provides free HTTPS hosting with SSL certificates from Let’s Encrypt.
Bookmark this URL. Share it anywhere.
Step Six: How Do You Update Your Website After Publishing?
Edit files directly in your repository by clicking any file, then the pencil icon. Make changes, write a commit message, click Commit changes. GitHub automatically rebuilds your site within minutes.
Action
- Edit path: Repository > Click file > Pencil icon (top right of file view)
- Save: Modify content > Add commit message > Commit changes button
- Result: Automatic rebuild triggers; changes appear in 2-5 minutes
Purpose
Every commit triggers a fresh deployment through GitHub’s continuous deployment system.
No manual uploads needed after initial setup. Understanding what git commit does helps you track all changes over time.
Step Seven: How Do You Connect a Custom Domain to GitHub Pages?
In Settings > Pages, enter your domain in the Custom domain field and save. Create a CNAME file in your repository root containing your domain name. Configure DNS A records pointing to GitHub’s IP addresses: 185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153.
Action
- GitHub: Settings > Pages > Custom domain field > Enter yourdomain.com > Save
- Repository: Add file named CNAME (no extension) containing only your domain
- DNS provider: Create four A records pointing to GitHub’s IP addresses
Purpose
Custom domains replace the github.io URL with your branded address.
DNS propagation takes 24-48 hours; HTTPS enables automatically after propagation completes.
Verification
Confirm your static website deployment worked correctly:
- Browser check: Visit your URL in an incognito window to bypass cache
- HTTPS: Verify the padlock icon appears in the address bar
- Mobile: Test on phone to confirm responsive layout
- Links: Click all internal links to catch broken paths
Check the Actions tab in your repository if the site shows outdated content. Failed builds display error messages there.
Troubleshooting
Issue: 404 Error on Website URL
Solution: Verify your repository name matches exactly: username.github.io (case-sensitive). Confirm index.html exists in the root folder, not a subfolder. Check Settings > Pages shows the correct branch and folder.
Issue: Custom Domain Not Connecting
Solution: Wait 24-48 hours for DNS propagation. Verify A records point to all four GitHub IPs. Confirm CNAME file exists in repository root with correct domain spelling.
Issue: Changes Not Appearing on Live Site
Solution: Clear browser cache or use incognito mode. Check repository’s Actions tab for failed builds. Verify you committed to the correct branch (main, not a feature branch).
Issue: CSS or Images Not Loading
Solution: Use relative paths (./styles.css) not absolute paths. Check file extensions match exactly (case-sensitive on GitHub). Verify files uploaded to the correct folder location.
Alternative Methods
GitHub Desktop Method
Download GitHub Desktop from desktop.github.com. Clone your repository locally, add files through your file system, then push changes through the desktop app.
Best for: Users uncomfortable with browser uploads; managing multiple files.
Git Command Line Method
Use terminal commands for full source control capabilities:
git clone https://github.com/username/username.github.iogit add .(stages all files)git commit -m "Your message"git push origin main
Best for: Developers familiar with Git who want faster workflows.
Learning how to use Git properly opens up branching, merging, and collaboration features.
GitHub Actions Workflow
For advanced users, GitHub Actions automate builds with static site generators like Jekyll or Hugo.
Create a .github/workflows/deploy.yml file to customize the build pipeline.
Next Steps and Related Processes
After your site goes live, consider these improvements:
- Jekyll themes: Add _config.yml to enable built-in themes without coding
- Custom 404 page: Create 404.html in root for branded error pages
- Analytics: Add Google Analytics tracking code to monitor visitors
- Forms: Use Formspree or Netlify Forms for contact functionality
GitHub Pages works perfectly for front-end development projects and static web apps.
For dynamic features requiring server-side code, explore Backend as a Service/) options or platforms like Netlify and Vercel.
Consider learning about merging branches in GitHub when collaborating with others on your site.
FAQ on How To Host A Website On Github
Is GitHub Pages Really Free?
Yes. GitHub Pages offers free static site hosting for public repositories with no hidden fees. You get a github.io subdomain, HTTPS certificate, and CDN distribution included. Private repository hosting requires a paid GitHub plan.
What Types of Websites Can GitHub Pages Host?
GitHub Pages supports static websites only: HTML, CSS, and JavaScript files. It works for portfolios, blogs, documentation, and landing pages. Server-side languages like PHP or Python won’t run. No database connections available.
How Long Does It Take for My Site to Go Live?
Initial deployment takes 1-10 minutes after enabling GitHub Pages. Updates typically appear within 2-5 minutes after each commit. DNS propagation for custom domains requires 24-48 hours.
Can I Use a Custom Domain Instead of github.io?
Yes. Add your domain in Settings > Pages, create a CNAME file in your repository, then configure DNS A records pointing to GitHub’s IP addresses. GitHub provides free HTTPS for custom domains automatically.
Do I Need to Know Git to Use GitHub Pages?
No. The browser interface handles file uploads and edits without command line tools. Understanding the difference between Git and GitHub helps, but isn’t required for basic hosting.
Why Is My GitHub Pages Site Showing a 404 Error?
Common causes: repository name doesn’t match username.github.io format, missing index.html file, wrong branch selected in Pages settings, or files placed in subfolders instead of root directory.
Can Multiple People Edit the Same GitHub Pages Site?
Yes. Add collaborators through Settings > Collaborators. Each person can push changes to the repository. Use branches and pull requests for organized workflows when multiple contributors edit simultaneously.
How Do I Add a Contact Form to My GitHub Pages Site?
GitHub Pages can’t process form submissions directly. Use third-party services like Formspree, Netlify Forms, or Getform. These handle API integration and email delivery for static sites.
What’s the Difference Between User Sites and Project Sites?
User sites deploy from username.github.io repositories to the root URL. Project sites deploy from any repository’s gh-pages branch or docs folder to username.github.io/repository-name subdirectories.
Can I Use Jekyll or Other Static Site Generators?
Yes. GitHub Pages has built-in Jekyll support with automatic builds. For Hugo, Gatsby, or other generators, use GitHub Actions to run custom build commands before deployment.
Conclusion
You now know how to host a website on GitHub using seven straightforward steps.
The entire process takes 15 minutes. No credit card required. No server management headaches.
GitHub Pages handles the deployment workflow automatically after every commit. Your changes go live within minutes.
Static site hosting through a repository gives you built-in version control for every file. Roll back mistakes instantly. Collaborate with others easily.
This free hosting solution works for portfolios, documentation, project demos, and landing pages. Add a custom domain when you’re ready to brand your site professionally.
Start with the browser upload method. Graduate to source control management via command line as your skills grow.
Understanding what GitHub is used for beyond hosting opens up collaboration, issue tracking, and deployment automation possibilities.
Many of his resources are available on various design marketplaces and for free on Codepen.
Over the years, he's worked with a range of clients and contributed to design publications like Design Your Way, Designmodo, WebDesignerDepot, WPDean, Speckyboy, and Slider Revolution among others.
- CSS Cheat Sheet - May 18, 2026
- How to Set Up VSCode for Python Development - May 16, 2026
- How Using One Platform Can Simplify Order Fulfillment - May 15, 2026
