feat: Add GitHub Actions workflow for Netlify preview deployments

[ongdisheng]

Closed: #638

Purpose of the pull request

This PR implements Netlify preview deployments for documentation changes using GitHub Actions. It addresses issue #638 by enabling automatic preview site generation when contributors submit pull requests that modify documentation files. This allows reviewers to see the rendered documentation before merging changes to the main branch.

What's changed?

This PR added a new GitHub Actions workflow file preview-docs.yml that automatically deploys documentation previews to Netlify when pull requests modify files in the website directory. The workflow uses the actions-netlify to handle the deployment and automatically posts the preview URL as a comment on the pull request. It only triggers for pull requests that contain changes to the documentation, ensuring that code-only pull requests do not consume build resources unnecessarily. This implementation requires creating a Netlify site first by importing the project from Netlify dashboard. Once the site is created, there are two repository secrets that need to be configured in the repository settings:

• NETLIFY_AUTH_TOKEN: A personal access token from Netlify for authentication
• NETLIFY_SITE_ID: The API ID of the Netlify site where previews will be deployed

Note: A working demonstration of this workflow can be seen in this test PR on my fork, where the GitHub Actions bot successfully posted the preview URL.

Checklist

• I have read the Contributor Guide.
• I have written the necessary doc or comment.
• I have added the necessary unit tests and all cases have passed.

[alaahong]

Seems it only working while website folder changes, it's well to limited the deploy on NETLIFY.

And meanwhile, as Fesod doesn't have NETLIFY token at this moment, had you validated on your resource before raise the PR?
The given deployed sample is broken as below screenshot

@delei do you have any suggestion on the deployment target as FESOD also register one account for this too?

[delei]

@delei do you have any suggestion on the deployment target as FESOD also register one account for this too?

I agree to register and use NETLIFY.

[ongdisheng]

Hi @alaahong, thanks for the feedback!

Testing

I've tested the workflow on my fork with the required secrets configured. You can see the working implementation in this test PR.

About the Deployment URLs

There are two bot comments appearing in my test PRs:

• GitHub Actions bot: This is the deployment from the workflow
• Netlify bot: This is from Netlify's automatic GitHub integration

Both URLs now point to the same preview site because the workflow uses the alias parameter to standardize the URL format. However, only the GitHub Actions workflow deployment is needed.

Why Two Bot Comments?

The Netlify bot appears because my test site still has Netlify's automatic GitHub integration enabled. Once the upstream fesod repository is configured, you can disable Netlify's automatic builds by setting:

• Site configuration → Build & deploy → Deploy Previews → None
• Site configuration → Build & deploy → Branch deploys → None

This way, only the GitHub Actions workflow will build and deploy, posting a single bot comment with the preview URL. This prevents duplicate builds and saves Netlify build minutes. The workflow has been tested and is working correctly on my fork.

[alaahong]

LGTM

It's a great enhancement for docs preview

[alaahong]

Hi @ongdisheng , can you kindly to check the reason why your solution have to bind with additional token and site id for Netlify?
I tried to understand the actions from Selenium, seems no such restrcition?
https://github.com/SeleniumHQ/seleniumhq.github.io/tree/trunk/.github/workflows
Otherwise, if this is the blocking, can you also help to seek an available solution for Fesod?

Thanks.

[ongdisheng]

Hi @alaahong, thank you for pointing me to the Selenium repository. I checked their setup and found that they use a different approach from Fesod. Selenium has a netlify.toml file but doesn't use GitHub Actions for Netlify deployment. Instead, they connect their repository directly through Netlify's dashboard, which means Netlify builds and deploys automatically on their servers without needing tokens in GitHub secrets.

Fesod's approach: We currently use the nwtgck/actions-netlify, which builds in GitHub Actions and then deploys to Netlify via their API. This requires NETLIFY_AUTH_TOKEN and NETLIFY_SITE_ID for API authentication because the action needs to authenticate with Netlify's API to create deploy previews.

APISIX's approach: I also found that Apache APISIX uses the same approach as Fesod with GitHub Actions. It seems like they successfully requested the Netlify secrets from Apache Infra through JIRA ticket INFRA-23242, and their deploy previews are working well as shown in this PR: apache/apisix-website#1081

Given that APISIX successfully uses the same approach, would it be possible to request the Netlify secrets from Apache Infra similar to their setup? From my understanding, Selenium's dashboard approach would still require Apache Infra involvement to configure the Netlify integration. I'm happy to assist with either solution or provide any additional information that might be helpful. Thank you for looking into this!