Add PR previews

[nrichers]

Internal Notes for Reviewers

This PR adds automatic previews that

• get deployed to our docs-demo site when you create or update a PR; AND
• get deleted when the PR gets merged or closed

In our docs CI/CD deployment proposal, this PR adds the following highlight:

Proof it works

Deploy PR preview

Successful run: https://github.com/validmind/documentation/actions/runs/10673952942

Delete PR preview

Successful run https://github.com/validmind/documentation/actions/runs/10674028315

How it works

We already had a check to render the docs site and run tests. Together with a bit of editing of the existing workflow, we now basically take the output of that quarto render step and sync it to AWS S3, making it an efficient solution to deploy PR previews.

Why not a separate workflow to deploy PR previews? The existing quarto render CI check gives us everything we need and is also the most expensive check to run, taking ~5 minutes to complete.

The PR preview delete is just the aws s3 rm command performed on the same path in the docs-demo S3 bucket. The delete is silent as it's not something an author or reviewer needs to engage with — failures in the action should result in an email from GitHub.

How to test

• Deploy PR preview: Add a commit to this PR and watch it get deployed via the Validate docs site (render, test, and deploy) CI check. Use the preview URL from the comment to check the preview is there.
• Delete PR preview: Close this PR, wait for the Delete PR preview action to run, recheck the preview URL (it should 404), and then reopen this PR

External Release Notes

[github-actions]

PR Summary

This pull request introduces several enhancements to the GitHub Actions workflows used in the project. The key changes are as follows:

1. New Workflow for Deleting PR Previews:

   • A new GitHub Actions workflow (delete-pr-preview.yaml) is added to delete PR previews from the S3 bucket when a pull request is closed without being merged. This workflow includes steps to configure AWS credentials and delete the preview files from the S3 bucket, followed by invalidating the CloudFront distribution.

2. Improvements to Documentation Validation Workflow:

   • The existing validate-docs-site.yaml workflow is renamed to better reflect its purpose: Validate docs site (render, test, and deploy).
   • Added permissions to write issues and pull requests.
   • Added steps to configure AWS credentials, deploy PR previews to an S3 bucket, and post a comment with the preview URL on the pull request.
   • Improved naming conventions for steps to enhance clarity.

3. Minor Naming Consistency Update:

   • Updated the step name in deploy-docs-prod.yaml for consistency (Checkout code to Checkout repository).

Test Suggestions

• Verify that the new delete-pr-preview.yaml workflow triggers correctly when a pull request is closed without being merged.
• Ensure that the AWS credentials are correctly configured and that the S3 bucket and CloudFront distribution are properly updated in the delete-pr-preview.yaml workflow.
• Test the validate-docs-site.yaml workflow to confirm that it correctly renders the site, checks for errors, deploys the PR preview, and posts the preview URL as a comment on the pull request.
• Check that the permissions added to the validate-docs-site.yaml workflow are sufficient and correctly scoped.
• Validate that the naming consistency update in deploy-docs-prod.yaml does not affect the workflow's functionality.

[nrichers]

Test closing the PR to check if the PR preview gets deleted.

[nrichers]

Deleting worked, see https://github.com/validmind/documentation/actions/runs/10674028315/job/29583896617.

Reopening PR.

[github-actions]

PR Summary

This pull request introduces several enhancements to the GitHub Actions workflows used in the project. The key changes are as follows:

1. New Workflow: Delete PR Preview

   • A new GitHub Actions workflow (delete-pr-preview.yaml) is added to delete PR previews when a pull request is closed without being merged. This workflow is triggered on the pull_request event with the closed type.
   • The workflow checks out the repository, configures AWS credentials, and deletes the PR preview from an S3 bucket. It also invalidates the CloudFront distribution to ensure the changes are reflected immediately.

2. Enhancements to Validate Docs Site Workflow

   • The existing validate-docs-site.yaml workflow is renamed to Validate docs site (render, test, and deploy).
   • Permissions for issues and pull-requests are added to the workflow.
   • The job name is changed from build to validate.
   • Additional steps are added to configure AWS credentials, deploy the PR preview to an S3 bucket, and post a comment with the preview URL on the pull request.

3. Minor Changes

   • The name of the checkout step in deploy-docs-prod.yaml is changed from Checkout code to Checkout repository for consistency.
   • Minor renaming of steps in validate-docs-site.yaml for clarity.

Test Suggestions

• Verify that the delete-pr-preview.yaml workflow correctly deletes the PR preview from the S3 bucket and invalidates the CloudFront distribution when a PR is closed without being merged.
• Ensure that the validate-docs-site.yaml workflow runs successfully, including rendering the site, testing for warnings or errors, deploying the PR preview, and posting the preview URL as a comment on the PR.
• Check that the permissions for issues and pull-requests in validate-docs-site.yaml are correctly set and do not cause any permission issues.
• Test the entire workflow sequence by opening, editing, and closing PRs to ensure all actions (render, test, deploy, delete) are performed as expected.

[github-actions]

A PR preview is available: Preview URL

[github-actions]

PR Summary

This pull request introduces several enhancements to the GitHub Actions workflows used in the project. The key changes are as follows:

