[GitHub Pages] Deploy preview option for PRs

[Andre601]

Context

When using GitHub Pages for things such as static pages or documentation is one thing almost always used alongside it: Deploy previews.

There exist many services such as Netlify and Vercel which do offer deploy previews with GitHub support, so that you can see how changes from a PR may look like.
The issue I (and probably some others) have with this is, that they either come with some limitations (i.e. limited bandwidth) or features that you can't disable and don't need (i.e. having a constant page deployment while you only need previews). This combined with the fact that some features are behind paywalls or a (sometimes) difficult configuration makes this a not so enjoyable experience.

The Idea

There should be an option to have Deploy previews using GitHub Pages. This would allow to have the main docs and any deploy preview hosted on the same place which would be GitHub (GitHub Pages).
This could reduce the required amount of configuration as you don't have to first authorize apps and sites, setup the files and dashboard settings, etc.

How it would work

Under the "Pages" tab of the Repository-setting would be a section where you can enable the deploy previews.
Clicking the button would open up the online editor, where you would create a YAML file inside the .github directory (i.e. .github/deploy-preview.yml).
This file could have a somewhat similar setup to GitHub Actions, which would allow a much higher level of configuration for when and where to build things.

As an example could you define required labels to build the preview.

Here is a small example of the file:

environment:
  - software: python # Load Python before any deployment
    version: 3.7 # Load version 3.7

requirements:
  labels:
    - 'Action: Build preview' # PR requires this label to have build preview.
  
  #excluded-labels: # List of labels to NOT start building.
  #  - 'No deploy preview'

# Set the folder where the built site will be located at
build-directory: "site"

# Define the steps the deploy should do.
actions:
  # Download dependencies through Pip from a requirements.txt
  - run: 'python -m pip install -r requirements.txt'
  # Build the site using mkdocs (Downloaded through requirements.txt)
  - run: 'mkdocs build'

If someone would now make a PR and this PR meets the requirements would GitHub take the information from the PR and build it according to the configuration.
The preview would then be deployed to a specific subdomain such as preview-<pr-id>.<username>.github.io or perhaps preview.<username>.github.io/<pr-id>/... depending on what would be doable from your end.

Final Words

I hope this is an interesting idea. I love GitHub Pages and I really hate to rely on external services to have deploy previews for Pull requests where the final page will end up on GitHub Pages anyway.
This idea would perhaps improve the flow of how you could handle deploy previews by having everything at one place. Less sites to worry about and less risk by not having authorization on other pages...

[yoannchaudet]

Hello! Just wanted to chime in here to confirm that this is something we have plans for. No ETA yet as it has not been committed to the roadmap but we are doing prep work in the next few months that will help us achieve this in the medium term.

[Andre601]

https://github.com/rossjrw/pr-preview-action looks great! @vincerubinetti Thanks for posting. Curious to hear if anyone's tried it and if there are any limitations besides the documented lack of previews for fork PRs (slated for v2).

Well, from what I can tell is it using the same repository you host your site on, so the previews will remain there, unless deleted on a close PR event. It's something not everyone may be comfortable with.

[vincerubinetti]

FYI I've tested out that action fairly extensively and even contributed a PR. The action works well for what it does, but it has some limitations:

1. It can be a pain to use with other actions/workflows. Since commits from one workflow can't automatically trigger another workflow, you need to split up your workflows in a very particular way if you want to have an automatic commit happen and then build the preview. This is not the case e.g. when using the "classic" Pages with Jekyll, where you can have an action that creates a commit automatically, and the site will rebuild automatically (with no additional workflows) whenever it needs to.
2. Since the previews all go in the same branch, you'll see them on the live site as sub-folders/paths (assuming you're using a file-system based site builder like Jekyll). One of your users could accidentally stumble upon a preview path, or you could have accidental path collisions (unlikely but possible).
3. A small issue, but the action creates a comment on the PR when the built site has been committed to the Pages branch, not when it has been committed and then deployed to the actual GitHub hosting servers. So when opening a new PR, there will be a short period of time where the comment link goes nowhere. This is because the action has no way (afaik) to listen and wait for a specific Pages deployment (pages-build-deployment) to complete.

