LATEST 🚀 Welcome to Upgradix by Shrash Studio – Your destination for free technology learning and career growth.
🕘 Updated:
Git & GitHub

GitHub Pages – Host and Publish Your Website for Free

You don't need to purchase a hosting server or configure a web server. You can publish HTML, CSS and JavaScript websites and share the live URL with anyone.

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.

In this article
  • 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.
Important: GitHub Pages is designed for static websites. It does not run your ASP.NET Core, Node.js, Python, PHP or other server-side application code. You can host a frontend there, but a backend API must run on a separate hosting platform.

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

Website files move from a developer's computer to a GitHub repository, through the Pages deployment process, and become available to website visitors. Developer HTML / CSS / JS GitHub Repo Committed files Pages Deploy Build and publish Live Website Public URL Push Deploy Publish

The developer pushes website files to GitHub. GitHub Pages deploys the selected source and serves the published website.

The publishing sequence

Step 1 – Create website files Build your website locally using HTML, CSS, JavaScript and static assets.
Step 2 – Push files to GitHub Commit and push the website files to the repository's publishing branch.
Step 3 – Configure GitHub Pages Select a branch and source folder, or configure a GitHub Actions workflow.
Step 4 – GitHub deploys the website GitHub runs the Pages deployment process and makes the website available.
Step 5 – Visitors open the website Anyone with the published URL can access the website through a browser.

3. Types of GitHub Pages Websites

GitHub Pages supports different website URL structures depending on the repository name.

GitHub Pages website types
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.

Remember: Project websites are published under a repository path. When configuring CSS, JavaScript and image paths, account for that path. Root-relative paths such as /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

  1. Sign in to GitHub.
  2. Click the New repository option.
  3. Enter employee-portal-demo as the repository name.
  4. Choose Public if you are using GitHub Free.
  5. 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.

Step 1 – Open repository settings Open your employee-portal-demo repository and select Settings.
Step 2 – Open Pages In the settings sidebar, find the Code, planning, and automation section and select Pages.
Step 3 – Select the publishing source Under Build and deployment, choose Deploy from a branch as the source.
Step 4 – Select branch and folder Select main as the branch and /(root) as the folder.
Step 5 – Save the configuration Click Save. GitHub will start the publishing workflow.
Step 6 – Open the published website Return to the Pages settings section. Once deployment completes, use Visit site to open your website.

Example published URL

https://YOUR-USERNAME.github.io/employee-portal-demo/
Deployment time: Publishing is not always immediate. GitHub notes that changes can take up to 10 minutes to appear after you push them. Check the Actions tab if the deployment does not complete.

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 developer edits a website, commits and pushes changes, GitHub deploys them, and visitors receive the updated page. Edit files Local changes Git Push New commit Deployment Pages workflow Updated site Latest version Every successful deployment publishes the selected website version.

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.

Comparing GitHub Pages publishing approaches
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:

  1. Open your repository's Settings → Pages.
  2. Enter your domain under Custom domain.
  3. Update the required DNS records with your domain provider.
  4. Wait for GitHub to verify the DNS configuration and provision HTTPS.
  5. Enable Enforce HTTPS when it becomes available.
Security recommendation: Verify ownership of your custom domain through GitHub before configuring it. Incorrect DNS records or unverified domain configurations can create domain takeover risks.

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.

GitHub Pages capabilities and limitations
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.

Do not use GitHub Pages for sensitive transactions. It is not intended for sites primarily facilitating commercial transactions or SaaS, and should not be used to collect passwords, credit card numbers or other sensitive transaction data.

10. Common GitHub Pages Problems

Problem 1 – Website displays a 404 error

Possible reasons:

  • The publishing source is configured incorrectly.
  • The index.html file 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

Exercise 1 – Publish a personal portfolio Create an HTML portfolio containing your name, skills, projects and contact information. Publish it using a GitHub Pages repository.
Expected result: A publicly accessible portfolio URL.
Exercise 2 – Publish project documentation Create a documentation website for a sample employee management application. Include an overview, features, installation instructions and screenshots.
Expected result: A documentation website hosted through GitHub Pages.
Exercise 3 – Configure a custom domain Use a domain you own and configure it for your GitHub Pages website.
Expected result: Your website opens using your custom domain with HTTPS.
Exercise 4 – Publish an update Change the homepage title, commit the change and push it to the configured branch.
Expected result: The deployed website displays the updated content.

13. Interview Questions and Answers

1. What is GitHub Pages? GitHub Pages is a static website hosting service that publishes website files from a GitHub repository. It is commonly used for portfolios, documentation, blogs and project demonstrations.
2. What is the difference between a user site and a project site? A user site uses the special repository name 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.
3. Can GitHub Pages host an ASP.NET Core Web API? No. GitHub Pages serves static website files. An ASP.NET Core API requires a server-side hosting environment. The frontend can be hosted on GitHub Pages and communicate with an independently hosted API.
4. How does automatic deployment work in GitHub Pages? When branch publishing is configured, changes pushed to the selected branch and folder trigger the Pages publishing process. GitHub Actions can also be configured for a custom build and deployment workflow.
5. Can GitHub Pages use a custom domain and HTTPS? Yes. You can configure a custom domain through repository Pages settings and update the required DNS records. GitHub Pages supports HTTPS, and HTTPS enforcement can be enabled after the domain is correctly configured.

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

Official Documentation and Further Learning

Comments & Ratings (0)

Log in or create a student account to comment and rate this article.

Be the first to comment on this article.