Use netlify previews for PRs

[ateucher]

As per @eeholmes we can use Netlify to create deploy previews on PRs. Importantly, we can use netlify just for the preview and keep using GitHub pages for the main site.

[ateucher]

Example from PACE hackweek website: https://github.com/PACEHackWeek/pace-2024/blob/main/.github/workflows/netlifypreview.yaml

[ateucher]

Quarto website preview: https://github.com/quarto-dev/quarto-web/blob/main/.github/workflows/preview.yml;

It's perhaps a bit bloated, here is the initial inception: quarto-dev/quarto-web#667

[jules32]

Netlify will be a bit disconnected from the website, it is just using a site ID and will deploy it to a efermal site; we only want the previews (we want to

You use quarto to build the website (takes your markdown and builds the staic website .html).
You use netlify to host the website. However, we already use GitHub Pages to host our website. We if we want to preview easily from the browser (for example via a PR)

[jules32]

Notes from Coworking with @ateucher and @cassienickles, October 10. See Notes Doc for accompanying screenshots.

Goal: We want to be able to easily preview additions to the Cookbook from the browser through a (draft) pull request.
We want to use Netlify’s infrastructure for deployment, but not for hosting.

Background: What is Netlify/why? How does it interact with/different from Quarto?

• You use quarto to build the website (takes your markdown and builds the static website .html).
• You can use netlify to host the website. However, we already use GitHub Pages to host our Cookbook website. We are are planning to use Netlify’s preview feature, not hosting feature. if we want to preview easily from the browser (for example via a PR)

We will create a “site” in netlify to host our deploy previews. Usually Netlify sites have a source that they pull from (such as GitHub). However, because we don’t want to host our site on Netlify, we don’t want it pulling from the cookbook repo. Instead we will create a site that doesn’t have a defined source set up; rather we will push rendered content to the site using the Netlify API via a GitHub action.
I haven’t figured out a way to create a site without a source, so we have to create the site with a source, then remove the source, so this next bit is a bit painful:
Andy logs into netlify
Once the account is made:
Click add new site (teal button on right) > import an existing project

“Let’s deploy your project with” Choose GitHub
In the drop-down, select NASA-Openscapes, pick the repo you want (ie. earthdata-cloud-cookbook, but it could be any repo as we are only doing this to create the bare bones site, and we will unlink it from the repo later).

Let’s deploy your project with… keep team as is, Leave everything else as default (including leave Site name blank –it will be auto-generated – since we don’t want the previews to be findable)
Click “deploy earthdata-cloud-cookbook”
Production deploys - will change to green “published” within a few moments
Wait until the “Production deploys” is green - Published”.

If the deploy doesn’t publish, click deployment under “Production deploys” and click cancel deployment from the deployment log
Click site configuration on the left sidebar

Build and Deploy > under repository > Manage repository > unlink the repository (in red!)

Next copy the github action in this file
https://github.com/ateucher/ateucher.github.io/blob/main/.github/workflows/preview.yml
Pasting the code from the above link; save as “.github/workflows/deploy-preview.yml” in the earthdata-cloud-cookbook repo locally
This file is similar to quarto-publish.yml (if you’re familiar with quarto workflow). It uses a Quarto action to render the site, and the Netlify deploy action from here to push the preview to the site we just created, using the Netlify API. It creates a unique URL for each PR, and updates the preview when the PR is pushed to.
Go to Site configuration -> site details -> copy site ID. Paste this string in place of the existing ID in the NETLIFY_SITE_ID spot in the newly created preview.yml file. Commit this file and push to main (See the cookbook file here).

Next we need to add our Netlify credentials to the cookbook repo in GitHub to allow Netlify to access the PR content to create the preview.
In Netlify, go to: account (avatar top right) > user settings > applications > personal access tokens. Click “New Access Token”. Give it a descriptive name like “Cookbook deploy previews”. Set Expiration to “No Expiration”, and click “Generate Token”. Copy the token to your clipboard.

Now we add the Netlify auth token secret to GitHub. Go to earthdata-cloud-cookbook repo > Settings > Secrets and variables > Actions. Click “New Repository secret”. Make the Name NETLIFY_AUTH_TOKEN, and paste the token you copied from Netlify in the previous step in the “Secret” box. Click “Add Secret”

And that’s it!
Next created a small PR with only a small text change to test out the preview. The action ran successfully and a bot created a comment in the PR with a link to the preview - and it worked!

There is more in Posit’s quarto-web deploy preview action that we could learn from, but for now I think this will suffice. One thing they do is limit the building of previews to PRs from internal branches (not forks). For PRs from forks, the preview is triggered by a repo maintainer adding a special comment in the PR thread (\deploy-preview).