feat: reintroduce docusaurus caching to CI

[pepopowitz]

Description

Resolves #4418, by adding a local GitHub action that basically does what we ripped out in #4417 due to the target action being removed from the internet.

For reference, the original caching was introduced in #4025.

This PR adds the caching step to these workflows:

• preview-env-deploy
• build-docs
• publish-stage

It does not add it to publish-prod....yet. I'd like to see it merged and running against staging first, to make sure it doesn't mess up prod builds.

Some details about how the caching works

• Caches are not shared across branches, because they need to be dropped in a location that is noticed by the docusaurus build -- which is specific to each branch.
• This means that the first build of every PR will always be a fresh one. Subsequent builds of a PR should benefit from the cache.
• We can only handle about 13 caches at one time, because the docusaurus cache is so large. See this page for a list of existing caches.
• Because of the above two limitations, we will see cache misses even when it seems like we shouldn't. GitHub will evict caches when we reach our size limit, but only once per day. Many PRs in one day should see cache benefits; PRs across multiple days might see a fresh build once per day.

This PR also modifies build-docs workflow to trigger only on pull_request.

This is done to allow sharing of the cache between the build-docs and preview-env-deploy. A build triggered by push does not run in the same github_workspace as a build triggered on pull_request -- see this screenshot of caches:

Those are the same PR. The top one is from preview-env-deploy running on a pull_request trigger; the bottom one is from build-docs running on a push trigger. (Yes, the issue/PR numbers are different in the two caches, but that's because the top one shows the PR number, and the bottom one shows the branch name, which includes the issue number.)

Removing the push trigger from build-docs, and forcing it to run on pull_request in all cases, results in the workspace/cache being shared across the workflows. This has two positive effects: (1) a better chance that a build will benefit from a cache, and (2) fewer caches, thus longer duration of each cache before it gets evicted due to lack of space.

Can we remove the push trigger?

I tracked down two conversations in Slack where I've asked publicly if people are using the push trigger to watch CI before they open a PR: https://camunda.slack.com/archives/C01H4NG9XDY/p1654292859796899?thread_ts=1654292843.207019&cid=C01H4NG9XDY and https://camunda.slack.com/archives/C026U8GBNSW/p1675695601973339.

In neither case did a single person say "I rely on the push trigger, by pushing up a branch before opening a PR."

This trigger was skipping main, so direct-commits to main (which shouldn't be done) weren't relying on this workflow to tell us when the build broke in that occasion, either.

Thus, I think we can remove this trigger, and if anyone complains, nudge them to open PRs if they want to run builds.

Experiments

You can see the workflow executions from my experimentation here and here. Note the build times decrease by 4-10 minutes on executions that are able to take advantage of the cache.

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)
• 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/).

• My changes require an Engineering review, and I've assigned the Engineering DRI or delegate.

• My changes require a technical writer review, and I've assigned @camunda/tech-writers as a reviewer.

• My changes require a docs infrastructure review.

[clementnero]

LGTM!

[clementnero]

GitHub will evict them when we reach our size limit

Indeed, but only once a day, so cache will be very helpful for consecutive push in a relatively short (one day) timeframe 🚀 .

[pepopowitz]

GitHub will evict them when we reach our size limit

Indeed, but only once a day, so cache will be very helpful for consecutive push in a relatively short (one day) timeframe 🚀 .

Oh, nice! I was wondering how frequently this happened, because every time I look at that "caches" page it seems like we're over the cache limit 😅

[akeller]

Sorry! I had this opened in a tab yesterday for review, but didn't actually hit the button.

[github-actions]

🧹 Preview environment for this PR has been torn down.