None of these are the fault of the creator of the action.

Hopefully a first party integration by GitHub would resolve these issues.

[Andre601]

3. A small issue, but the action creates a comment on the PR when the built site has been _committed_ to the Pages branch, _not_ when it has been committed and then deployed to the actual GitHub hosting servers. So when opening a new PR, there will be a short period of time where the comment link goes nowhere. This is because the action has no way (afaik) to listen and wait for a _specific_ Pages deployment (`pages-build-deployment`) to complete.

You could just have another action that checks for page deployment and update the comment after that. There exists an action to find a comment based on criteria (i.e. author) and one to update one, so they could be used.

[vincerubinetti]

There exists an action to find a comment based on criteria (i.e. author) and one to update one, so they could be used.

Indeed. There is sticky-pull-request-comment, which is what pr-preview-action uses. I don't think that's the problem.

I think the problem is waiting on a specific (based on a particular commit) pages-build-deployment workflow run to complete. See here for more discussion:
rossjrw/pr-preview-action#25

Maybe there is a way that I'm missing, perhaps using lewagon/wait-on-check-action or codex-/await-remote-run.

Though regardless, hopefully all this discussion will be made moot very soon. 😇

[revolter]

Unfortunately, rossjrw/pr-preview-action doesn't seem to work with workflow-based GitHub Pages, only with branch-based ones.

[andrewstech]

Context

When using GitHub Pages for things such as static pages or documentation is one thing almost always used alongside it: Deploy previews.

There exist many services such as Netlify and Vercel which do offer deploy previews with GitHub support, so that you can see how changes from a PR may look like. The issue I (and probably some others) have with this is, that they either come with some limitations (i.e. limited bandwidth) or features that you can't disable and don't need (i.e. having a constant page deployment while you only need previews). This combined with the fact that some features are behind paywalls or a (sometimes) difficult configuration makes this a not so enjoyable experience.

The Idea

There should be an option to have Deploy previews using GitHub Pages. This would allow to have the main docs and any deploy preview hosted on the same place which would be GitHub (GitHub Pages). This could reduce the required amount of configuration as you don't have to first authorize apps and sites, setup the files and dashboard settings, etc.

How it would work

Under the "Pages" tab of the Repository-setting would be a section where you can enable the deploy previews. Clicking the button would open up the online editor, where you would create a YAML file inside the .github directory (i.e. .github/deploy-preview.yml). This file could have a somewhat similar setup to GitHub Actions, which would allow a much higher level of configuration for when and where to build things.

As an example could you define required labels to build the preview.

Here is a small example of the file:

environment:
  - software: python # Load Python before any deployment
    version: 3.7 # Load version 3.7

requirements:
  labels:
    - 'Action: Build preview' # PR requires this label to have build preview.
  
  #excluded-labels: # List of labels to NOT start building.
  #  - 'No deploy preview'

# Set the folder where the built site will be located at
build-directory: "site"

# Define the steps the deploy should do.
actions:
  # Download dependencies through Pip from a requirements.txt
  - run: 'python -m pip install -r requirements.txt'
  # Build the site using mkdocs (Downloaded through requirements.txt)
  - run: 'mkdocs build'

If someone would now make a PR and this PR meets the requirements would GitHub take the information from the PR and build it according to the configuration. The preview would then be deployed to a specific subdomain such as preview-<pr-id>.<username>.github.io or perhaps preview.<username>.github.io/<pr-id>/... depending on what would be doable from your end.

Final Words

I hope this is an interesting idea. I love GitHub Pages and I really hate to rely on external services to have deploy previews for Pull requests where the final page will end up on GitHub Pages anyway. This idea would perhaps improve the flow of how you could handle deploy previews by having everything at one place. Less sites to worry about and less risk by not having authorization on other pages...

Not sure if this is helpful for you. But I

Context

When using GitHub Pages for things such as static pages or documentation is one thing almost always used alongside it: Deploy previews.

