chore(README): Provide workflow_run troubleshooting

[polarathene]

Adds a troubleshooting section for users to learn about pull_request workflow gotcha and an example of how to get it setup.

Includes information on features that presently are unsupported for this action with workflow_run and a workaround for PR comment and status updates in the meantime.

Deployment environment updates can't be disabled and will use the wrong commit for now.

[nwtgck]

Fantastic! Thank you so much for the explanation and code. Code is very helpful. I'll read.

[nwtgck]

rendered: https://github.com/polarathene/actions-netlify/blob/4d24251f2cfec3f03fd3a4878453ec1243df0cae/README.md#troubleshooting

[t1m0thyj]

@polarathene Thanks for the thorough documentation. It was quite helpful since I also had to set up Netlify deploys for PRs coming from outside collaborators (in zowe/docs-site#2913).

One more tip that may be useful for others doing the same thing - in my case, the artifact for the preview build is quite large (almost 1GB) so it takes 5-10 minutes to upload it from the pull_request workflow and download it from the workflow_run workflow.

In order to make deployments as quick as possible, I still deploy from the pull_request workflow when the PR is not opened from a fork using logic like the following:
https://github.com/t1m0thyj/zowe-docs-site/blob/2a0f41218516752a3088626ede350edcd107e3dc/.github/workflows/build-docs.yml#L45-L73

Then in the workflow_run workflow, I skip deployment if the artifact is not found:
https://github.com/t1m0thyj/zowe-docs-site/blob/2a0f41218516752a3088626ede350edcd107e3dc/.github/workflows/deploy-preview.yml#L15-L44

[polarathene]

in my case, the artifact for the preview build is quite large (almost 1GB)

That's due to node_modules I take it?

You can use the cache action possibly to separate that portion out, then it's only relevant when the dependencies change/update.

Usually though at least for docs deployments there is a build output that should be much smaller and doesn't rely on a backend so you shouldn't need a 1GB artifact.

---

I see you're using Docusaurus which I had experimented with prior to the team choosing mkdocs-material, I don't recall that having such large build outputs.

EDIT: Ok, I inspected one of your workflow runs artifacts, 1GB uncompressing to 1.5GB build dir. The bulk of the fileweight is from your PDFs, GIFs and other assets that aren't likely changing often?

Since these are probably part of the Git repo already, you could exclude them and restore afterwards, or use the cache action if that's simpler? It'd shave a tonne of weight. The GIF files are quite large, you could try use MP4 or AVIF depending on the audience browsers and what's easiset for you, that should help quite a bit too.

You have 2-3GB webpack caches 😬 (I haven't looked into contents, depends how useful and timesaving that is as it eats into your 10GB CI cache for other items)