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/my-repo/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....

---

Addition by a GitHub docs team member

Outline content plan

1. Update About status checks to add a brief new section on "Commit statuses" and how they are different from status checks, linking out to REST API endpoints for commit statuses.
2. Update Troubleshooting required status checks with additional information, including:
   • Workflows don't run on PRs with merge conflicts. You must resolve the conflict and then workflows will be triggered (see https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request).
   • If you change the name of a workflow or a job within a workflow, then you must also update the required status checks for the branch to use the new name. If you do not do this, then pull requests will have an unmet required status check and this will block PRs from being merged.
   • Explain how to identify the workflow that corresponds to a status check.
3. Update Require status checks before merging to explain that the name of status checks shown in this view is name for the job or, when no job name is defined, the job identifier. For example, the required status check defined for the content-lint-markdown.yml file is lint-content (no name defined). The required status checks from the test.yml file are the matrix-defined names.

How to find the workflow that corresponds to a status check

1. In the status checks box of the PR, click Details to show the workflow log file.
2. In the left side bar, is a list of the job names for each job defined in that workflow.
3. Scroll to the bottom of the log file so you can see the "Run details" part of the left side bar, to display a link to the workflow file.
4. Click the link to display the workflow file.

The names for status checks shown on a pull request are formed as follows:

• workflow name / job name (trigger)
• The job name may be defined by a matrix.
• Where name is not defined, the id is used (see Setting an ID for a job and Setting a name for a job)

Examples:

• https://github.com/github/docs/blob/main/.github/workflows/os-ready-for-review.yml generates status checks of the form: OS Ready for review / Request a review from the docs-content team (pull_request_target)
• https://github.com/github/docs/blob/main/.github/workflows/test.yml generates status checks of the form: Test / assets (pull requests) where assets is part of a matrix.

[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 ✨

[felicitymay]

@tomsit-ionos - thank you for your patience waiting for a response to this issue ✨

Many thanks for taking the time to write a detailed description of the problem you encountered and suggestions for how to address it. Your thoughtfulness is much appreciated.

I've taken a look at the article you mentioned and a few related ones, and have some suggestions on how someone could make some simple updates to help users learn how status checks work.

Outline content plan

1. Update About status checks to add a brief new section on "Commit statuses" and how they are different from status checks, linking out to REST API endpoints for commit statuses.
2. Update Troubleshooting required status checks with additional information, including:
   • Workflows don't run on PRs with merge conflicts. You must resolve the conflict and then workflows will be triggered (see https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request).
   • Explain how to identify the workflow that corresponds to a status check.
3. Update Require status checks before merging to explain that the name of status checks shown in this view is name for the job or, when no job name is defined, the job identifier. For example, the required status check defined for the content-lint-markdown.yml file is lint-content (no name defined). The required status checks from the test.yml file are the matrix-defined names.

How to find the workflow that corresponds to a status check

1. In the status checks box of the PR, click Details to show the workflow log file.
2. In the left side bar, is a list of the job names for each job defined in that workflow.
3. Scroll to the bottom of the log file so you can see the "Run details" part of the left side bar, to display a link to the workflow file.
4. Click the link to display the workflow file.

The names for status checks shown on a pull request are formed as follows:

• workflow name / job name (trigger)
• The job name may be defined by a matrix.

Examples:

• https://github.com/github/docs/blob/main/.github/workflows/os-ready-for-review.yml generates status checks of the form: OS Ready for review / Request a review from the docs-content team (pull_request_target)
• https://github.com/github/docs/blob/main/.github/workflows/test.yml generates status checks of the form: Test / assets (pull requests) where assets is part of a matrix.