There exist many services such as Netlify and Vercel which do offer deploy previews with GitHub support, so that you can see how changes from a PR may look like. The issue I (and probably some others) have with this is, that they either come with some limitations (i.e. limited bandwidth) or features that you can't disable and don't need (i.e. having a constant page deployment while you only need previews). This combined with the fact that some features are behind paywalls or a (sometimes) difficult configuration makes this a not so enjoyable experience.

The Idea

There should be an option to have Deploy previews using GitHub Pages. This would allow to have the main docs and any deploy preview hosted on the same place which would be GitHub (GitHub Pages). This could reduce the required amount of configuration as you don't have to first authorize apps and sites, setup the files and dashboard settings, etc.

How it would work

Under the "Pages" tab of the Repository-setting would be a section where you can enable the deploy previews. Clicking the button would open up the online editor, where you would create a YAML file inside the .github directory (i.e. .github/deploy-preview.yml). This file could have a somewhat similar setup to GitHub Actions, which would allow a much higher level of configuration for when and where to build things.

As an example could you define required labels to build the preview.

Here is a small example of the file:

environment:
  - software: python # Load Python before any deployment
    version: 3.7 # Load version 3.7

requirements:
  labels:
    - 'Action: Build preview' # PR requires this label to have build preview.
  
  #excluded-labels: # List of labels to NOT start building.
  #  - 'No deploy preview'

# Set the folder where the built site will be located at
build-directory: "site"

# Define the steps the deploy should do.
actions:
  # Download dependencies through Pip from a requirements.txt
  - run: 'python -m pip install -r requirements.txt'
  # Build the site using mkdocs (Downloaded through requirements.txt)
  - run: 'mkdocs build'

If someone would now make a PR and this PR meets the requirements would GitHub take the information from the PR and build it according to the configuration. The preview would then be deployed to a specific subdomain such as preview-<pr-id>.<username>.github.io or perhaps preview.<username>.github.io/<pr-id>/... depending on what would be doable from your end.

Final Words

I hope this is an interesting idea. I love GitHub Pages and I really hate to rely on external services to have deploy previews for Pull requests where the final page will end up on GitHub Pages anyway. This idea would perhaps improve the flow of how you could handle deploy previews by having everything at one place. Less sites to worry about and less risk by not having authorization on other pages...

Not sure if this is helpful, with a bit of fiddling around you can make your own deployment preview system just using basic GitHub actions.

I have made one for a react project. While we wait for GitHub to release a proper solution, I encourage you to have a tinker.

My solution if your interested generates a repository then builds the project, finally it deploys it to the new repository and posts a comment to the preview url.
Files:
https://github.com/blueedgetechno/win11React/blob/master/.github/workflows/gen-preview.yml

[Andre601]

Hey there.
Sorry for this late reply. I do like the idea you shared, but I'm not sure if I really want to use that, especially since from what I could see is this requiring a dedicated GitHub Account, which I would like to avoid having.
So if that is doable with the GitHub Actions Account (By using a personal token), I'm all in for trying it out! Just would need to know what privileges the token needs to have for this to work...

Also, since the above linked file has changed, new URL for anyone curious:
https://github.com/blueedgetechno/win11React/blob/master/.github/workflows/PR-Preview.yml

[andrewstech]

Perms to create repos and create and update files

[Andre601]

I actually do use it now for a while (And even managed to convince someone to use it too) with a dedicated account, tho I made some changes, such as not making a new repo each time (It probs makes sense for your project, but for some static sites was that wasteful) and instead just push to a specific directory within a repository.

Works really well, so thanks for sharing this.

[vincerubinetti]

The preview would then be deployed to a specific subdomain such as preview-..github.io or perhaps preview..github.io//...

I think the former would be much preferable because it would not represent a change to the baseurl of the site. I believe regardless of what tool you're using (Jekyll, React + React Router, whatever), this needs to be set properly for the site to work. If it were the latter, you'd need to dynamically change the baseurl in your tool just when doing PR previews.

Maybe take the lead from Netlify, who has urls like deploy-preview-XX--app-name.netlify.app/.

pr-preview-XX--your-org.github.io/repo-name

[Andre601]

Given the fact that GitHub Actions can now be used to deploy to GitHub Pages am I wondering something...

