chore(preview-envs): Add preview env workflows to camunda docs repo

andromaqui commented 2 weeks ago

Description

This pr adds two workflows which aim to assist in deploying the camunda-docs preview environments as well as tearing the environments down:

preview-env-deploy.yml:

Deployment Trigger: Activates on labeled pull requests.
Build: Installs dependencies, builds the project
Deployment: Syncs the content of the path in the bucket to the local folder build. I did a test and using the gsutil command with the rsync -d -r option does the following: a. Files which don’t exist in the bucket but exist locally in the build folder will get uploaded b. Files which exist in the bucket but not in the local folder will get deleted from the bucket c. File which exist in both the local directory and the bucket but they have different content will be synced (the content of the local files will override the content of the files in the bucket) 
Comment Handling: Updates or creates comments on the pull request about deployment status  a. If no comments exist then a comment indicating the deployment url will be shown  b. If a comment is found which indicates that the environment was previously teared down, it will be replaced by a comment indicating the preview env url. c. If there is subsequent deployments then the comment indicating that the preview env has been deployed will remain intact
- Deployment status: The deployment status will start showing in the pr just before the build step. Once the deployment has been concluded the url will be shown at the status

preview-env-teardown.yml

Deployment Trigger: Runs on pull request unlabeled or closed events if the 'deploy' label is present or was present.
- Deletes Bucket Files: Removes files from the Google Cloud Storage bucket associated with the pull request.
- Updates Comment: Finds and updates a specific comment on the pull request to indicate the preview environment has been torn down.

Testing

Test1: Teardown workflow gets triggered when closing pr

PR https://github.com/camunda/camunda-docs/pull/3961 Run triggered: https://github.com/camunda/camunda-docs/actions/runs/9576897550/job/26404161568

Test 2: When pushing multiple times in the same pr: the deploy comment won’t get posted multiple times and the preview environment will be build from scratch

An example of this can be found in this pr as the deploy label is active and there are multiple pushes which have happened. The latest run of the deploy-preview-env workflow wiped out all files from the bucket pr-3960 before pushing the built changes again https://github.com/camunda/camunda-docs/actions/runs/9577037637/job/26404564930?pr=3960

Test 3: Adding and removing the deploy label multiple times results in only one comment in the pr indicating the current status of the preview env.

You can have a look at the history of this pr. The label has been removed and added multiple times and there is one comment which constantly get updated. The comment gets created/updated in the following ways:

When a deployment was successful a comment gets created.
The comment doesnt get updated when there are subsequent pushes to the pr even if there have been subsequent deployments.
The comment gets updated when the preview env gets teared down (on label removal for instance) indicating that action.
The comment which previously was indicating that the preview env has been teared down will have to be updated again to indicate that the preview env has been deployed in case the label was added again to the pr and the deployment was successful.

After env was torn down:

Test 4: The url in the posted comment leads to a working preview environment

Following this comment on this pr the url posted there should prompt us to a working preview environment. The link is https://preview.docs.camunda.cloud/pr-3960/index.html.

Test 5: Test concurency in deploy preview env workflow

PR: https://github.com/camunda/camunda-docs/pull/3965

Initial run triggered: https://github.com/camunda/camunda-docs/actions/runs/9595842471/job/26461440032?pr=3965 Second run triggered: https://github.com/camunda/camunda-docs/actions/runs/9595856162/job/26461487867?pr=3965 The initial run got cancelled after the first run got triggered

Test 6: Preview env has been torn down

PR: https://github.com/camunda/camunda-docs/pull/3972 I deployed the preview env and then removed the label to tear it down.

Since the deployment is only deactivated and not removed, this is how it is deployment after the environment has been torn down (notice the url not been apparent anymore):

An explanation as to why the deployment has not been removed can be found in this comment https://github.com/camunda/camunda-docs/pull/3960#discussion_r1648617453

When should this change go live?

[ ] This is a bug fix, security concern, or something that needs urgent release support.
[ ] This is already available but undocumented and should be released within a week.
[ ] This on a specific schedule and the assignee will coordinate a release with the DevEx team. (apply hold label or convert to draft PR)
[ ] This is part of a scheduled alpha or minor. (apply alpha or minor label)
[x] There is no urgency with this change and can be released at any time.

PR Checklist

[ ] My changes are for an already released minor and are in /versioned_docs directory.
[ ] My changes are for the next minor and are in /docs directory (aka /next/).

[x] My changes require an Engineering review, and I've assigned the Engineering DRI or delegate.
[x] My changes require a technical writer review, and I've assigned @camunda/tech-writers as a reviewer.

andromaqui commented 1 week ago

@pepopowitz Thank you for having a look at this pr and glad you are pleased with the current result. I just wanted to say that the pr has not gone through infra review yet so a merge is not possible. Tagging @akeller as well on this message :)

akeller commented 1 week ago

@akeller I'm assigning this PR to you to review/merge when it is convenient for you, since I will be out of office after tomorrow and unavailable to support if anything happens. If you'd rather wait until I'm back in a few weeks, feel free to reassign to me.

I reworked this so I'm not the assignee. I didn't do any work here 😉 and @andromaqui deserves all the credit!

Adding this to my list of things to review tomorrow.

github-actions[bot] commented 1 week ago

Your preview env has been torn down.

andromaqui commented 1 week ago

@akeller This pr is now ready for devex review as well :)

akeller commented 1 week ago

@andromaqui this is super cool! I know our PMs will be very excited to have previews available for docs PR reviews 🚀

The implementation looks clean and is easy to follow. No concerns with that.

I'm looking into each of the open PRs associated with this work and noticed I occasionally see a NoSuchKey error:

Initially, I thought this happened on the first load, but it happened again. It happens if I am on any page and hit the refresh button in my browser. The error continues until I navigate to the docs homepage and refresh. Given that this is better than our current state, I will accept this as a bug if this is a complex issue (either to debug or fix).

https://github.com/camunda/camunda-docs/assets/1051363/ded5c860-7c87-42d0-816c-c49b1714732f

andromaqui commented 1 week ago

@akeller Thank you for catching this error, I didnt think of refreshing tbh. I had al look into the issue and that seems to be a common problem with bucket hosted javascript applications (example thread on stack overflow). I am not yet 100% certain but I think the change will involve modifying some settings on the bucket side so this pr here probably doesnt have influence in this topic.

If the current solution is acceptable to you, could we consider merging this? Today I am working on another urgent task but I will priorise fixing this issue with the preview environments right after

camunda / camunda-docs