Explain how to handle skipped required checks

[jsoref]

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://github.com/github/docs/blob/2289ca70c7ec7ec1b81eafdb333cd0157fafaa08/content/github/administering-a-repository/troubleshooting-required-status-checks.md

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

A section should be added that explains that if people use paths for a required check, they'll want to add a second copy of the check with paths-ignore for the same content that just returns true.

Additional information

It's a FAQ in https://github.community

[lecoursen]

It's a FAQ in https://github.community

Hi @jsoref, could you link to one or more examples? Thanks!

[jsoref]

https://github.community/t/github-pull-request-is-waiting-for-required-status-checks-even-with-ci-skip-in-commit-message/827
https://github.community/t/github-actions-checks-when-not-in-triggers/194399
https://github.community/t/pr-stuck-waiting-for-checks-which-should-be-skipped/18485
https://github.community/t/feature-request-conditional-required-checks/16761
https://github.community/t/skip-ci-ci-skip-dont-work-if-a-repo-has-branch-protection-enabled-travis-ci-pull-request/15326
https://github.community/t/github-actions-and-required-checks-in-a-monorepo-using-paths-to-limit-execution/16586
https://github.community/t/dealing-with-checks-enforced-by-branch-protection-but-skipped-by-path-filter/18451
https://github.community/t/monorepos-and-limiting-workflows-by-changed-files-required-status-checks/136030
https://github.community/t/force-succeed-required-workflow-when-skipped/124055
https://github.community/t/path-filtering-on-required-pull-request-checks/18402

[lecoursen]

Thanks @jsoref! This sounds like a great plan that will address a very common source of confusion. You or anyone else is welcome to open that PR! ⚡

[Fran-Rg]

Because I landed here from google search, the documented solution is here: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/troubleshooting-required-status-checks#handling-skipped-but-required-checks

[TWiStErRob]

@jsoref I'm trying to research this topic, but all the links in #8926 (comment) are dead. Where can I find those old forum topics?

[jsoref]

Dunno. They did a real number in github.community in their migration. It didn't occur to me when I filed this that I'd need to quote the full contents of each item here...

[TWiStErRob]

I tried searching for some slugs without dashes but no results, not even on Google.

[jsoref]

@TWiStErRob IA appears to have at least some of them..., here's an example: https://web.archive.org/web/20200928033538/https://github.community/t/github-pull-request-is-waiting-for-required-status-checks-even-with-ci-skip-in-commit-message/827

[TWiStErRob]

Oo nice, forgot about that.

[cb-shivamagarwal]

May someone please review and merge - #24182 ?

In the section handling-skipped-but-required-checks, the docs do not shed any light for the case mentioned below:

When someone sends a pull request that changes the files listed under paths and also changes a file that is not listed under paths-ignore in the other workflow. In such a case, both workflows must be executed and the associated status checks must pass in order to merge the PR.

This PR adds documentation for that

[minherz]

The proposed solution is confusing because it causes the check list to display the same workflow / job names twice when changes in a pull request fit both filters (e.g. paths and paths-ignore).
So far the solution looks more like a problem mitigation. It would be nice having a smarter check list execution logic for required checks. Is it possible to mark the execution is completed when the check is skipped due to filtering?

[jsoref]

Sadly, this repository is focused on documentation. For technical implementation details, there are two main paths that externals (like us) can take:

• https://support.github.com/
• https://github.com/community/community/discussions

I sympathize with your concerns, but it's much easier for me to get documentation added than to get implementation changed.

[JJ-connect]

The proposed solution has been removed (as of this commit).

What is now the recommended way of dealing with this?

The docs seem to imply that using a conditional rather than path/branch filtering is the correct way to deal with this.
If this is recommended, could there be an example to show how it works?

PS: does anyone have a link for this issue (as a technical implementation) to follow up there too?

[jsoref]

When a workflow is run as a required workflow it will ignore all the filters in the on: section, for example: branches, branches-ignore, paths, types etc. The required workflow will run only for the pull_request and pull_request_target default events. For more information on default activity types, see "Events that trigger workflows."

https://docs.github.com/en/actions/using-workflows/required-workflows#prerequisites

[minherz]

Great! If previously it was inconvenient, now it became a nonsense.

There are two problems with the document (hence, implicitly, implementation of the "required check" feature) that @jsoref referenced:

1. There is no such thing as required workflow. At least I cannot find one when I am configuring setting for a branch. What it does allow me is to setup a required check. It is very confusing and misleading, especially when there are more than one check (a.k.a. job) in a workflow (a.k.a. file).
2. Ignoring any filters when a job is marked as required, means breaking a contract of the job configuration. It makes the "required check" feature confusing, introduces longer (than expected) check running times and may introduce extra costs.

Such decisions should be published for community feedback before they make intro the product.

[TWiStErRob]

For 1), @minherz scroll up on the linked page for an explanation. Also notice the banner:

Note: Required workflows for GitHub Actions are in private beta and are not available for new signups.

[jsoref]

@TWiStErRob I don't believe they existed when I opened this issue.

[minherz]

@TWiStErRob you are right, it was my mistake. I am biased in that when I read public documentation it describes functionality that is available to public.

It is good to see that the original problem still exists in its original form. It is bad that there is no solution to it.