How to Deploy Your Website for Free Using GitHub Pages: A Complete Beginner’s Guide
📘 Chapter 3: Deploying Your Site Using GitHub Pages
🧭 What You’ll Learn
In this chapter, you’ll learn:
- How
to activate GitHub Pages for your repository
- Deployment
methods: root vs. /docs folder
- Using
custom domains with GitHub Pages
- Live
preview and URL structure
- How
to fix common deployment issues
- Automating
deployments with GitHub Actions (intro)
🚀 What Is Deployment?
Deployment is the process of taking your local or
staged website and making it publicly accessible via the internet. With GitHub
Pages, you’re hosting a static site by simply pushing your files to a
GitHub repo and enabling a few settings.
✅ Deployment Types with GitHub
Pages
|
Type |
URL Format |
Repo Name
Requirement |
|
User/Org Site |
https://username.github.io/ |
Must be
username.github.io |
|
Project Site |
https://username.github.io/repo-name/ |
Any repo name
allowed |
🔧 Step-by-Step: Enabling
GitHub Pages
Let’s assume you’ve already created your repository and
uploaded the static site files (see Chapter 2). Here’s how to go live:
🪜 Enable GitHub Pages
- Go
to your repository on GitHub
- Click
Settings (top menu)
- Scroll
down to the “Pages” section in the sidebar
- Under
“Source”, choose:
- Branch:
main
- Folder:
/ (root) or /docs
- Click
Save
GitHub will now start publishing your site.
⏳ Wait Time
- Your
site will typically go live within 30 seconds to 2 minutes
- A
banner will appear:
“Your site is live at https://username.github.io/repo-name/”
📂 Deployment Options:
Root vs. /docs Folder
|
Setting |
Description |
When to Use |
|
Root (/) |
Deploys site from root
directory (index.html at root) |
For simple static
sites |
|
/docs folder |
Deploys from
a folder inside the repo (e.g., myproject/docs/) |
For
multi-purpose repos (code + documentation) |
📝 If you're using the
/docs folder, make sure index.html is inside it.
💻 Sample index.html File
for Testing
html
<!DOCTYPE
html>
<html>
<head>
<title>Hello GitHub
Pages</title>
<meta charset="UTF-8" />
</head>
<body>
<h1>Hello World</h1>
<p>This is my first GitHub Pages
site!</p>
</body>
</html>
Place this in the root (or /docs) and follow the deployment
steps.
🌐 Accessing Your Deployed
Site
After successful deployment, your site will be accessible
at:
text
https://yourusername.github.io/repository-name/
Example:
https://johnsmith.github.io/portfolio/
For user sites, if your repo is named
johnsmith.github.io, then the site is at:
text
https://johnsmith.github.io/
🧪 Testing Deployment
After publishing:
- Clear
your browser cache or use incognito
- Check
the developer console (F12) for any missing resources (like images or
stylesheets)
- Make
sure links and navigation work correctly
🛠️ Troubleshooting
Common Deployment Issues
|
Issue |
Possible Cause |
Solution |
|
404 Not Found |
No index.html, wrong
folder selected |
Ensure correct source
folder and filename |
|
Styles or JS not loading |
Incorrect
file paths |
Use relative
paths, e.g., css/style.css |
|
Deployment delayed |
GitHub caching or
config issues |
Refresh or wait a few
minutes |
|
No HTTPS |
HTTPS not
enforced |
Go to Settings
> Pages and check HTTPS box |
|
Domain not
resolving |
DNS misconfigured or
missing CNAME |
Update domain DNS and
create CNAME file |
🌍 Custom Domain
Configuration (Optional)
Want to use www.yoursite.com instead of username.github.io?
🪜 Steps to Add a Custom
Domain
- Buy
a domain (from Namecheap, GoDaddy, etc.)
- Go
to your domain DNS settings
- Add
a CNAME record pointing to:
lua
yourusername.github.io
- In
your GitHub repo:
- Create
a file named CNAME (no extension)
- Add
your domain inside:
www.yoursite.com
- Commit
and push the change
GitHub will detect the domain and serve your site over HTTPS
(may take up to 24 hrs).
🌐 Domain Record Types
|
Record Type |
Hostname |
Points To |
Use Case |
|
A Record |
@ |
GitHub IPs (e.g.,
185.199.108.153) |
For apex domains like
mysite.com |
|
CNAME |
www |
username.github.io |
For
subdomains like www.mysite.com |
🔁 Automating Deployment
with GitHub Actions (Preview)
For advanced users, you can use GitHub Actions to
automate builds and deployments for static site generators like React, Vue,
Jekyll, or Hugo.
✅ Sample GitHub Actions Workflow
Create .github/workflows/deploy.yml:
yaml
name:
Deploy to GitHub Pages
on:
push:
branches:
- main
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: echo "Deploying static
site..."
- run: cp -R ./build/* ./docs/
- run: git add .
- run: git commit -m "Auto-deploy
site"
- run: git push
This is a basic setup for pushing build output to /docs.
🧼 Clean Deployment
Checklist
|
Task |
✅ Done |
|
Repo created and
public |
✅ |
|
index.html at root or /docs |
✅ |
|
GitHub Pages
enabled |
✅ |
|
HTTPS enforced |
✅ |
|
Custom domain
(optional) set |
✅ |
|
Tested on live URL |
✅ |
📊 Table: Deployment
Settings Summary
|
Setting |
Value |
|
Source |
main branch |
|
Folder |
/ (root) or
/docs |
|
HTTPS |
Enabled |
|
URL Format |
https://username.github.io/ |
|
Custom Domain File |
CNAME |
🧠 Pro Tips
- Use relative
paths (like ./css/styles.css) to avoid broken links
- Add
a favicon.ico for branding
- Push
changes to update the live site automatically
- Use GitHub Status to
check service issues
- Bookmark
your GitHub Pages link!
🧾 Summary
In this chapter, you learned:
- How
to enable GitHub Pages on your repo
- Deployment
options and folder structure
- How
to preview and access your live site
- Custom
domain setup
- Troubleshooting
common issues
- How
to prep for future automation with GitHub Actions
You’ve officially published your first live
website! 🎉
In the next chapter, we’ll explore advanced customization, themes, and using
Jekyll.
FAQs
❓ 1. What is GitHub Pages and how does it work?
Answer:
GitHub Pages is a free hosting service by GitHub that allows you to publish
static websites directly from a GitHub repository. It works by serving the
HTML, CSS, JS, and other static files from your repo to a web URL like
https://yourusername.github.io/.
❓ 2. Is GitHub Pages really free to use?
Answer:
Yes, GitHub Pages is completely free. There are no hidden fees, and you can
host as many static sites as you want as long as your repository is public.
Private repo hosting is available with GitHub Pro.
❓ 3. What kind of websites can I host on GitHub Pages?
Answer:
You can host static websites, such as portfolios, documentation, blogs,
resumes, and simple landing pages. It does not support server-side languages
like PHP, Python, or databases.
❓ 4. What file should my website start with for GitHub Pages to work?
Answer:
Your site should have an index.html file in the root directory (or /docs if
using that folder). This acts as the homepage for your site.
❓ 5. How long does it take for my GitHub Pages site to go live?
Answer:
Typically, your site is live within 30 seconds to 2 minutes after
enabling GitHub Pages. However, DNS changes (like custom domains) may take up
to 24 hours.
❓ 6. Can I use a custom domain with GitHub Pages?
Answer:
Yes! You can map a custom domain by updating your DNS settings and adding a
CNAME file to your repository with your domain name in it (e.g.,
www.yoursite.com).
❓ 7. Can I use GitHub Pages with frameworks like React or Vue?
Answer:
Yes, you can build your project and push the static build/ folder to
your GitHub repo. Some projects use the /docs folder for this or deploy using
GitHub Actions for automation.
❓ 8. How do I fix broken links or missing styles/scripts?
Answer:
Check if your file paths are correct and relative (e.g., ./style.css instead of
/style.css). Also, make sure your files are in the correct directories and
committed to the repo.
❓ 9. Can I use GitHub Pages for private projects?
Answer:
You can only host public repos for free with GitHub Pages. For private repo
hosting, you’ll need a GitHub Pro plan or use GitHub Actions to deploy
elsewhere (like Netlify).
❓ 10. What are some alternatives to GitHub Pages?
Answer:
Other free static hosting options include:
- Netlify
- Vercel
- Firebase
Hosting
- Cloudflare Pages
These services offer more flexibility for dynamic apps,
CI/CD, and advanced routing.
Comments(0)