📖 [Docs]: GitHub Actions standard warns that a skipped dependency skips the job

[Marius Storhaug (MariusStorhaug)]

The GitHub Actions standard now warns about a failure mode that produces no error, no red check, and no linter finding: a job never runs because a dependency was skipped. Authors connecting conditional jobs with needs: can now identify the risk before it silently stops a workflow.

New: Guidance for skipped dependencies

Structure work into jobs and steps now explains that a job whose needs: list contains a skipped job is skipped too, while the workflow can still report success. It shows when to remove an impossible dependency edge, when an optional dependency needs an explicit status check, and why a bare always() or !cancelled() can permit work after a failed dependency.

The guidance also explains why neither actionlint nor zizmor detects this reachability problem, so authors must read needs: and if: together.

---

Technical details

• Added the skipped-dependency subsection to src/docs/Coding-Standards/GitHub-Actions.md, beside the existing job-structure guidance.
• A follow-up commit corrects the optional-dependency example so build must succeed and integration-tests may be skipped but not fail; it also states that the actionlint evidence used a complete workflow matching the example's shape.
• The examples and statements are based on the real publishing failure tracked by Publish the documentation site on push and schedule again PSModule/Process-PSModule#486 and its correction in PSModule/docs#107.
• Implementation plan progress: the guidance and the toolchain conclusion in Warn that a skipped job in needs skips the dependent job #149 are complete; no plan steps moved to follow-up work.

Changed surface	Standards checked	Framework docs checked	Result
src/docs/Coding-Standards/GitHub-Actions.md	Markdown, Documentation, and Natural Language	None (this page is the framework documentation for this subject)	Aligned

Issue convergence sweep: reviewed open MSXOrg/docs issues concerning the GitHub Actions standard and job structure. #149 is the only issue fully satisfied by this diff.

Relevant issues (or links)

• Resolves Warn that a skipped job in needs skips the dependent job #149

Related work

• References Publish the documentation site on push and schedule again PSModule/Process-PSModule#486
• References PSModule/docs#107

[Copilot]

Pull request overview

This PR updates the GitHub Actions coding standard to document the “skipped dependency” failure mode where a job listed in needs: is skipped (due to an if:), causing downstream jobs to be skipped while the workflow run still reports success.

Changes:

• Adds a new subsection under “Structure work into jobs and steps” explaining skip-propagation through needs: and why it can remain invisible in checks.
• Introduces avoid/correct YAML examples for (1) removing dead needs: edges and (2) using status functions with explicit dependency-result checks for optional dependencies.
• Clarifies that the pinned linting toolchain does not detect this class of reachability issue.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Suppressed comments (4)

src/docs/Coding-Standards/GitHub-Actions.md:262

• The opening claim reads as unconditional, but the subsection later explains that using status functions (for example always() / !cancelled()) can override the default skip propagation. Adding “By default,” keeps the statement accurate and avoids an internal contradiction in the same subsection.

A job whose `needs:` list contains a **skipped** job is skipped too. This is not
about failure: `if:` on a job is implicitly wrapped in `success()`, and
`success()` is false when a dependency was *skipped*, exactly as it is when one
failed. So adding `needs:` to a job that may not run silently makes every
dependent job conditional on it as well.

src/docs/Coding-Standards/GitHub-Actions.md:281

• In the avoid snippet, publish declares needs: [build, lint] but the snippet itself doesn’t define a build job. That makes the example invalid as written (copy/paste would fail for an unrelated reason), which distracts from the skipped-dependency trap you’re trying to demonstrate.

  publish:
    needs: [build, lint]
    if: github.event_name != 'pull_request'    # runs only when NOT a pull request

src/docs/Coding-Standards/GitHub-Actions.md:284

• This comment says the symptom happens “On push”, but the conditions shown are “non-PR events” in general (github.event_name != 'pull_request'). Broadening the wording makes the example accurate for workflow_dispatch, schedule, etc. as well.

    # On push, lint is skipped, so publish is skipped — and the run still
    # reports success. A real occurrence froze a documentation site for two
    # weeks while every run was green.

src/docs/Coding-Standards/GitHub-Actions.md:318

• In GitHub Actions expressions, job IDs containing a hyphen can’t be accessed with dot notation in a needs context. Use bracket notation so the example works for integration-tests consistently.

  if: ${{ !cancelled() && needs.build.result == 'success' && needs.integration-tests.result != 'failure' }}