GitHub Pages – Host and Publish Your Website for Free
Imagine you have created a personal portfolio, a project documentation website, or a landing page using HTML, CSS and JavaScript. The website works perfectly on your computer. But how can you make it accessible to everyone through a public URL without purchasing a hosting plan?
GitHub Pages solves this problem. It allows you to publish static websites directly from a GitHub repository. You can share your portfolio, documentation, project demos and learning projects using a URL hosted by GitHub.
- Understand what GitHub Pages is and how it works.
- Create a website repository and publish an HTML page.
- Configure automatic deployment from a branch.
- Understand project sites, user sites and custom domains.
- Learn limitations, troubleshooting and best practices.
1. What Is GitHub Pages?
GitHub Pages is a static website hosting service provided by GitHub. It takes website files stored in a GitHub repository and publishes them as a website that visitors can open through a browser.
A static website commonly contains:
- HTML for page structure.
- CSS for layout and styling.
- JavaScript for browser-side interactions.
- Images, icons, fonts and other static assets.
You do not need to manage a web server or configure hosting infrastructure for a basic website. You maintain the files in GitHub, configure a publishing source, and GitHub handles the deployment process.
Where can you use GitHub Pages?
- Personal portfolio and resume websites.
- Project documentation and user guides.
- Static blogs and learning resources.
- Frontend demonstrations and prototypes.
- Open-source project websites.
2. How Does GitHub Pages Work?
Think about a developer building a project documentation website. The developer updates the HTML and CSS files, pushes the changes to GitHub, and GitHub publishes the updated website.
GitHub Pages – Publishing Workflow
The developer pushes website files to GitHub. GitHub Pages deploys the selected source and serves the published website.
The publishing sequence
3. Types of GitHub Pages Websites
GitHub Pages supports different website URL structures depending on the repository name.
| Website type | Repository name | Example URL |
|---|---|---|
| User website | username.github.io |
https://username.github.io/ |
| Project website | portfolio |
https://username.github.io/portfolio/ |
User or organization website
A user website is associated with your GitHub account. The repository must use the special naming format username.github.io.
Project website
A project website is associated with a normal repository. For example, a repository named employee-portal-demo can be published under your GitHub Pages project URL.
/assets/style.css can point to the wrong location on a project website. Relative paths such as ./assets/style.css are often more suitable.4. Create Your First Website
Let's create a simple employee management project landing page. You will publish it using GitHub Pages without requiring a backend or paid hosting plan.
Prerequisites
- A GitHub account.
- A basic understanding of HTML.
- A web browser and a text editor.
- A GitHub repository where you can upload files.
Step 1 – Create a repository
- Sign in to GitHub.
- Click the New repository option.
- Enter
employee-portal-demoas the repository name. - Choose Public if you are using GitHub Free.
- Create the repository.
Step 2 – Create the website structure
Create the following files in your project:
employee-portal-demo/
│
├── index.html
├── css/
│ └── style.css
└── js/
└── app.js
The index.html file is the entry point for this website.
Step 3 – Add HTML
Create the page structure in index.html:
index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport"
content="width=device-width, initial-scale=1.0">
<title>Employee Portal Demo</title>
<link rel="stylesheet" href="./css/style.css">
</head>
<body>
<main class="container">
<h1>Employee Portal</h1>
<p>Welcome to our project website.</p>
<button id="welcomeButton">Get Started</button>
<p id="message"></p>
</main>
<script src="./js/app.js"></script>
</body>
</html>
Step 4 – Add CSS
Create a simple design in css/style.css:
css/style.css
body {
margin: 0;
font-family: Arial, sans-serif;
background: #f1f5f9;
color: #1e293b;
}
.container {
max-width: 650px;
margin: 80px auto;
padding: 32px;
text-align: center;
background: white;
border-radius: 12px;
}
button {
padding: 12px 20px;
border: 0;
border-radius: 6px;
background: #4f46e5;
color: white;
cursor: pointer;
}
Step 5 – Add JavaScript
Create the interaction in js/app.js:
js/app.js
const button = document.getElementById("welcomeButton");
const message = document.getElementById("message");
button.addEventListener("click", () => {
message.textContent = "Your website is working!";
});
When a visitor clicks the button, JavaScript updates the page content inside the browser.
Step 6 – Push the files to GitHub
If you are using Git locally, open a terminal inside the project folder and run:
Git commands
git init
git add .
git commit -m "Create employee portal website"
git branch -M main
git remote add origin https://github.com/YOUR-USERNAME/employee-portal-demo.git
git push -u origin main
Replace YOUR-USERNAME with your GitHub username. If the repository is already cloned, you do not need to run git init or add the remote again.
Expected result
Enumerating objects... Counting objects... Writing objects... To https://github.com/YOUR-USERNAME/employee-portal-demo.git * [new branch] main -> main
5. Configure and Publish GitHub Pages
Now that your website files are available in GitHub, configure the repository to publish them.
employee-portal-demo repository and select Settings.main as the branch and /(root) as the folder.Example published URL
https://YOUR-USERNAME.github.io/employee-portal-demo/
6. How Are Website Updates Published?
One of the useful features of GitHub Pages is that you can configure publishing to happen automatically whenever changes are pushed to the selected branch.
For example, imagine you update the employee portal heading or add a new page. You only need to commit and push the changes:
Update and publish
git add .
git commit -m "Update employee portal homepage"
git push origin main
GitHub detects the update to the configured publishing source and starts another deployment.
Automatic Website Update Cycle
A push to the configured source triggers deployment, so the published website can stay aligned with the latest committed files.
7. Branch Deployment vs GitHub Actions
GitHub Pages supports publishing from a branch or using a custom GitHub Actions workflow. The right choice depends on how your website is built.
| Area | Deploy from a branch | GitHub Actions |
|---|---|---|
| Configuration | Select a branch and folder. | Configure a workflow file. |
| Build process | GitHub's standard Pages build. | Custom build and deployment steps. |
| Best suited for | Simple static websites. | Frameworks and custom build processes. |
| Control | Simple publishing configuration. | Greater control over build and deployment. |
For a basic HTML, CSS and JavaScript website, deploying from a branch is usually sufficient. If your project needs a custom build process, GitHub Actions provides more flexibility.
8. Can You Use a Custom Domain?
Yes. GitHub Pages supports custom domains, allowing you to use a domain you own instead of the default github.io address.
For example, instead of:
https://username.github.io/portfolio/
You may configure a domain such as:
https://www.example.com
The general configuration process is:
- Open your repository's Settings → Pages.
- Enter your domain under Custom domain.
- Update the required DNS records with your domain provider.
- Wait for GitHub to verify the DNS configuration and provision HTTPS.
- Enable Enforce HTTPS when it becomes available.
9. Important Limitations of GitHub Pages
GitHub Pages is excellent for static website hosting, but it is not a replacement for every type of hosting platform.
| Feature | Supported? | Explanation |
|---|---|---|
| HTML, CSS and JavaScript | Yes | Static frontend files can be published. |
| Images and documents | Yes | Static assets can be hosted. |
| Custom domain | Yes | You can configure a domain you own. |
| HTTPS | Yes | HTTPS and enforcement are supported. |
| ASP.NET Core backend | No | Server-side application code is not executed. |
| SQL Server database | No | Pages does not provide a database server. |
| Server-side authentication | No | Requires a separate backend or authentication service. |
GitHub documents additional usage limits, including a recommended source repository size of 1 GB, a published site size limit of 1 GB, a soft bandwidth limit of 100 GB per month, and a soft build limit of 10 per hour for standard publishing. These limits can change, so check the official documentation before planning a high-traffic deployment.
10. Common GitHub Pages Problems
Problem 1 – Website displays a 404 error
Possible reasons:
- The publishing source is configured incorrectly.
- The
index.htmlfile is missing from the selected folder. - The deployment has not completed.
- The URL contains an incorrect repository path.
Solution: Check the Pages configuration, verify the entry file location, and inspect the latest deployment in the Actions tab.
Problem 2 – CSS or JavaScript is not loading
Possible reason: The website uses incorrect asset paths, especially when hosted as a project website under a repository path.
Solution: Use suitable relative paths and verify the browser's developer tools for failed network requests.
Problem 3 – Changes are not visible
Possible reasons: The deployment is still running, failed, or the browser is showing a cached resource.
Solution: Check the Actions workflow result, confirm that the correct branch was updated, and refresh the browser after deployment succeeds.
Problem 4 – Custom domain is not working
Possible reasons: DNS records are incorrect, domain verification is incomplete, or HTTPS certificate provisioning is still in progress.
Solution: Review the custom domain settings and DNS records. Allow time for DNS changes and certificate provisioning.
11. Best Practices for Production Websites
- Use a clear folder structure: Keep HTML, CSS, JavaScript and assets organised.
- Use relative asset paths: Avoid broken links when deploying project websites.
- Keep secrets out of repositories: Never commit API keys, passwords, private tokens or credentials.
- Use HTTPS: Enable HTTPS for your published website.
- Validate responsive layouts: Test the website on desktop, tablet and mobile screens.
- Check deployments: Review GitHub Actions when a publishing operation fails.
- Use a custom workflow when required: Choose GitHub Actions for custom build and deployment requirements.
- Separate frontend and backend: Host server-side services and databases on suitable platforms.
12. Hands-On Practice
Expected result: A publicly accessible portfolio URL.
Expected result: A documentation website hosted through GitHub Pages.
Expected result: Your website opens using your custom domain with HTTPS.
Expected result: The deployed website displays the updated content.
13. Interview Questions and Answers
username.github.io and is published at the account's root URL. A project site uses a normal repository and is published under a repository-specific path.14. Conclusion
GitHub Pages makes it simple to publish static websites directly from GitHub repositories. You can create a portfolio, publish project documentation, share frontend demonstrations and maintain a website without managing your own web server.
The important concept is the publishing workflow: create website files, push them to a repository, configure the publishing source, and let GitHub deploy the website.
For developers learning GitHub, GitHub Pages is a practical way to understand how source control and website deployment work together.
Learn Technology. Build Your Future.
Upgradix by Shrash Studio