Deploying your Blog to GitHub Pages

There are many ways to publish a blog online. One of the simplest options is GitHub Pages, which lets you host your site without needing a custom domain or separate hosting provider.

When it comes to frameworks, the choices are equally plentiful. For this blog, I chose Astro because it’s modern, lightweight, and works seamlessly with GitHub Pages.

In this tutorial, you’ll start with a fresh Astro project on your machine and end with a fully deployed blog hosted at yourusername.github.io.

We’ll use:

Astro for the site
GitHub Actions for the build & deploy
GitHub Pages for hosting

1. Create a new Astro project

If you don’t have an Astro project yet, create one:

npm create astro@latest blog
cd blog
npm install && npm run dev

Open http://localhost:4321 to make sure your blog works locally.

2. Initialize a Git repository

git init
git commit -am "Initial Astro blog"
git branch -M main
git remote add origin git@github.com:yourusername/blog.git
git push -u origin main

3. Configure site and base in astro.config.mjs

export default defineConfig({
  site: "https://yourusername.github.io/blog/",
});

4. Add GitHub Actions workflow

Create .github/workflows/deploy.yml and push it to main:

name: Deploy Astro site 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:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

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

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

5. Enable GitHub Pages

Settings → Pages
Set Source: GitHub Actions

Your site will deploy to:

https://yourusername.github.io/blog/

6. Updating your blog

Commit new posts, push to main.
GitHub Actions rebuilds and deploys automatically.