astro ghpages action fails to autodetect pnpm usage #80
Description
Astro Info
$ pnpm astro info
> @0.0.1 astro /mnt/<myfilesystempath>/astro-ghpages-pnpm-version-error.github.io
> astro info
Astro v5.13.5
Node v22.19.0
System Linux (x64)
Package Manager pnpm
Output static
Adapter none
Integrations @astrojs/starlight
Clipboard command not found!
Please manually copy the text above.
If this issue only occurs in one browser, which browser is a problem?
No response
Describe the Bug
Description
The official astro github page action is failing to detect the use of pnpm successfully based on the pnpm lockfile existing when following the offical docs on how to set it up https://docs.astro.build/en/guides/deploy/github/.
Reproduction Steps
Host Machine
Dev machine Microsoft Windows 11 Pro version 10.0.26100 Build 26100
Commands run via powershell:
> wsl --version
WSL version: 2.5.10.0
Kernel version: 6.6.87.2-1
WSLg version: 1.0.66
MSRDC version: 1.2.6074
Direct3D version: 1.611.1-81528511
DXCore version: 10.0.26100.1-240331-1435.ge-release
Windows version: 10.0.26100.4946
> wsl --list --running
Windows Subsystem for Linux Distributions:
Ubuntu (Default)
(WSL and Ubuntu installed yesterday)
WSL Linux Environment
environment inside the WSL Ubuntu install:
$ uname -a
Linux <mypcname> 6.6.87.2-microsoft-standard-WSL2 withastro/astro#1 SMP PREEMPT_DYNAMIC Thu Jun 5 18:30:46 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux
$ node --version
v22.19.0
$ pnpm --version
10.15.0
Github Repo creation
Create a new organization xyz and repo inside it xyz.github.io. Specify no README, no LICENSE required (I specified MIT).
My repo with initial commit:
Per Astro documentation for deploying to github pages at:
https://docs.astro.build/en/guides/deploy/github/
Go into Settings for the repo, Pages:
-
set
SourcetoGithub Actions.Note: you could set this to
Deploy from a branchand you would get the exact same result.
Create Astro Starlight project
Check it out on your WSL2 machine:
$ pnpm create astro@latest
pnpm create astro@latest
astro Launch sequence initiated.
dir Where should we create your new project?
.
tmpl How would you like to start your new project?
Use docs (Starlight) template
deps Install dependencies?
No
◼ No problem! Remember to install dependencies after setup.
◼ Nice! Git has already been initialized
✔ Project initialized!
■ Template copied
next Liftoff confirmed. Explore your project!
Run pnpm dev to start the dev server. CTRL+C to stop.
Add frameworks like react or tailwind using astro add.
Stuck? Join us at https://astro.build/chat
╭─────╮ Houston:
│ ◠ ◡ ◠ Good luck out there, astronaut! 🚀
╰─────╯
then deps
$ pnpm install
Packages: +386
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 468, reused 387, downloaded 0, added 386, done
dependencies:
+ @astrojs/starlight 0.35.2
+ astro 5.13.5
+ sharp 0.34.3
╭ Warning ───────────────────────────────────────────────────────────────────────────────────╮
│ │
│ Ignored build scripts: esbuild, sharp. │
│ Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts. │
│ │
╰────────────────────────────────────────────────────────────────────────────────────────────╯
Done in 1m 45.6s using pnpm v10.15.0
$ pnpm approve-builds
✔ Choose which packages to build (Press <space> to select, <a> to toggle all, <i> to invert selection) · esbuild, sharp
✔ The next packages will now be built: esbuild, sharp.
Do you approve? (y/N) · true
node_modules/.pnpm/[email protected]/node_modules/esbuild: Running postinstall script, done in 262ms
node_modules/.pnpm/[email protected]/node_modules/sharp: Running install script, done in 622ms
node_modules/.pnpm/[email protected]/node_modules/sharp: Running install script, done in 623ms
$ pnpm install
Lockfile is up to date, resolution step is skipped
Already up to date
Done in 2.4s using pnpm v10.15.0
Verify the project works:
$ pnpm run dev
> @0.0.1 dev /mnt/<my filesystem path>/astro-ghpages-pnpm-version-error.github.io
> astro dev
01:12:51 [types] Generated 7ms
01:13:00 [content] Syncing content
01:13:00 [content] Synced content
astro v5.13.5 ready in 31634 ms
┃ Local http://localhost:4321/
┃ Network use --host to expose
01:13:00 watching for file changes...
Verify at http://localhost:4321/ the site loads, works, and you can browser around the examples.
- Yup!
Optionally commit and push the working site to github, no ghpages yet added.
My repo with the working astro starlight defaults, no ghpages yet:
No files have been manually created or edited at this point, only astro create has been used.
If you already configured github pages on the repo, it should now be serving your README.md from Astro at: https://xyz.github.io
Mine was at: https://astro-ghpages-pnpm-version-error.github.io/
and was serving the default startlight README.
Add ghpages deploy action to astro
Follow official Astro Docs for deploying Astro Site to Github Pages (retrieved 2025-08-30):
https://docs.astro.build/en/guides/deploy/github/
Create the .github/workflows/deploy.yml file with the contents specified:
name: Deploy to GitHub Pages
on:
# Trigger the workflow every time you push to the `main` branch
# Using a different branch name? Replace `main` with your branch’s name
push:
branches: [ main ]
# Allows you to run this workflow manually from the Actions tab on GitHub.
workflow_dispatch:
# Allow this job to clone the repo and create a page deployment
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout your repository using git
uses: actions/checkout@v4
- name: Install, build, and upload your site
uses: withastro/action@v3
# with:
# path: . # The root location of your Astro project inside the repository. (optional)
# node-version: 20 # The specific version of Node that should be used to build your site. Defaults to 20. (optional)
# package-manager: pnpm@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)
# env:
# PUBLIC_POKEAPI: 'https://pokeapi.co/api/v2' # Use single quotation marks for the variable value. (optional)
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
No changes to the file per documentation.
It should auto detect the package-manager from the pnpm-lock.yaml file checked in, no other lock files.
Edit astro.config.js with your https://xyz.github.io site key per documentation. Since we created an organization, no base needs to be specified.
Commit and you expect it to deploy to ghpages using the astro action.
Here is my commit:
And here is the error output from ghpages:
- https://github.com/astro-ghpages-pnpm-version-error/astro-ghpages-pnpm-version-error.github.io/actions/runs/17340063239/job/49232671338
Fails in theInstall, build, and upload your sitestep:
Run withastro/action@v3
Run len=`echo $INPUT_PM | wc -c`
Run pnpm/action-setup@v4
Running self-installer...
Error: No pnpm version is specified.
Please specify it by one of the following ways:
- in the GitHub Action config with the key "version"
- in the package.json with the key "packageManager"
at readTarget (/home/runner/work/_actions/pnpm/action-setup/v4/dist/index.js:1:5400)
at runSelfInstaller (/home/runner/work/_actions/pnpm/action-setup/v4/dist/index.js:1:3930)
at async install (/home/runner/work/_actions/pnpm/action-setup/v4/dist/index.js:1:3154)
at async main (/home/runner/work/_actions/pnpm/action-setup/v4/dist/index.js:1:445)
Error: Error: No pnpm version is specified.
Please specify it by one of the following ways:
- in the GitHub Action config with the key "version"
- in the package.json with the key "packageManager"
Notice the Error: No pnpm version is specified. error.
Uncomment pnpm in deploy.yml
edit .github\worksflows\deploy.yml and try to fix it by uncommenting the with: line and package-manager: pnpm@latest line
See commit to my repo here:
This time it works:
Verified deployment at: https://astro-ghpages-pnpm-version-error.github.io/
Revert uncomment to verify that was the culprit
Revert or change back the steps from Uncomment pnpm in deploy.yml to make sure the default doc instruction do not work.
My revert commit:
Same failure as before the fix:
traditional ghpages Branch deployment method without the uncomment fix
Repo should now be default per the docs with the deploy.yml, no pnpm specified, it should auto detect from the pnpm-lock.yaml file checked in.
Note: The astro docs specify to use Github Actions not Branch deployment, nevertheless this is a bit interesting.
On github repo settings in Pages config:
- set
SourcetoDeploy from a branch - set
Branchtomainand/ (root)(defaults)
In the repo:
edit .github/workflows/deploy.yml to add a # traditional ghpages from branch line just to have something to commit to trigger ghpages again.
My repo:
Error is the same as before:
Error: Error: No pnpm version is specified.
Try uncommenting pnpm line for traditional ghpages branch deploy
edit .github\worksflows\deploy.yml and try to fix it by uncommenting the with: line and package-manager: pnpm@latest line
My repo:
This time success:
and verified at https://astro-ghpages-pnpm-version-error.github.io/
My actual project
In my actual project, I originally used github branches, and despite uncommenting the pnpm@latest still got the no version error. I fixed it by changing it to specify the exact version [email protected]. I could not reproduce that problem here, pnpm@latest appears to fix it in both Github Pages (the recommendation from astro) and the traditional Deploy from Branch. I will demise that I am misremembering what the configuration state was and that this was due to something else.
EDIT: per #80, there does indeed seem to be a case where uncommenting pnpm@latest was not enough, and you had to specifiy the exact version, as another user encountered the same problem, despite I not being able to reproduce the exact steps.
Nevertheless I was able to reproduce the failure to automatically detect pnpm as advertised in the steps above consistently.
Final note
The official astro github page action is failing to detect the use of pnpm successfully based on the pnpm lockfile existing.
What's the expected result?
Successful ghpages build and publishing
Link to Minimal Reproducible Example
Participation
- I am willing to submit a pull request for this issue.
- 🦥