GitHub Pages Deployment

Deploy your portfolio to GitHub Pages with automatic builds and deployments using GitHub Actions.

Overview

The portfolio is configured to deploy automatically to GitHub Pages when you push to the main branch. The deployment workflow builds the site and publishes it to https://juanroccia.github.io.

Prerequisites

Before deploying, ensure:

GitHub repository created

Create a repository named username.github.io (replace username with your GitHub username):

# Example for user 'juanroccia'
https://github.com/juanroccia/juanroccia.github.io

Site URL configured

Update astro.config.mjs with your GitHub Pages URL:

astro.config.mjs

import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://juanroccia.github.io'
})

Replace juanroccia with your GitHub username.

Workflow file present

Ensure .github/workflows/deploy.yml exists in your repository (already included).

GitHub Actions Workflow

The deployment is automated using this workflow:

.github/workflows/deploy.yml

name: Deploy to GitHub Pages

on:
  # Trigger on push to main branch
  push:
    branches: [ main ]
  # Allow manual workflow runs
  workflow_dispatch:

# Required permissions for GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Prevent concurrent deployments
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: npm
      
      - name: Setup Pages
        uses: actions/configure-pages@v4
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build with Astro
        run: npm run build
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Workflow Breakdown

Triggers

on:
  push:
    branches: [ main ]
  workflow_dispatch:

push: Automatically runs on every push to main
workflow_dispatch: Allows manual triggering from GitHub Actions tab

Permissions

permissions:
  contents: read      # Read repository files
  pages: write        # Deploy to GitHub Pages
  id-token: write     # OIDC token for verification

Build Job

Checkout code

- uses: actions/checkout@v4

Clones the repository to the runner

Setup Node.js

- uses: actions/setup-node@v4
  with:
    node-version: "20"
    cache: npm

Installs Node.js 20 with npm caching for faster builds

Configure Pages

- uses: actions/configure-pages@v4

Configures GitHub Pages settings

Install dependencies

- run: npm ci

Clean install from package-lock.json (faster and more reliable than npm install)

Build site

- run: npm run build

Builds the Astro site to ./dist/

Upload artifact

- uses: actions/upload-pages-artifact@v3
  with:
    path: ./dist

Uploads the built site for deployment

Deploy Job

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

Waits for build job to complete
Deploys the artifact to GitHub Pages
Provides deployment URL in workflow output

Initial Setup

Configure GitHub Pages in your repository:

Enable GitHub Pages

Go to repository Settings > Pages
Under Source, select GitHub Actions
Save the settings

Push workflow file

Commit and push .github/workflows/deploy.yml:

git add .github/workflows/deploy.yml
git commit -m "Add GitHub Pages deployment workflow"
git push origin main

Monitor deployment

Go to Actions tab in your repository
Watch the workflow run
Once complete, visit your site at https://username.github.io

Deployment Process

Every push to main triggers:

Checkout: Repository code is cloned
Install: Dependencies are installed with npm ci
Build: Site is built with npm run build
Deploy: Built files are deployed to GitHub Pages
Live: Site is available at your GitHub Pages URL

Custom Domain Setup

Use a custom domain instead of username.github.io:

Add CNAME file

Create public/CNAME with your domain:

public/CNAME

www.yourdomain.com

Or for apex domain:

public/CNAME

yourdomain.com

Update site URL

Update astro.config.mjs:

astro.config.mjs

export default defineConfig({
  site: 'https://www.yourdomain.com'
})

Configure DNS

Add DNS records with your domain provider:For www subdomain (recommended):

Type: CNAME
Name: www
Value: username.github.io

For apex domain:

Type: A
Name: @
Value: 185.199.108.153
Value: 185.199.109.153
Value: 185.199.110.153
Value: 185.199.111.153

Enable custom domain in GitHub

Go to repository Settings > Pages
Enter your custom domain
Wait for DNS check to complete
Enable Enforce HTTPS

DNS propagation can take up to 24 hours. Use DNS Checker to verify.

Manual Deployment

Trigger deployment manually:

Go to Actions tab
Click Deploy to GitHub Pages workflow
Click Run workflow
Select main branch
Click Run workflow button

Monitoring Deployments

Check deployment status:

Via GitHub Actions

Navigate to Actions tab
View workflow runs with status badges:
- ✅ Green: Successful
- ❌ Red: Failed
- 🟡 Yellow: In progress

Via Workflow Badge

Add to README.md:

[![Deploy](https://github.com/juanroccia/juanroccia.github.io/actions/workflows/deploy.yml/badge.svg)](https://github.com/juanroccia/juanroccia.github.io/actions/workflows/deploy.yml)

Via Deployments

Go to repository Settings > Environments
Click github-pages
View deployment history and URLs

Troubleshooting

Workflow fails at build step

Issue: Build errors during npm run buildSolution:

Run build locally: npm run build
Fix any content validation errors
Ensure all frontmatter is valid
Push fixes to main

Site shows 404

Issue: GitHub Pages returns 404 after deploymentSolution:

Verify site URL in astro.config.mjs matches GitHub Pages URL
Check repository name is username.github.io
Ensure GitHub Pages is enabled in repository settings
Wait a few minutes for deployment to propagate

Assets not loading

Issue: Images or CSS missing in productionSolution:

Ensure assets are in public/ directory
Use absolute paths: /assets/image.jpg, not assets/image.jpg
Check img paths in frontmatter
Clear browser cache

Custom domain not working

Issue: Custom domain shows error or redirects incorrectlySolution:

Verify DNS records are correct
Wait 24h for DNS propagation
Check public/CNAME file exists and is correct
Ensure site URL in config matches custom domain
Verify custom domain in GitHub Pages settings

Workflow permission denied

Issue: Error: Resource not accessible by integrationSolution:

Go to Settings > Actions > General
Under Workflow permissions, select Read and write permissions
Enable Allow GitHub Actions to create and approve pull requests
Save and re-run workflow

Deployment Checklist

Before deploying:

site URL in astro.config.mjs is correct

.github/workflows/deploy.yml exists

GitHub Pages is enabled in repository settings

GitHub Pages source is set to GitHub Actions

Workflow permissions are configured

Build succeeds locally with npm run build

All content validates with npm run astro check

Next Steps

Building - Understand the build process
Configuration - Customize site settings
GitHub Pages Documentation - Official GitHub Pages docs

Setup

Content

Deployment

Overview

Prerequisites

GitHub Actions Workflow

Workflow Breakdown

Triggers

Permissions

Build Job

Deploy Job

Initial Setup

Deployment Process

Custom Domain Setup

Manual Deployment

Monitoring Deployments

Via GitHub Actions

Via Workflow Badge

Via Deployments

Troubleshooting

Deployment Checklist

Next Steps

Build docs developers (and LLMs) love

Setup

Content

Deployment

​Overview

​Prerequisites

​GitHub Actions Workflow

​Workflow Breakdown

​Triggers

​Permissions

​Build Job

​Deploy Job

​Initial Setup

​Deployment Process

​Custom Domain Setup

​Manual Deployment

​Monitoring Deployments

​Via GitHub Actions

​Via Workflow Badge

​Via Deployments

​Troubleshooting

​Deployment Checklist

​Next Steps

Build docs developers (and LLMs) love

Overview

Prerequisites

GitHub Actions Workflow

Workflow Breakdown

Triggers

Permissions

Build Job

Deploy Job

Initial Setup

Deployment Process

Custom Domain Setup

Manual Deployment

Monitoring Deployments

Via GitHub Actions

Via Workflow Badge

Via Deployments

Troubleshooting

Deployment Checklist

Next Steps