There is the option to define extra enviroment variables from what I saw, and given my prior experience with other deploy tools like Netlify or Vercel, these seem to be used to also define deploy enviroments?
My question right now is, if this setup would already be enough to allow to define a own domain for deploy previews using GitHub Actions.

If not would I like to hear any (and I mean any) updates regarding this. I know it's a lot of work and it may not be on any roadmap (either public or private) yet, but at least a confirmation that it's not forgotton would be nice.
After all has it been almost a year since the last official update/statement from your end.

[yoannchaudet]

It's not forgotten. We are focusing on making CD overall better at GitHub so we can release Pages previews to the world.

[Andre601]

Thanks for the reply.

[caendesilva]

This was my thought as well, and also how I found this discussion. Would make total sense IMO to be able to specify that it's for a preview when using the new Actions deployment.

[AlekSi]

I guess there is some progress: https://github.com/actions/deploy-pages/blob/368bf1aa22b9265440e251b9216520e3f91c2d5b/action.yml#L36-L39

[vincerubinetti]

How did you find that 😂

This is great news though, this will make life soooo much easier. GitHub slowly killing off all the external services I used to use. First Actions for CircleCI/Travis, now pr previews for Netlify.

[caendesilva]

Amazing!

[sghsri]

This is going to be sooo nice when its merged in!

[gfx]

Can't wait for its general availability.

FYI it has been added in the following pull request in September 2022:

• Add support for preview deployments internal alpha experiment 🧪  actions/deploy-pages#61

[benipeled]

@JamesMGreene / @yoannchaudet any update on this request?
I understand the complexity of development and I'm sure you have to prioritize this task with other many tasks,
Please take into account that this request can help significantly many users who currently use different workarounds and other tools to implement PR preview,
If there are any insights or updates you could provide regarding the progress or potential release of this feature, it would be greatly appreciated.

[JamesMGreene]

Latest update: https://github.com/orgs/community/discussions/7730#discussioncomment-7603270

Unfortunately, it's not a very satisfying one. 😭

[Andre601]

Looking back at this, I feel like there could also be a use for defining your own custom (sub-)domain for deploy previews to use, just in case you want things to look more professional.
The system could be the same as with custom domains right now, having a dedicated file containing the (sub-)domain to use. The file could probably be called PREVIEW_CNAME or something...

Alternatively have an option in the configuration file, if said file would be used.

Just a random idea...

[benipeled]

+1 for a custom domain for the preview pages
But I guess it complicates the implementation a bit so I'd start with the feature itself and leave it to v2 :)

[annabaker]

@yoannchaudet any update on when this will ship? My team could really use this feature, I've been crossing my fingers.. Would be amazing to have, +1 to @Andre601s suggestion on a custom domain. Even better if it can be defined within the workflow itself, without having to create the CNAME file directly (I believe a widely used mkdocs deploy Actions plugin behaves this way)🤞

[JamesMGreene]

Unfortunately, we can't comment on any ETA for shipping this. 😕

I can confirm that it is still intended for eventual release, and it is still actively being used internally in its alpha state.

Other projects have been prioritized over this one for the team for now, unfortunately. 😐

[thibaudcolas]

Thanks for the update @JamesMGreene! Personally I think it’s great that we get a "not for now" update. Means people who want this now have closure, and will be able to focus on other options (Netlify, Vercel, etc).

[Andre601]

I can confirm that it is still intended for eventual release, and it is still actively being used internally in its alpha state.

Any chance to be added to the alpha?
👉👈

[lauthieb]

Hello! Is it planned to release this feature for everyone soon? 🙏

[janbrasna]

Newest update from last month actions/deploy-pages#180 is there's no ETA;)

[Andre601]

Not sure if it is too late to suggest ways of doing this, but if it isn't have I found a solution another service uses, which I find quite decent.

On that other service can you put @<branch> after the domain (i.e. example.github.io/@some-branch) to display the page content of a specific branch from a repository...
Tho, given how GitHub Pages works with its deployments can I imagine that this would be a bit more tricky... Perhaps here could a name be defined to use during deployment that is set for the @... part to then use... Idk. Without any further info on what the deploy preview alpha currently looks like can I just guess here.

[AlekSi]

See also actions/deploy-pages#337