1. New Workflow for Deleting PR Previews:

   • A new GitHub Actions workflow (delete-pr-preview.yaml) is added to delete PR previews from the S3 bucket when a pull request is closed without being merged. This workflow includes steps to configure AWS credentials and delete the preview files from the S3 bucket, followed by invalidating the CloudFront distribution.

2. Improvements to Documentation Deployment Workflow:

   • The deploy-docs-prod.yaml workflow has been updated to rename the step from "Checkout code" to "Checkout repository" for consistency.

3. Enhancements to Documentation Validation Workflow:

   • The validate-docs-site.yaml workflow has been renamed to better reflect its purpose: "Validate docs site (render, test, and deploy)".
   • Added permissions to write issues and pull-requests.
   • Renamed the job from build to validate.
   • Added steps to configure AWS credentials, deploy PR previews to the S3 bucket, and post a comment with the preview URL on the pull request.
   • Improved the naming of steps for better clarity, such as changing "Render Site" to "Render site" and "Check for render errors" to "Test for warnings or errors".

Test Suggestions

• Verify that the new 'Delete PR preview' workflow triggers correctly when a pull request is closed without being merged.
• Ensure that the AWS credentials are correctly configured and that the S3 bucket and CloudFront distribution are properly updated in the 'Delete PR preview' workflow.
• Test the 'Validate docs site' workflow to confirm that it correctly renders the site, checks for errors, deploys the PR preview, and posts the preview URL as a comment on the pull request.
• Check that the permissions for writing issues and pull-requests are correctly set in the 'Validate docs site' workflow.
• Validate that the renaming of steps in the workflows does not affect their functionality.

[github-actions]

PR Summary

This pull request introduces several enhancements to the GitHub Actions workflows used in the project. The key changes are as follows:

1. New Workflow for Deleting PR Previews:

   • A new GitHub Actions workflow (delete-pr-preview.yaml) is added to delete PR previews from the S3 bucket and invalidate the CloudFront cache when a pull request is closed.
   • The workflow is triggered on the pull_request event with the closed type.
   • It includes steps to configure AWS credentials and delete the PR preview from the S3 bucket, followed by a CloudFront cache invalidation.

2. Enhancements to Documentation Deployment Workflow:

   • The deploy-docs-prod.yaml workflow has a minor change where the step name is updated from "Checkout code" to "Checkout repository" for consistency.

3. Improvements to Documentation Validation Workflow:

   • The validate-docs-site.yaml workflow is renamed to "Validate docs site (render, test, and deploy)".
   • The workflow now includes additional permissions for issues and pull-requests.
   • The job name is changed from build to validate.
   • The step names are updated for clarity, such as changing "Render Site" to "Render site" and "Check for render errors" to "Test for warnings or errors".
   • New steps are added to configure AWS credentials, deploy the PR preview to the S3 bucket, and post a comment with the preview URL on the pull request.

Test Suggestions

• Verify that the new 'Delete PR preview' workflow is triggered and executes successfully when a pull request is closed.
• Check that the PR preview is correctly deleted from the S3 bucket and the CloudFront cache is invalidated.
• Ensure that the 'Validate docs site' workflow runs without errors and correctly renders the documentation site.
• Confirm that the PR preview is deployed to the S3 bucket and accessible via the provided URL.
• Validate that the comment with the preview URL is posted on the pull request.

[nrichers]

Test deleting PR preview by closing PR.

[nrichers]

Reopening PR for review & approval.

[github-actions]

PR Summary

This pull request introduces several enhancements to the GitHub Actions workflows used in the project. The key changes are as follows:

1. New Workflow for Deleting PR Previews:

   • A new GitHub Actions workflow (delete-pr-preview.yaml) is added to delete PR previews from the S3 bucket and invalidate the CloudFront cache when a pull request is closed.
   • This workflow is triggered on the closed event of pull requests.
   • It includes steps to configure AWS credentials and delete the PR preview from the S3 bucket, followed by a CloudFront cache invalidation.

2. Enhancements to Documentation Deployment Workflow:

   • The deploy-docs-prod.yaml workflow has a minor change in the step name from "Checkout code" to "Checkout repository" for consistency.

3. Improvements to Documentation Validation Workflow:

   • The validate-docs-site.yaml workflow has been renamed to better reflect its purpose: "Validate docs site (render, test, and deploy)".
   • Added permissions for issues and pull-requests to allow posting comments.
   • The workflow now includes steps to configure AWS credentials, deploy PR previews to an S3 bucket, and post a comment with the preview URL on the pull request.
   • Improved step names for clarity, such as changing "Render Site" to "Render site" and "Check for render errors" to "Test for warnings or errors".

4. Minor Documentation Update:

   • A comment in the README.md file has been updated with a timestamp.

Test Suggestions

• Verify that the new 'Delete PR preview' workflow triggers correctly when a pull request is closed.
• Ensure that the AWS credentials are correctly configured and that the S3 bucket and CloudFront distribution are properly accessed.
• Test the 'Validate docs site' workflow to confirm that it renders the site, checks for errors, deploys the preview, and posts the comment with the preview URL.
• Check that the 'Deploy docs prod' workflow still functions as expected after the minor step name change.
• Manually close a pull request and verify that the PR preview is deleted from the S3 bucket and the CloudFront cache is invalidated.

[github-actions]

A PR preview is available: Preview URL