DEV Community

John Ajera
John Ajera

Posted on

Setting Up GitHub Pages with GitHub Actions

#github #pages #actions #deployment

Setting Up GitHub Pages with GitHub Actions

This article demonstrates how to create a GitHub repository with GitHub Pages enabled, from a basic hello world example to automated deployment using GitHub Actions. We'll cover manual setup steps and show how to automate the deployment process.

High-Level Steps

Setting up GitHub Pages involves:

  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
  2. Select "New repository"
  3. Configure the repository:
    • Repository name: github-pages-demo (or your preferred name)
    • Description: "A simple hello world site on GitHub Pages"
    • Visibility: Public (required for free GitHub Pages)
    • Initialize with README: ✅ (checked)
  4. Click "Create repository"

Key points:

  • Repository name will be part of your site URL: https://username.github.io/repository-name
  • Public repositories get free GitHub Pages hosting
  • Private repositories require GitHub Pro or higher for Pages

Step 2: Clone Repository Locally

Clone your repository to your local machine:

git clone https://github.com/your-username/github-pages-demo.git
cd github-pages-demo
Enter fullscreen mode Exit fullscreen mode

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">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <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>
Enter fullscreen mode Exit fullscreen mode

What this creates:

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

Alternative: You can create any static HTML content, CSS files, JavaScript files, or other static assets in your repository.

Step 4: Create GitHub Actions Workflow

Create the workflow directory and file:

mkdir -p .github/workflows
Enter fullscreen mode Exit fullscreen mode

Create .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
Enter fullscreen mode Exit fullscreen mode

Workflow explanation:

  • Triggers: Runs on push to main branch or manual trigger
  • Permissions: Required permissions for Pages deployment
  • Concurrency: Prevents multiple deployments from running simultaneously
  • Steps:
    1. Checkout repository code
    2. Configure Pages settings
    3. Upload all files as artifact
    4. Deploy 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 needed for simple HTML (add build steps if using frameworks)
  • Artifact path '.' uploads the entire repository root

Step 5: Enable GitHub Pages

Important: You must enable GitHub Pages and select "GitHub Actions" as the source before pushing your code. If you push the workflow file first, the workflow will not run because the github-pages environment doesn't exist yet. Enabling Pages first creates the necessary environment for the workflow to execute successfully.

Step 5.1: Navigate to Settings

  1. Go to your repository on GitHub
  2. Click on "Settings" in the top navigation bar
  3. Scroll down to "Pages" in the left sidebar

Step 5.2: Configure Source

  1. Under "Build and deployment", find "Source"
  2. Select "GitHub Actions"
  3. The selection is automatically saved

What this does:

  • Enables GitHub Pages for your repository
  • Configures Pages to use GitHub Actions for deployment
  • Creates the github-pages environment needed for the workflow
  • The workflow will handle all deployments automatically

Step 6: Commit and Push

Commit both files and push to GitHub:

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

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

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

Key points:

  • The main branch (or master) 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

Step 7.1: Wait for Deployment

  • GitHub Actions will detect the workflow file and run automatically
  • GitHub will build and deploy your site
  • This may take a few minutes
  • You'll see a green checkmark when deployment is complete
  • Check the Actions tab to monitor the workflow progress

Step 7.2: Access Your Site

Your site will be available at:

https://your-username.github.io/github-pages-demo
Enter fullscreen mode Exit fullscreen mode

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

Step 7.3: Add Website to Repository About Section (Optional)

To make your GitHub Pages site more accessible and visible to visitors, you can add the website URL to your repository's About section:

  1. On your repository page, click the gear icon (⚙️) next to the "About" section
  2. In the "Edit repository details" modal, find the "Website" field
  3. Enter your GitHub Pages URL: https://your-username.github.io/github-pages-demo
  4. Check the box "Use your GitHub Pages website" (this will automatically populate the URL)
  5. Click "Save changes"

