The Straightforward Way I Launch One Apps On GitHub Pages

Why GitHub Pages Fits One Projects So Well Preparing The Repository For Pages My GitHub Actions Workflow That Does The Heavy Lifting Breaking Down The Workflow Step By Step Pointing A Custom Domain For A Polished Presence Final Checklist Before I Hit Merge

Let’s acknowledge the elephant in the room: the internet already groans under the weight of “How I deployed my blog” tutorials. Yet here you are, reading another one, and here I am writing it. The difference? This post documents the precise steps that run this blog—yes, the very page you are scrolling—on GitHub Pages with One. It takes one workflow file, a sprinkle of DNS, and a grand total of zero servers. Tongue firmly in cheek, but the instructions are dead serious.

Why GitHub Pages Fits One Projects So Well

GitHub Pages is a free, globally distributed CDN that loves static files. One compiles to static assets out of the box, so the pairing is almost too perfect. Public repositories cost nothing, private repos only need GitHub Pro, and the deploy pipeline is a single YAML file. No servers to patch, no SSL certificates to renew, no invoices to forget to pay.

Preparing The Repository For Pages

Push your One code to GitHub.
Open Settings → Pages.
Pick the branch you want to publish from—main is my standard—and leave the folder as / if you follow the workflow below.
Save. GitHub gives you a temporary github.io URL instantly.

That’s all the UI work done. Everything else lives in code where it belongs.

My GitHub Actions Workflow That Does The Heavy Lifting

Create .github/workflows/deploy.yml in the repo root and drop in this workflow:

name: Deploy to jshez.com

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Enable Corepack
        run: corepack enable

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'yarn'

      - name: Install latest Yarn
        run: corepack prepare yarn@stable --activate

      - name: Install dependencies
        run: yarn install --immutable

      - name: Build
        run: yarn build:web
        env:
          ONE_SERVER_URL: ${{ vars.ONE_SERVER_URL }}

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

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

Commit, push, and watch the Actions tab light up. When the green checkmark appears, your site is live.

Breaking Down The Workflow Step By Step

Checkout grabs the latest commit so the runner has your source.
Enable Corepack ensures Node’s package-manager shim is available.
Setup Node.js guarantees the correct runtime (I lock to 20 for now) and caches node_modules between runs.
Install latest Yarn keeps Yarn up to date without polluting global installs.
Install dependencies is the familiar yarn install --immutable, a belt-and-braces check that your lockfile is honest.
Build triggers yarn build:web, compiling the One project into pure static assets inside dist/client.
Upload Pages artifact hands those files to GitHub’s Pages system.
Deploy to GitHub Pages publishes the artifact and spits out the final URL.

Nothing fancy, nothing brittle, just a clean twelve-step chain that works every single push.

Pointing A Custom Domain For A Polished Presence

I own jshez.com, so I want my app living there, not under github.io. The process is two minutes of DNS work and one extra file in the repo root.

A records for the apex domain:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

CNAME for www (or any subdomain):

www    CNAME    <your-github-username>.github.io

Inside the repository, add a plain-text file named CNAME containing your domain:

jshez.com

Commit and push. GitHub Pages sees the file, provisions SSL automatically, and your custom domain lights up once DNS propagates (usually under an hour, occasionally a lazy afternoon).

Final Checklist Before I Hit Merge

yarn build:web succeeds locally.
.github/workflows/deploy.yml exists on main.
ONE_SERVER_URL is set in Repository → Settings → Variables if the app calls an API.
CNAME file is present if I’m using a custom domain.
DNS records are correct at the registrar.

When that list is green, I merge. Pages publishes in under a minute and this blog quietly updates itself while I make coffee.