GitHub Pages Tutorial: Host a Website for Free (Branch, Actions and Custom Domain)

GitHub Pages turns a repository into a website for free. In this lesson you will publish a portfolio from a branch, deploy with GitHub Actions, use Jekyll for Markdown sites, connect a custom domain and publish test reports.

---

🌐 What Is GitHub Pages?

GitHub Pages hosts static websites (HTML, CSS, JavaScript and files generated from Markdown) directly from a GitHub repository, with HTTPS and an optional custom domain. It is perfect for:

• Personal portfolios and resumes.
• Project documentation.
• Publishing test reports (for example a Playwright HTML report).
• Demo apps and landing pages.

---

🏷️ Types of Sites and Their URLs

Type	Repository name	URL
User site	<username>.github.io	https://<username>.github.io/
Organisation site	<org>.github.io	https://<org>.github.io/
Project site	Any name, e.g. portfolio	https://<username>.github.io/portfolio/

---

🚀 Option 1: Publish from a Branch (Quickest)

1. Create a repository (e.g. portfolio) with an index.html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Asha Verma – QA Automation Engineer</title>
  </head>
  <body>
    <h1>Asha Verma</h1>
    <p>QA Automation Engineer · Playwright · TypeScript</p>
    <a href="https://github.com/asha-verma-qa">My GitHub projects</a>
  </body>
</html>

1. Push it to main.
2. Open Settings, Pages. Under Build and deployment, choose Source: Deploy from a branch, branch main and folder / (root) (or /docs), and click Save.
3. After a minute, the page shows “Your site is live at https://<username>.github.io/portfolio/”.

Every push to the branch republishes the site.

---

⚙️ Option 2: Publish with GitHub Actions (Flexible)

Choose Source: GitHub Actions when your site needs a build step (React, Vue, Astro, a documentation generator) or when you want to publish generated files such as test reports. The workflow uses actions/upload-pages-artifact and actions/deploy-pages; a complete example is in Deploy with GitHub Actions.

- uses: actions/upload-pages-artifact@v3
  with:
    path: ./dist            # or ./playwright-report
- uses: actions/deploy-pages@v4

---

📝 Markdown Sites with Jekyll

When publishing from a branch, GitHub builds the site with Jekyll, so a README.md or index.md is turned into HTML automatically, and you can pick a theme in a _config.yml:

# _config.yml
title: QA Notes
description: My notes on Playwright and Git
theme: minima

If your site is plain HTML or uses folders that start with an underscore, add an empty .nojekyll file to skip Jekyll processing. Markdown basics are in Markdown and README.

---

🔗 Custom Domain

1. In Settings, Pages, Custom domain, enter e.g. qa.example.com and save (this creates a CNAME file when publishing from a branch).
2. At your DNS provider, add a CNAME record pointing qa to <username>.github.io (for an apex domain such as example.com, use the A records listed in GitHub’s documentation).
3. Wait for DNS to propagate, then tick Enforce HTTPS.

---

🧪 For Testers: Publish Test Reports

Publishing the Playwright HTML report to Pages after every run on main gives the team a permanent link to the latest results. Only do this for non-sensitive projects: anything on Pages is public. See Playwright in GitHub Actions and reporters.

---

🐞 Troubleshooting

Problem	Fix
404 after enabling Pages	Wait a few minutes; check there is an index.html (or index.md) in the selected folder
CSS or images missing on a project site	Use relative paths; project sites live under /<repo>/, not the domain root
Build fails with Jekyll errors	Check the Actions tab for the “pages build and deployment” run; add .nojekyll if you do not need Jekyll
Custom domain not working	Check DNS records and the CNAME setting; HTTPS can take time to be issued

---

📝 Assignment

1. Create a repository portfolio with an index.html and publish it from main.
2. Create your user site <username>.github.io with a short bio and links to your Playwright and Git projects.
3. Switch a site to GitHub Actions as the source and deploy with a workflow.
4. Publish a sample (non-sensitive) Playwright HTML report to Pages.
5. Bonus: connect a custom subdomain if you own a domain.

---

❓ FAQ

🤔 What is GitHub Pages?

A free GitHub service that hosts static websites directly from a repository, with HTTPS and optional custom domains.

🤔 How do I host a website on GitHub for free?

Push an index.html to a public repository, open Settings, Pages, choose Deploy from a branch (main, root) and save. The site appears at username.github.io/repository.

🤔 Can GitHub Pages run a backend or database?

No. It serves static files only. Use client-side JavaScript or external APIs for dynamic features.

🤔 How do I use a custom domain with GitHub Pages?

Add the domain in Settings, Pages, create a CNAME (or A records for apex domains) at your DNS provider, then enable Enforce HTTPS.

🤔 Can I publish test reports to GitHub Pages?

Yes, by uploading the report folder with upload-pages-artifact and deploy-pages in a workflow, as long as the report contains no sensitive data.

---

🎯 Next Steps

• ☁️ GitHub Codespaces: Cloud Development Environments
• 🤖 GitHub Copilot for Developers and Testers
• 📘 Git and GitHub Tutorial: full course