A portfolio website gives employers and clients one link that shows your work. GitHub Pages lets you publish that kind of site straight from a GitHub repository. By the end of this guide, you will be able to create the right repository, add a home page, switch publishing on and check that your site is live.

The steps follow GitHub’s documentation, mainly the Quickstart for GitHub Pages. Steps and limits are given as the documentation stated them in late 2026. Button names change from time to time, so compare them with your screen.

What GitHub Pages is

According to What is GitHub Pages?, the service is static site hosting: it takes HTML, CSS and JavaScript files from a repository, can optionally run them through a build process, and publishes the result. A site about yourself is one of the uses GitHub lists.

A user site lives in a repository named <username>.github.io and is published at that address, with one allowed per account. A project site belongs to an ordinary repository and appears at <username>.github.io/<repositoryname>. For a portfolio, the user site is the natural choice.

Before you start

GitHub’s page on creating a GitHub Pages site says Pages is available in public repositories on GitHub Free, and in public and private repositories on paid plans such as GitHub Pro. The published site is public either way, and GitHub warns that you may want to remove sensitive data from the repository before publishing. Keep your home address, identity numbers and private documents out of it.

Step 1: Create the repository

  1. In the upper-right corner of any GitHub page, open the plus menu and click New repository.
  2. Name it username.github.io, using your own GitHub username. Capital letters in your username must be typed in lowercase.
  3. Choose the visibility, turn Add README on and click Create repository.

Step 2: Add a home page

GitHub Pages looks for an entry file named index.html, index.md or README.md. When you publish from a branch and folder, the entry file must sit at the top level of that folder. The quickstart simply uses README.md as the page content. If you prefer HTML, create index.html in the repository with something like this:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Your Name | Portfolio</title>
</head>
<body>
  <h1>Your Name</h1>
  <p>Junior web developer: small, fast, accessible websites.</p>
  <p><a href="https://github.com/your-username/weather-app">Weather app</a> (HTML, CSS, JavaScript)</p>
  <p>Contact: you@example.com</p>
</body>
</html>

Replace the placeholders with your own details and commit the file. Keep the first version small: your name, a one-line summary, three to five projects linked to their code, and a way to contact you.

Step 3: Turn on publishing

  1. Under the repository name, click Settings. If you cannot see it, open the dropdown menu and click Settings there.
  2. In the “Code, planning, and automation” section of the sidebar, click Pages.
  3. Under “Build and deployment”, set Source to Deploy from a branch.
  4. Under “Branch”, select the branch that holds your files.

Step 4: Check that the site is live

Go back to Settings, then Pages, and click Visit site, or type username.github.io into your browser. GitHub notes that changes can take up to 10 minutes to appear after you push them.

Step 5: Set a title (optional)

If you publish the README version, the default title is username.github.io. The quickstart explains how to change it: create a file named _config.yml if it does not exist, add a title: line and a description: line, then click Commit changes.

theme: jekyll-theme-minimal
title: Your Name
description: Web projects and contact details

Limits and rules

The GitHub Pages limits page sets these usage limits:

  • One user or organization site per GitHub account.
  • A recommended limit of 1 GB for the source repository, and a maximum of 1 GB for the published site.
  • Deployments time out after 10 minutes.
  • A soft bandwidth limit of 100 GB per month, and a soft limit of 10 builds per hour that does not apply to sites built with a custom GitHub Actions workflow.

The same page says GitHub Pages is not intended or allowed as free hosting for an online business, an e-commerce site or commercial software as a service, and should not be used for sensitive transactions such as sending passwords or credit card numbers.

Common mistakes

  • A misspelled repository name. A user site needs the exact pattern username.github.io, in lowercase.
  • The entry file in the wrong folder. It must be at the top level of the folder you publish from.
  • A private repository on a free plan. On GitHub Free, the repository has to be public.
  • Expecting instant updates. Allow up to 10 minutes after each push before deciding something is broken.
  • Publishing private information. Share only contact details you are happy for anyone to see.

A GitHub Pages portfolio needs one correctly named repository, one entry file and one setting. Start with a single page, check it at your github.io address and improve it each time you finish a project. If your screen looks different from these steps, check the linked documentation, since GitHub updates its menus and limits.