Fixing: Artifact could not be deployed. Please ensure the content does not contain any hard links, symlinks and total size is less than 10GB.

If you're building a JS project using a static site generator like Eleventy (11ty) or Astro, you might encounter this really annoying issue where the artifact is showing as uploaded and is downloadable but the deployment never finishes because of the error:

Artifact could not be deployed. Please ensure the content does not contain any hard links, symlinks and total size is less than 10GB.

To fix this, I attempt many different builds but what ultimately solved it is changing which action I was using for uploading the artifacts. I'm not 100% sure how this works/breaks but using the actions/upload-pages-artifact action worked for me. I've pasted my whole build file below.

name: Build and deploy site

on:
  push:
    branches:
      - main

permissions:
  contents: write
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Set up Bun
        uses: oven-sh/setup-bun@v1

      - name: Install dependencies
        run: bun install

      - name: Build project
        run: bun run build

      - name: Verify build output
        run: |
          echo "Verifying build output"
          find ./dist -type l -exec echo "Symlink found: {}" \;
          ls -la ./dist

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

      - name: Download Build Artifact
        uses: actions/download-artifact@v4
        with:
          name: "github-pages"
          path: ./dist

      - name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v4
        with:
          token: ${{ github.token }}
          artifact_name: "github-pages"