software

Setting Up GitHub Pages with GitHub Actions

Published: (December 31, 2025 at 05:11 PM EST)
7 min read
Source: Dev.to

Source: Dev.to

High‑Level Steps

  1. Create GitHub Repository – Create a new repository on GitHub.
  2. Create Hello World Content – Add basic HTML content to serve.
  3. Enable GitHub Pages – Configure Pages in repository settings.
  4. Set Up GitHub Actions – Automate deployment with a workflow.
  5. Verify Deployment – Confirm your site is live.

Prerequisites

  • GitHub account
  • Git installed locally
  • Basic knowledge of HTML
  • Text editor or IDE

Use Case: Simple Hello World Site

We’ll create a basic static website that displays “Hello World” and can be extended with additional content. This approach works for any static HTML site, documentation, or simple web applications.

Step‑by‑Step Implementation

Step 1: Create GitHub Repository

  1. Navigate to GitHub and click the “+” icon in the top‑right corner.
  2. Select “New repository.”

Configure the repository:

SettingValue
Repository namegithub-pages-demo (or your preferred name)
Description“A simple hello world site on GitHub Pages”
VisibilityPublic (required for free GitHub Pages)
Initialize with README✅ (checked)

Click “Create repository.”

Key points

  • Repository name becomes part of your site URL: https://<username>.github.io/
  • Public repositories get free GitHub Pages hosting.
  • Private repositories require GitHub Pro (or higher) for Pages.

Step 2: Clone Repository Locally

git clone https://github.com/your-username/github-pages-demo.git
cd github-pages-demo

Replace your-username with your actual GitHub username.

Step 3: Create Hello World Content

