Deploying to GitHub Pages

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Docusaurus provides an easy way to publish to GitHub Pages, which comes free with every GitHub repository.

Usually, there are two repositories (at least two branches) involved in a publishing process: the branch containing the source files, and the branch containing the build output to be served with GitHub Pages. In the following tutorial, they will be referred to as "source" and "deployment", respectively.

Each GitHub repository is associated with a GitHub Pages service. If the deployment repository is called my-org/my-project (where my-org is the organization name or username), the deployed site will appear at https://my-org.github.io/my-project/. If the deployment repository is called my-org/my-org.github.io (the organization GitHub Pages repo), the site will appear at https://my-org.github.io/.

GitHub Pages picks up deploy-ready files (the output from docusaurus build) from the default branch (master / main, usually) or the gh-pages branch, and either from the root or the /docs folder. You can configure that through Settings > Pages in your repository. This branch will be called the "deployment branch".

We provide a docusaurus deploy command that helps you deploy your site from the source branch to the deployment branch in one command: clone, build, and commit.

First, modify your docusaurus.config.js and add the following params:

These fields also have their environment variable counterparts which have a higher priority: ORGANIZATION_NAME, PROJECT_NAME, and DEPLOYMENT_BRANCH.

Example:

export default {  // ...  url: 'https://endiliey.github.io', // Your website URL  baseUrl: '/',  projectName: 'endiliey.github.io',  organizationName: 'endiliey',  trailingSlash: false,  // ...};

GitHub enterprise installations should work in the same manner as github.com; you only need to set the organization's GitHub Enterprise host as an environment variable:

Finally, to deploy your site to GitHub Pages, run:

<Tabs>
<TabItem value="bash" label="Bash">

GIT_USER=<GITHUB_USERNAME> yarn deploy

</TabItem>
<TabItem value="windows" label="Windows">

cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"

</TabItem>
<TabItem value="powershell" label="PowerShell">

cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'

</TabItem>
</Tabs>

GitHub Actions allow you to automate, customize, and execute your software development workflows right in your repository.

The workflow examples below assume your website source resides in the main branch of your repository (the source branch is main), and your publishing source is configured for publishing with a custom GitHub Actions Workflow.

Our goal is that:

1. When a new pull request is made to main, there's an action that ensures the site builds successfully, without actually deploying. This job will be called test-deploy.
2. When a pull request is merged to the main branch or someone pushes to the main branch directly, it will be built and deployed to GitHub Pages. This job will be called deploy.

Here are two approaches to deploying your docs with GitHub Actions. Based on the location of your deployment repository, choose the relevant tab below:

• Source repo and deployment repo are the same repository.
• The deployment repo is a remote repository, different from the source. Instructions for this scenario assume publishing source is the gh-pages branch.

<Tabs>
<TabItem value="same" label="Same">

While you can have both jobs defined in the same workflow file, the original deploy workflow will always be listed as skipped in the PR check suite status, which is not indicative of the actual status and provides no value to the review process. We therefore propose to manage them as separate workflows instead.

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main
    # Review gh actions docs if you want to further define triggers, paths, etc
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  build:
    name: Build Docusaurus
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm

      - name: Install dependencies
        run: npm ci
      - name: Build website
        run: npm run build

      - name: Upload Build Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: build

  deploy:
    name: Deploy to GitHub Pages
    needs: build

    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write # to deploy to Pages
      id-token: write # to verify the deployment originates from an appropriate source

    # Deploy to the github-pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

name: Test deployment

on:
  pull_request:
    branches:
      - main
    # Review gh actions docs if you want to further define triggers, paths, etc
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  test-deploy:
    name: Test deployment
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm

      - name: Install dependencies
        run: npm ci
      - name: Test build website
        run: npm run build

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main
    # Review gh actions docs if you want to further define triggers, paths, etc
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  build:
    name: Build Docusaurus
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: yarn

      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Build website
        run: yarn build

      - name: Upload Build Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: build

  deploy:
    name: Deploy to GitHub Pages
    needs: build

    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write # to deploy to Pages
      id-token: write # to verify the deployment originates from an appropriate source

    # Deploy to the github-pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

name: Test deployment

on:
  pull_request:
    branches:
      - main
    # Review gh actions docs if you want to further define triggers, paths, etc
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  test-deploy:
    name: Test deployment
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: yarn

      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Test build website
        run: yarn build

</TabItem>
<TabItem value="remote" label="Remote">

A cross-repo publish is more difficult to set up because you need to push to another repo with permission checks. We will be using SSH to do the authentication.

1. Generate a new SSH key. Since this SSH key will be used in CI, make sure to not enter any passphrase.
2. By default, your public key should have been created in ~/.ssh/id_rsa.pub; otherwise, use the name you've provided in the previous step to add your key to GitHub deploy keys.
3. Copy the key to clipboard with pbcopy < ~/.ssh/id_rsa.pub and paste it as a deploy key in the deployment repository. Copy the file content if the command line doesn't work for you. Check the box for Allow write access before saving your deployment key.
4. You'll need your private key as a GitHub secret to allow Docusaurus to run the deployment for you.
5. Copy your private key with pbcopy < ~/.ssh/id_rsa and paste a GitHub secret with the name GH_PAGES_DEPLOY on your source repository. Copy the file content if the command line doesn't work for you. Save your secret.
6. Create your documentation workflow in the .github/workflows/ directory. In this example it's the deploy.yml file.

At this point, you should have:

• the source repo with the GitHub workflow set with the private SSH key as the GitHub Secret, and
• your deployment repo set with the public SSH key in GitHub Deploy Keys.

name: Deploy to GitHub Pages

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  test-deploy:
    if: github.event_name != 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: yarn
      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Test build website
        run: yarn build
  deploy:
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: yarn
      - uses: webfactory/ssh-agent@v0.5.0
        with:
          ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}
      - name: Deploy to GitHub Pages
        env:
          USE_SSH: true
        run: |
          git config --global user.email "actions@github.com"
          git config --global user.name "gh-actions"
          yarn install --frozen-lockfile
          yarn deploy

</TabItem>
</Tabs>