fix(docs): deploy on tag push, not on the unreachable workflow_call branch

[danielmeppiel]

TL;DR

v0.9.4 docs auto-deploy SKIPPED silently. Deploy Docs / build ran successfully, Deploy Docs / deploy was skipped, and the public site still serves <0.9.4 content. Root cause: in a reusable workflow, github.event_name reflects the caller's event, not 'workflow_call'. Detect the tag-push context directly. Manual workflow_dispatch triggered to ship v0.9.4 docs in parallel with this PR.

Problem (WHY)

#953 fixed the missing release: published event for bot-cut releases by switching from a release-event trigger to a direct workflow_call invocation in build-release.yml. That was correct and necessary. But the gate inside docs.yml was never updated.

The if: on the upload-pages-artifact step and the deploy job reads:

github.event_name == 'workflow_dispatch' ||
(github.event_name == 'release' && github.event.release.prerelease == false) ||
(github.event_name == 'workflow_call' && inputs.is_prerelease == false)

Per GitHub Actions docs, in a reusable workflow the github context is inherited from the caller. When build-release.yml (triggered by push of a v* tag) calls docs.yml, inside docs.yml:

• github.event_name == 'push' (NOT 'workflow_call')
• github.ref_type == 'tag'
• inputs.is_prerelease == false

None of the three branches match. Build runs (no condition gates the build job). Upload + deploy skip.

Verified

$ gh run view 24978104679 --json jobs --jq '.jobs[] | "\(.name): \(.status)/\(.conclusion)"' | grep Deploy
Deploy Docs / build:  completed/success
Deploy Docs / deploy: completed/skipped

$ curl -s https://microsoft.github.io/apm/reference/package-types/ | grep -oE 'id="[^"]*"'
id="apm-package-apm-directory"
id="skill-bundle-skillmd-at-root"
# (no 'skill-collection-...' anchor -- 0.9.4 content not deployed)

This is silently broken since #953 landed and is the second-order regression of the same root cause class — github.event_name not behaving like authors expect under workflow_call (#953 was the inverse: author expected release: published to fire under bot-cut releases).

Approach (WHAT)

Detect the tag-push context directly. Both build-release.yml:639 and build-release.yml:646 already gate the workflow_call invocation on github.ref_type == 'tag' && needs.create-release.outputs.is_prerelease != 'true', so the inputs are trustworthy.

- (github.event_name == 'workflow_call' && inputs.is_prerelease == false)
+ (github.event_name == 'push' && github.ref_type == 'tag' && inputs.is_prerelease == false)

Applied identically on the upload-artifact step and the deploy job.

Implementation (HOW)

.github/workflows/docs.yml — two surgical replacements + a comment explaining the gotcha for the next reader. Net: +13/-2.

Trade-offs

Choice	Why	Why not other
Detect via event_name == 'push' && ref_type == 'tag'	Robust, no new inputs, matches the only legitimate caller path	Could check inputs.* directly, but inputs always have defaults so no way to detect "actually invoked via workflow_call"
Keep workflow_dispatch and release: published branches	Manual deploy + human-cut releases still work	Could remove them, but they're cheap safety nets

Validation

• Manual gh workflow run docs.yml --ref main triggered (run 24983311706) to ship v0.9.4 docs in parallel with this PR landing
• Confirmed live site missing skill-collection-* anchor before fix
• After merge: next stable release tag triggers automatic docs deploy with no skipped step

How to test

After merge, on the next stable release (or by re-tagging a no-op patch):

1. gh run view <build-release-run> --json jobs --jq '.jobs[] | select(.name | startswith("Deploy Docs")) | "\(.name): \(.conclusion)"'
2. Expect: Deploy Docs / build: success AND Deploy Docs / deploy: success (not skipped).

Related

• fix(ci): deploy docs after bot-cut releases via workflow_call #953 — original release: published workaround that introduced this latent gap
• docs(readme): add 'Coming from npx skills add?' conversion block #980 — README change blocked behind v0.9.4 docs landing the #skill-collection anchor

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[Copilot]

Pull request overview

Fixes a regression where the docs site was not deploying after bot-cut releases once the docs workflow was converted to a reusable workflow (workflow_call). The change updates the deploy gating to correctly detect the tag-push caller context so upload + deploy run for stable tag releases again.

Changes:

• Update .github/workflows/docs.yml upload/deploy if: gates to detect stable tag-push context (caller event) instead of an unreachable workflow_call branch.
• Add explanatory comments in docs.yml documenting the reusable-workflow github.* context gotcha.
• Add an Unreleased changelog entry describing the docs auto-deploy fix.

Show a summary per file

File	Description
CHANGELOG.md	Adds an Unreleased “Fixed” entry for the docs auto-deploy regression.
.github/workflows/docs.yml	Adjusts artifact upload + deploy conditions to run on stable tag-based release calls and documents the workflow_call context behavior.

Copilot's findings

• Files reviewed: 2/2 changed files
• Comments generated: 1