Create a basic index.html file in the repository root:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Hello World - GitHub Pages</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
      display: flex;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      margin: 0;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      color: white;
    }
    .container {
      text-align: center;
      padding: 2rem;
    }
    h1 {
      font-size: 3rem;
      margin-bottom: 1rem;
    }
    p {
      font-size: 1.2rem;
      opacity: 0.9;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>Hello World!</h1>
    <p>Welcome to my GitHub Pages site</p>
  </div>
</body>
</html>

What this creates

  • A simple HTML page with a “Hello World” message.
  • Basic styling for a clean appearance.
  • Responsive design that works on mobile devices.

Alternative: Add any static HTML, CSS, JavaScript, or other assets you need.

Step 4: Create GitHub Actions Workflow

  1. Create the workflow directory:

    mkdir -p .github/workflows

  2. Add the workflow file .github/workflows/pages.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: '.'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Workflow explanation

  • Triggers – Runs on pushes to main or when manually triggered.
  • Permissions – Required for Pages deployment.
  • Concurrency – Prevents multiple deployments from overlapping.
  • Steps
    1. Checkout repository code.
    2. Configure Pages settings.
    3. Upload all repository files as an artifact.
    4. Deploy the artifact to GitHub Pages.

Key points

  • The workflow automatically deploys when you push to main.
  • Uses the official GitHub Actions for Pages (actions/deploy-pages@v4).
  • No build step is needed for simple HTML (add build steps if using a framework).
  • path: '.' uploads the entire repository root.

Step 5: Enable GitHub Pages

Important: Enable GitHub Pages before pushing the workflow file. If the workflow runs first, the github-pages environment won’t exist, causing the job to fail.

Step 5.1: Navigate to Settings

  1. Go to your repository on GitHub.
  2. Click “Settings” in the top navigation bar.
  3. In the left sidebar, select “Pages.”

Step 5.2: Configure Source

Under “Build and deployment,” locate “Source.”

  • Choose “GitHub Actions.”
  • The selection is saved automatically.

What this does

  • Enables GitHub Pages for the repository.
  • Configures Pages to use the GitHub Actions workflow for deployment.
  • Creates the github-pages environment required by the workflow.

Verify Deployment

  1. Commit and push your changes (including index.html and the workflow file) to the main branch:

    git add .
git commit -m "Add site content and Pages workflow"
git push origin main

  2. Navigate to the Actions tab to watch the workflow run.

  3. Once the workflow completes, go to Settings → Pages to find the live site URL (e.g., https://<username>.github.io/github-pages-demo).

  4. Open the URL in a browser – you should see the “Hello World!” page.

Recap

  • Created a public repository.
  • Added a simple static site (index.html).
  • Set up a GitHub Actions workflow to deploy the site automatically.
  • Enabled GitHub Pages with GitHub Actions as the source.
  • Verified that the site is live.

You now have a fully automated GitHub Pages site that updates on every push to main. Feel free to expand the site with additional pages, assets, or a static site generator—just adjust the workflow accordingly.

Step 6: Commit and Push

git add index.html .github/workflows/pages.yml
git commit -m "feat: add hello world page and GitHub Pages workflow"
git push origin main

Note: We’re pushing directly to main for simplicity in this tutorial. In a production environment, best practice is to:

  1. Create a branch (e.g., git checkout -b feature/add-pages-setup)
  2. Create a pull request for review
  3. Merge after approval

Key points

  • The main (or master) branch is typically used for GitHub Pages.
  • All files in the repository root or a specific branch/folder can be served.
  • GitHub Pages serves static files only (HTML, CSS, JavaScript, images, etc.).
  • The workflow will trigger automatically on push.

Step 7: Wait for Deployment and Access Your Site

7.1 Wait for Deployment

  • GitHub Actions detects the workflow file and runs automatically.
  • GitHub builds and deploys your site (may take a few minutes).
  • A green check‑mark indicates the deployment is complete.
  • Monitor progress in the Actions tab.

7.2 Access Your Site

Your site will be available at:

https://your-username.github.io/github-pages-demo

Replace your-username and github-pages-demo with your actual values.

7.3 Add Website to Repository About Section (Optional)

  1. On the repository page, click the gear icon (⚙️) next to the About section.
  2. In the Edit repository details modal, locate the Website field.
  3. Enter your GitHub Pages URL (e.g., https://your-username.github.io/github-pages-demo).
  4. Check “Use your GitHub Pages website” – this auto‑populates the URL.
  5. Click Save changes.

What this does

  • Shows the site URL in the repository’s About section.
  • Provides a direct link for visitors.
  • Improves discoverability of your GitHub Pages site.

Note: Future pushes to main will automatically trigger the workflow and deploy updates.

Complete Example

Repository structure

github-pages-demo/
├── .github/
│   └── workflows/
│       └── pages.yml
├── index.html
└── README.md
  • index.html – as shown in Step 3.
  • pages.yml – as shown in Step 4.

Repository Structure Summary

File / FolderPurpose
.github/workflows/pages.ymlGitHub Actions deployment workflow
index.htmlMain page content
README.mdRepository documentation

Important Notes

GitHub Pages Limitations

  • Static content only – no server‑side processing (PHP, Python, etc.).
  • File size limits – 1 GB repository size, 100 MB per file.
  • Bandwidth – 100 GB per month for free accounts.
  • Build time – 10 builds per hour limit.

Custom Domain Support

  • Add a CNAME file containing your domain name.
  • Configure DNS records to point to GitHub.
  • See the official GitHub Pages documentation for details.

For a walkthrough using AWS Route 53, see Setting Up Custom Domain for GitHub Pages with Route53.

Branch and Folder Options

Source optionDescription
Deploy from a branchServes files directly from a branch.
GitHub ActionsUses a workflow to build and deploy (recommended).
Folder optionDescription
/ (root)Serves files from the repository root.
/docsServes files from a docs folder.
customAny folder you specify in the settings.

Security Considerations

  • Public repositories – content is publicly accessible.
  • Private repositories – requires a GitHub Pro plan for Pages.
  • Secrets – never commit API keys or other sensitive data.
  • HTTPS – automatically enabled for all Pages sites.

Troubleshooting

Site Not Loading

Symptoms: 404 error or site does not load.

Steps to resolve

  1. Check deployment status – go to Repository → Actions tab.
  2. Verify workflow ran – ensure it completed successfully.
  3. Check Pages settings – confirm “GitHub Actions” is selected as the source.
  4. Wait a few minutes – initial deployment can take 5‑10 minutes.
  5. Clear browser cache – try incognito mode or a different browser.

Useful commands

# Verify workflow file exists
ls -la .github/workflows/pages.yml

# View its contents
cat .github/workflows/pages.yml

Workflow Fails

Symptoms: GitHub Actions workflow errors.

Resolution checklist

  • Review error messages in the Actions tab logs.
  • Ensure Pages permissions are enabled (pages: write, id-token: write).
  • Verify artifact paths match your content location ('.' for root, or correct folder).
  • Confirm the workflow triggers on the correct branch.
  • Validate YAML syntax (use an online linter if needed).

Common errors

  • Missing permissions: add pages: write and id-token: write.
  • Wrong artifact path: adjust to '.' or the appropriate folder.
  • Branch name mismatch: ensure the on: trigger matches your branch.

Custom Domain Issues

Symptoms: Custom domain not working.

Resolution steps

  1. Check CNAME file – it must contain only the domain name (no extra whitespace).
  2. Verify DNS records – A/CNAME records should point to GitHub’s servers.
  3. Allow propagation – DNS changes can take up to 48 hours.
  4. Confirm GitHub settings – the domain must be added under Pages settings.

Verification

After deployment, verify your site:

  • Visit the site URL.
  • Ensure the “Hello World!” content displays correctly.
  • Check the Actions tab for a successful run.
Back to Blog

Related posts

Read more »

AI SEO agencies Nordic

!Cover image for AI SEO agencies Nordichttps://media2.dev.to/dynamic/image/width=1000,height=420,fit=cover,gravity=auto,format=auto/https%3A%2F%2Fdev-to-uploads...