Building and deploying a custom site using GitHub Actions and GitHub Pages#

I figured out a minimal pattern for building a completely custom website using GitHub Actions and deploying the result to GitHub Pages.

First you need to enable GitHub Pages for the repository. Navigate to Settings -> Pages (or visit $repo/settings/pages) and set the build source to “GitHub Actions”.

Here’s my minimal YAML recipe - save this in a .github/workflows/publish.yml file:

1
name: Publish site
2

3
on:
4
  push:
5
  workflow_dispatch:
6

7
permissions:
8
  contents: read
9
  pages: write
10
  id-token: write
11

12
jobs:
13
  build:
14
    runs-on: ubuntu-latest
15
    steps:
16
    - uses: actions/checkout@v4
17
    - name: Build the site
18
      run: |
19
        mkdir _site
20
        echo '<h1>Hello, world!</h1>' > _site/index.html
21
    - name: Upload artifact
22
      uses: actions/upload-pages-artifact@v3
23
  deploy:
24
    environment:
25
      name: github-pages
26
      url: ${{ steps.deployment.outputs.page_url }}
27
    runs-on: ubuntu-latest
28
    needs: build
29
    steps:
30
      - name: Deploy to GitHub Pages
31
        id: deployment
32
        uses: actions/deploy-pages@v4

Anything that goes in that _site/ directory will be published to the GitHub Pages site.

The permissions are required:

• contents: read allows the actions/checkout action to check out the repo
• pages: write enables writes to pages
• id-token: write one is needed by the actions/deploy-pages action for some reason

The default URL for the site will be https://$GITHUB_USERNAME.github.io/$REPO_NAME/. You can set this to custom domain if you want.

github.com/simonw/minimal-github-pages-from-actions is an example repository that uses this exact YAML configuration. It publishes a site to https://simonw.github.io/minimal-github-pages-from-actions/.