What this does:

  • Makes your site URL visible in the repository's About section
  • Provides a direct link for visitors to access your site
  • Improves discoverability and accessibility of your GitHub Pages site

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

Complete Example

Here's a complete repository structure:

github-pages-demo/
├── .github/
│   └── workflows/
│       └── pages.yml
├── index.html
└── README.md
Enter fullscreen mode Exit fullscreen mode

index.html (as shown in Step 3)

pages.yml (as shown in Step 6)

Repository Structure Summary

After setup, you'll have:

File/Folder Purpose
.github/workflows/pages.yml GitHub Actions deployment workflow
index.html Main page content
README.md Repository documentation

Important Notes

GitHub Pages Limitations

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

Custom Domain Support

Branch and Folder Options

Source options:

  • Deploy from a branch: Serves files directly from a branch
  • GitHub Actions: Uses workflow to build and deploy (recommended)

Folder options:

  • / (root): Serves files from repository root
  • /docs: Serves files from docs folder
  • Custom folder: Any folder in your repository

Security Considerations

  • Public repositories: Content is publicly accessible
  • Private repositories: Requires GitHub Pro for Pages
  • Secrets: Don't commit API keys or sensitive data
  • HTTPS: Automatically enabled for all Pages sites

Troubleshooting

Site Not Loading

Issue: Site returns 404 or doesn't load

  1. Check deployment status: Go to repository → Actions tab
  2. Verify workflow ran: Ensure the workflow completed successfully
  3. Check Pages settings: Verify "GitHub Actions" is selected as source
  4. Wait a few minutes: Initial deployment can take 5-10 minutes
  5. Clear browser cache: Try incognito mode or different browser

Solution:

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

# Verify file content is correct
cat .github/workflows/pages.yml
Enter fullscreen mode Exit fullscreen mode

Workflow Fails

Issue: GitHub Actions workflow fails to deploy

  1. Check Actions tab: Review error messages in workflow logs
  2. Verify permissions: Ensure Pages permissions are enabled
  3. Check file paths: Ensure artifact path matches your content location
  4. Review workflow syntax: Validate YAML syntax

Common errors:

  • Missing permissions: Add pages: write and id-token: write
  • Wrong artifact path: Use '.' for root or correct folder path
  • Branch name mismatch: Ensure workflow triggers on correct branch

Custom Domain Issues

Issue: Custom domain not working

  1. Verify CNAME file: Must contain only the domain name
  2. Check DNS records: Ensure A/CNAME records are correct
  3. Wait for propagation: DNS changes can take up to 48 hours
  4. Check GitHub settings: Domain must be added in Pages settings

Verification

After deployment, verify your site:

  1. Visit your site URL: https://your-username.github.io/github-pages-demo
  2. Check Actions tab: Verify workflow completed successfully
  3. Test updates: Make a change, push to main, verify it appears on site

Working example: See a live example at https://jdevto.github.io/github-pages-demo/

Verify deployment:

# Check if site is accessible
curl -I https://your-username.github.io/github-pages-demo

# Should return HTTP 200 status

# Example with working site:
curl -I https://jdevto.github.io/github-pages-demo/
Enter fullscreen mode Exit fullscreen mode

Next Steps

Once your basic site is working, you can:

  • Add more pages: Create additional HTML files
  • Add CSS styling: Create a styles.css file
  • Add JavaScript: Create interactive features
  • Use a static site generator: Jekyll, Hugo, MkDocs, etc.
  • Add a custom domain: Point your own domain to GitHub Pages
  • Set up CI/CD: Add tests and build steps to your workflow

Conclusion

Setting up GitHub Pages with GitHub Actions provides a simple, automated way to host static websites. By following these steps, you can:

  • Create a basic hello world site
  • Enable GitHub Pages manually or via Actions
  • Automate deployments with GitHub Actions
  • Extend your site with additional content

The combination of GitHub Pages and GitHub Actions makes it easy to deploy and maintain static websites with minimal configuration.

References

Top comments (0)