Document required permissions and report pretty errors when missing

[jsoref]

Here's a run of a workflow based on the https://github.com/martinthomson/internet-draft-template: https://github.com/check-spelling-sandbox/draft-mpic/actions/runs/14170845689

---

Build Succeeded

✅ draft-westerbaan-alldispatch-mpic

Build Failed

❌ all

❌ step 'ghpages-push' failed

---

• It looks like this workflow only needed contents: write (see https://github.com/check-spelling-sandbox/draft-mpic/commit/6af7f0f9a7e72f22497861038d8dc8144ef08906), but the error reporting is really unhelpful.

• Ideally the README file for this repository would say what permissions are required for this action

• Ideally this action would handle the cases where required permissions are missing and produce GITHUB_STEP_SUMMARY output that includes an explanation of what permissions are missing / roughly how to add them.

[jsoref]

Another case: https://github.com/check-spelling-sandbox/internet-draft-template/actions/runs/14171037329/job/39694680330

The log says:

git fetch -qf origin gh-pages:gh-pages
fatal: couldn't find remote ref gh-pages
make: [lib/ghpages.mk:60: fetch-ghpages] Error 128 (ignored)
Error: No gh-pages branch, run `make -f lib/setup.mk setup-ghpages` to initialize it.

Ideally the pretty message would mention that it's possible someone made a fork of only the head branch and didn't include the gh-pages branch, in which case the person who owns the forked repository should either:

• disable the workflow (if they don't want to maintain a gh-pages branch)
• do something like: git fetch upstream gh-pages:gh-pages && git push origin gh-pages

And again, this output should be shown in GITHUB_STEP_SUMMARY

[martinthomson]

A reasonable request, but not a simple one. I don't have any concrete ideas on how to do this without disruptive changes. The current setup for GITHUB_STEP_SUMMARY relies on a wrapper that make runs. The errors you refer to are not coming from within that wrapper, but from make itself. That's why failures tend to accumulate. The second error is a separate thing. I like this issue as a means of tracking the request, but there might be individual fixes for these issues, separate from the nice reporting.

[jsoref]

That's fine. I figured make was doing the hard work.

I'm not in a hurry. For reference, for my own (composite) action, I have an extra step that runs in certain cases and generates extra output: https://github.com/check-spelling/check-spelling/blob/8da53591073357945b37cc7737985004badf09e8/action.yml#L464-L474 https://github.com/check-spelling/check-spelling/blob/8da53591073357945b37cc7737985004badf09e8/diagnose-failed-checkout.sh

For other cases, the internal code is responsible for things, for example:

https://github.com/check-spelling/check-spelling/blob/8da53591073357945b37cc7737985004badf09e8/unknown-words.sh#L173-L187