search

rossjrw / pr-preview-action

GitHub Action that deploys a pull request preview to GitHub Pages, similar to Vercel and Netlify, and cleans up after itself.
https://github.com/marketplace/actions/deploy-pr-preview
MIT License
255 stars 39 forks source link

Add ability to specify GitHub pages directory #80

Closed RedSparr0w closed 5 months ago

RedSparr0w commented 5 months ago

Currently as far as I can tell, you are not able to specify the directory you are using to serve your GitHub pages project. This means when the preview URL is generated it still includes the pages directory pointing to a broken link.

For example, my repo uses docs/ as the GitHub pages base directory, with the following config I get this output:

          source-dir: 'build'
          preview-branch: 'master'
          umbrella-dir: 'docs/preview'
          custom-url: 'example.site'

Output URL: https://example.site/docs/preview/pr-123 Expected URL: https://example.site/preview/pr-123

rossjrw commented 5 months ago

Closing this issue as a duplicate of #42.

rossjrw commented 5 months ago

@RedSparr0w I wouldn't set master as the preview branch.

The preview action will put a copy of the entire contents of your repo into the preview branch. In this case you've got docs/preview/pr-123/ containing a copy of the repo, modified as per PR 123, but it'll also include its own docs directory docs/preview/pr-123/docs/. Bear in mind that this is all on the master branch.

Next person to make a pull request branches from master, which contains PR 123's preview, and opens PR 124. Now master's docs dir contains docs/preview/pr-123/ and also docs/preview/pr-124/. Sounds good so far but because PR 123 and PR 124 are happening at the same time, and PR 124 came later, you also have docs/preview/pr-123/docs/preview/pr-123/.

Let's say PR 123 is a little out of date and merges master into itself. Now you've got docs/preview/pr-123/docs/preview/pr-124/docs/preview/pr-123/. Your preview directory is growing exponentially with seemingly-harmless operations like updating pull requests. All of this is happening on the master branch, affecting pull time, repo size etc.

In my projects, a rule I stick to is that the main branch should only ever contain work authored by humans. Previews are technically computer-generated given that they're just copies of human-written work.

Deploying from docs/ on the master branch has presumably worked fine for you up until now because, I assume, all the stuff in there is entirely authored by humans. Now that you want to add generated files I suggest a different workflow.

I would suggest adopting the 'gh-pages' workflow that my preview action assumes as a default. By deploying from the root directory of the gh-pages branch, you create a dedicated space for your deployment and subdeployments (like these previews) to exist without impacting anything else. Critically, no-one is going to want to branch from gh-pages to add new stuff to your repo, so you'll never get the feedback loop that I described.

You should still keep your deployment in docs/, but add a new workflow that copies it into gh-pages on push to master - e.g. https://github.com/rossjrw/pr-preview-action?tab=readme-ov-file#full-example (but change the source-dir and folder parameters from . to ./docs/)

RedSparr0w commented 5 months ago

Oh sorry, some how missed #42 😅

All of our code and PRs go to our develop branch, It's all deploying fine without recursion, we build to the build/ directory, and then move it over to the docs/ directory for deployment.

Or in the case of the PR previews, it's just copying the build directory over to docs/preview/pr-123 on our gh-pages specified branch (have had multiple PRs and re-deployments of PRs to confirm).

Our master branch only contains the gh-pages data, and not the rest of the code.

Unfortunately it has to be on the master branch and docs directory due to some other systems we have relying on it being there due to how it was previously deployed a long while ago.