Deploying Your Portfolio for Free on GitHub Pages

Deployment means making your website accessible on the internet so others can visit it. Until now, your Hugo site has only existed on your local computer. GitHub Pages provides free hosting for static websites, making it an ideal platform for Hugo sites.

Here you will be deploying your Hugo portfolio to GitHub Pages using GitHub Actions for automated builds. You will see your site live on the internet, understand how the deployment process works, and practice continuous deployment where changes automatically go live.

Here we will see:

• how to prepare your site for deployment using Git and GitHub
• how to deploy your Hugo site to GitHub Pages using the official Hugo workflow
• how GitHub Actions automates building and deploying your site
• how to practice continuous deployment by making changes that automatically go live

Setup

Navigate to your Hugo site directory and initialize Git.

cd my-portfolio
git init

Create a GitHub repository

Go to GitHub in your browser (https://github.com) and log in to your account. In the top right corner, click the “+” icon and select “New repository” from the dropdown menu. Name your repository my-portfolio, keep it public, and do not check any boxes to initialize with a README, .gitignore, or license. Click “Create repository”. NOTE: This should be the hugo site that you created. Not the parent directory

After creating the repository, GitHub shows a page with setup instructions. You will see a URL that looks like https://github.com/username/my-portfolio.git where username is your GitHub username.

Pushing Your Site to GitHub

git add .
git commit -m "Initial Hugo site"
git remote add origin https://github.com/YOUR-USERNAME/my-portfolio.git
git push -u origin main

Section 1: Deploying to GitHub Pages

Before your site is live on the website, there are three main steps to take

• Setting up GitHub Pages
• Creating hugo workflow
• Checking build and deploy processes on GitHub Actions

Exercises: Setting up GitHub Pages

• Go to your repository on GitHub
• Go to Settings and Pages
• Change Source in Build and deployment to GitHub Actions

Exercise: Creating Hugo workflow

• Create .github/workflows/hugo.yaml file in your local repo
• Go to https://gohugo.io/host-and-deploy/host-on-github-pages/
• Copy and paste the entire content into .github/workflows/hugo.yaml file
• Commit and push to the repo

Exercise: Checking Build and deploy process

• Go to Actions tab in your GitHub repository
• You should see two jobs: build and deploy
• Here you can check the progress of the build and deploy processes
• You can check the deployed site in the link which will be shown below deploy

Section 2: Modifying the Workflow

Background

Your site is now deployed and accessible on the internet. The GitHub Actions workflow handles the entire build and deployment process automatically. Now you will understand what the workflow does by making changes to it and observing the results.

Exercises

This section focuses on modifying the workflow file, seeing how those modifications affect the build process in the logs, and verifying the site still works. Each exercise follows a complete cycle: modify the workflow → commit and push → watch the workflow run → examine the logs → verify the live site.

Example Let’s modify Hugo version to something that doesn’t exist. Change HUGO_VERSION to 0.0.0, push the changes and then see what happens in the build process.

HUGO_VERSION: 0.154.4

Exercise: Change the Hugo version back to 0.154.4

HUGO_VERSION: 0.154.4

Exercise: Let’s remove the whole worflow and write our own. Start with this skeleton

name: Build and Deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

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

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
      
      # YOUR STEPS WILL BE HERE IN THE NEXT EXERCISES
  
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4

We will follow the following pattern

- name: Name of the job
  run: |
    command 1
    command 2

Exercise: Add Install Pixi step which downloads, installs, and adds Pixi to path

- name: Install Pixi
  run: |
    curl -fsSL https://pixi.sh/install.sh | sh
    echo "$HOME/.pixi/bin" >> $GITHUB_PATH

Exercise: Add Install Hugo step which initializes Pixi environment and adds hugo

- name: Install HUgo
  run: |
    pixi init
    pixi add hugo

(Demo) Exercise: Add build step

    - name: Setup Pages
      id: pages
      uses: actions/configure-pages@v5

    - name: Build site
      run: |
        pixi run hugo \
        --gc \
        --minify \
        --baseURL "${{ steps.pages.outputs.base_url }}/"

Section 3: Practicing Continuous Deployment

Background

Continuous Deployment (CD) means your changes automatically go live on the internet without manual intervention. Every time you push to GitHub, your workflow rebuilds the site and deploys the updates.

Exercises

This section focuses on practicing this workflow repeatedly to build muscle memory.

You will make various a few changes to your content following the same pattern each time: edit files locally, stage changes, commit with a descriptive message, push to GitHub, watch the workflow run, and verify on the live site.

Exercise: Add a new paragraph to your homepage

Exercise: Remove the paragraph you added

Exercise: Modify some configuration in hugo.toml