More consise Status Check Guide needed for most common use case

[tomsit-ionos]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks

What part(s) of the article would you like to see updated?

I'd love make a contribution via PR but i'm afraid this is beyond my time capacity!

Part 1 Howto Simple Use Case

After running into problems to to config required checks for PRs, i think i understood now how it works -- but only after piecing together the info points spread over several articles, discussions (thank u https://github.com/orgs/community/discussions/26698#discussioncomment-3252954). It would be great to have a simple HowTo for the most common scenario which IMO is: "I have 1..n jobs that need to be OK before the PR can get merged"

The howto is then thus:

1. create or edit ur ruleset, e.g. https://github.com/ionos-cloud/platform-iam-identity-policy-service/settings/rules/new?target=branch
2. check Require status checks to pass
3. Click Add Check
4. type in the value of jobs.<job-id>.name (does this default to jobs.<job-id> ?)
5. add it

My Gotcha:
The name of the check is not the same string that is shown on the PR UI, e.g.

It took me a while to get this even after reading the discussion linked above.

I'm guessing the UI string depends how the Job was actually run (nested/triggered by other WFs !? plz expand), e.g. in my case i have 2 jobs in the same WF named ci, which is the reason this is indicated by the leading ci/. However, this must not be added to the name of the status check added in step (4), nor the (push) suffix which probably indicates the triggering event.

The above will probably help more simpletons like me to get things done w/o having to read thru lots of docs.

Part 2 Expand on the Simple Use Case to lead into the more general impl and additional use case of the API

The following is under the assumption that i deducted the following, w/o really delving into the API docs. Reading those might have made things clearer, but i also guess, that a user that just wants to use GH thru web UI and git CLI like me and wants to config the most common use case, is not going to read it either, if not explicitly asked to do so. So let's lower the bar for this!

1. Status Checks (SCs) can be set thru the API, where the SC is identified by its name.
2. These SC.names are ref'ed in the config of step (4). Note that this ref is by name only! So if the name of the job is changed in the WF file it must also be updated manually on the ruleset settings page. Otherwise u get stuck with an unmet SC and wont be able to merge the PR.
3. when jobs are triggered against the head of a PR, they automatically add the SC with their name and outcome, thus possibly satisfying the configured req. check

Something along these lines should be written up concisely in the docs -- starting with the most simple use case that every1 understands and then expand to the general mechanism that Apps and external apps can use but that is also used by the actions themselves, ie a TLDR and its Long Story.

My guess is, that this requires some restructuring of the pages/texts to really make it shine and be easily understandable -- just my 2cts.

Additional information

PS: HUBBERS!! This is the github/docs open source repo. You may want to open an issue in the internal-only github/docs-content repo instead.

i dont understand who u are addressing with the bolded text. Are HUBBERS GH employes that have access to the github/docs-content repo ? -- because i dont. I initially thought that HUBBERS are all github users....

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[tomsit-ionos]

the HowTO should be ideally linked to on the settings page

[nguyenalex836]

@tomsit-ionos Thank you for opening an issue! I'll get this triaged for review ✨