折腾 Zhēteng

Deploy Quartz site with Foam Repo Submodule to Github Pages

Created: Modified: 4 min read

Updates

Now I deploy to cloudflare and just use quartz as a builder.

[use-quartz-as-a-builder-of-foam-vault-deploy-to-cloudflare] (Don’t forget to delete the PATs)

Background

  • ‘#quartz’ repo: a public repo (so that we can use github page for free).
  • ‘#foam’ repo: a private repo holds the notes.

Create access token

We need access token of the foam repo so the Action Workflow of quartz repo can ‘checkout’ the foam repo as a git-submodule.

  • Creating a Fine-Grained Personal Access Token
    • Go to your GitHub account Settings.
    • Navigate to Developer settings > Personal access tokens > Fine-grained tokens.
    • Click “Generate new token”.
    • Token name: Give it a descriptive name (e.g., quartz-foam-submodule-action).
    • Expiration: Set an appropriate expiration date (GitHub enforces a maximum).
    • Description: (Optional) Add a description.
    • Resource owner: Select the user or organization that owns both the quartz-repo and the foam-vault-repo. If they are owned by your personal account, select your username.
    • Repository access:
      • Choose “Only select repositories”.
      • In the “Selected repositories” dropdown, search for and add your quartz-repo and your foam-vault-repo.
    • Permissions: This is the crucial part. For the actions/checkout action to clone these repositories and their submodule content, you need to grant permissions for each selected repository (quartz-repo and foam-vault-repo):
      • Under “Repository permissions,” find “Contents”.
      • Set it to “Read-only”. This allows the action to read the repository content, which is necessary for cloning and checking out submodules.
      • You generally do not need “Metadata (Read-only)” for actions/checkout to work, but some more complex Git operations might. “Contents (Read-only)” is usually sufficient for cloning.
      • You do not need write access for actions/checkout unless your workflow will also push changes. For just deploying your Quartz site, read-only is safer.
    • Click “Generate token”.
    • Copy the token immediately. You will not be able to see it again.
  • Add the Fine-Grained PAT as a Secret in Your quartz-repo
    • Go to your quartz-repo on GitHub.
    • Click on “Settings” > “Security” (in the sidebar) > “Secrets and variables” > “Actions”.
    • Under “Repository secrets,” click “New repository secret”.
    • Name: Give it a name, for example, ACCESS_TOKEN_FOR_NOTES.
    • Secret: Paste the fine-grained PAT you copied.
    • Click “Add secret”.

Deploy workflow to github-page

File: .github/workflows/deploy.yml

  • Reference
  • Added submodule update --init --recursive --remote step.
  • Note the use of token: ${{ secrets.ACCESS_TOKEN_FOR_NOTES }}
    • Also, you don’t need to specify ‘token’ again (also, you can’t) in the submodule step, because:

      • When you use actions/checkout@v4 with a token: ${{ secrets.YOUR_PAT }} (whether classic or fine-grained), the action does more than just check out files.

      • For HTTPS-based Git operations (which is typical if your submodule URL is https://github.com/…), actions/checkout configures the Git credential helper in the runner’s environment to use the provided token.

      • This means that subsequent raw git commands within the same job that access github.com over HTTPS (like git submodule update —remote) will automatically use the token that actions/checkout set up.

YAML:

name: Deploy Quartz site to GitHub Pages
 
on:
  push:
    branches:
      - main
 
permissions:
  contents: read
  pages: write
  id-token: write
 
concurrency:
  group: "pages"
  cancel-in-progress: false
 
jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4 # Or the latest version
        with:
          fetch-depth: 0
          token: ${{ secrets.ACCESS_TOKEN_FOR_NOTES }} # Or your classic PAT
          submodules: 'recursive' # This checks out the pinned version first
 
      - name: Update submodules to latest from their remote branch
        run: git submodule update --init --recursive --remote
 
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Dependencies
        run: npm ci
      - name: Build Quartz
        run: npx quartz build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: public
 
  deploy:
    needs: build
    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

Issue

  • ‘commit’ on the foam repo will not trigger the workflow to make a new deployment.
  • There is a bug for Quartz on Github page: [quartzgithub-page-tag-bug]

Graph View

Backlinks