[GitHub Pages] Deploy preview option for PRs #7730

Andre601 · 2021-11-15T13:04:26Z

Andre601
Nov 15, 2021

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 · 2021-12-30T05:25:31Z

yoannchaudet
Dec 30, 2021

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.

13 replies

Andre601 Nov 23, 2022
Author

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 Jan 12, 2023

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:

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.
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).
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 Jan 12, 2023
Author

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 Jan 12, 2023

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 8000 . 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 May 6, 2024

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

andrewstech · 2022-02-06T22:37:27Z

andrewstech
Feb 6, 2022

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 me 8000 ets 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

3 replies

Andre601 May 2, 2022
Author

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 Jun 23, 2022

Perms to create repos and create and update files

Andre601 Jul 13, 2022
Author

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 · 2022-11-23T19:06:13Z

vincerubinetti
Nov 23, 2022

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

0 replies

Andre601 · 2022-11-23T19:38:22Z

Andre601
Nov 23, 2022
Author

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.

4 replies

yoannchaudet Nov 23, 2022

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

Andre601 Nov 23, 2022
Author

Thanks for the reply.

caendesilva Mar 21, 2023

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.

InDieTasten Jun 16, 2025

@yoannchaudet Is there any chance you can bump that topic internally? The official pages-deploy action still gatekeeps that functionality to staff and GitHub-owned repos only 🙁

AlekSi · 2023-01-12T17:42:10Z

AlekSi
Jan 12, 2023

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

4 replies

vincerubinetti Jan 12, 2023

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 Mar 21, 2023

Amazing!

sghsri Apr 3, 2023

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

gfx Sep 29, 2023

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 · 2023-08-21T13:10:29Z

benipeled
Aug 21, 2023

@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.

1 reply

JamesMGreene Nov 17, 2023

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

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

Andre601 · 2023-08-21T13:33:16Z

Andre601
Aug 21, 2023
Author

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...

1 reply

benipeled Aug 21, 2023

+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 :)

anna-engle · 2023-10-26T17:12:31Z

anna-engle
Oct 26, 2023

@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)🤞

7 replies

JamesMGreene Nov 17, 2023

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 Nov 18, 2023

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 Nov 18, 2023
Author

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 Feb 1, 2024

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

janbrasna Feb 25, 2024

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

Andre601 · 2024-03-21T17:12:39Z

Andre601
Mar 21, 2024
Author

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.

10000

0 replies

AlekSi · 2024-06-17T14:15:17Z

AlekSi
Jun 17, 2024

r-leyshon
Jul 3, 2024

This would be a really great feature for our organisation.

0 replies

landsman · 2025-02-16T12:59:19Z

landsman
Feb 16, 2025

This

0 replies

jolestar · 2025-05-19T15:25:09Z

jolestar
May 19, 2025

Is there any update on this feature? I asked the GitHub Copilot in VS Code, and it thinks the PR preview should be worked :).

1 reply

mfisher87 May 19, 2025

@jolestar I believe that's a hallucination.

When I want to check if this feature is available, I check here:

https://github.com/actions/deploy-pages/blob/854d7aa1b99e4509c4d1b53d69b7ba4eaf39215a/action.yml#L29

It still says the feature is not available to the public on the latest revision.

2025-06-16T12:00:28Z

github-actions[bot]
bot Jun 16, 2025

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

Your input will be carefully reviewed and cataloged by members of our product teams.
- Due to the high volume of submissions, we may not always be able to provide individual responses.
- Rest assured, your feedback will help chart our course for product improvements.
Other users may engage with your post, sharing their own perspectives or experiences.
GitHub staff may reach out for further clarification or insight.
- We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

Upvote and comment on other user feedback Discussions that resonate with you.
Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐

0 replies

[GitHub Pages] Deploy preview option for PRs #7730

Uh oh!

Uh oh!

Context

The Idea

How it would work

Final Words

Replies: 14 comments · 34 replies

Uh oh!

Uh oh!

Andre601 Nov 23, 2022 Author

Uh oh!

Uh oh!

Andre601 Jan 12, 2023 Author

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Context

The Idea

How it would work

Final Words

Context

The Idea

How it would work

Final Words

Uh oh!

Andre601 May 2, 2022 Author

Uh oh!

Uh oh!

Andre601 Jul 13, 2022 Author

Uh oh!

Uh oh!

Andre601 Nov 23, 2022 Author

Uh oh!

Uh oh!

Andre601 Nov 23, 2022 Author

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Andre601 Aug 21, 2023 Author

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Replies: 14 comments 34 replies

Andre601 Nov 23, 2022
Author

Andre601 Jan 12, 2023
Author

Andre601 May 2, 2022
Author

Andre601 Jul 13, 2022
Author

Andre601
Nov 23, 2022
Author

Andre601 Nov 23, 2022
Author

Andre601
Aug 21, 2023
Author