Troubleshooting

"Repository not found" or "Authentication failed"

  1. Verify the token has access to the repository.

  2. Check the token has not expired.

  3. Ensure correct credential format (no trailing whitespace).

  4. For GitLab, ensure you’re using oauth2 as the username.

"Could not find start path"

  1. Check the start_path in your playbook matches the actual directory structure.

  2. Ensure the branch specified exists in the repository.

"Multiple versions of pnpm specified" (pnpm/action-setup)

pnpm/action-setup@v4 errors if both its version input and package.json packageManager pin different releases. This action passes only package_json_file (no hard-coded version) so the version comes from your repo. Align any other pnpm/action-setup steps the same way, or set setup_pnpm: false after you install pnpm yourself.

Slow builds

  1. Use fetch: false if you don’t need to update content sources.

  2. Consider caching node_modules (install is usually fast, but caching helps large monorepos).

  3. The action enables actions/setup-node dependency cache (pnpm or npm) when it runs the setup step; if you use setup_node: false, reuse your own cache configuration.

Extension not found

  1. Check the extension package name is correct.

  2. Some extensions require both antora.extensions and asciidoc.extensions configuration.

Underscore-prefixed assets on GitHub Pages

If CSS/JS under paths like _ are not served, ensure .nojekyll exists at the site root. This action defaults create_nojekyll to true to create it for you.