fix(ci): deploy docs after bot-cut releases via workflow_call

[danielmeppiel]

TL;DR

The Deploy Docs workflow listens for release: published, but that event never fires when the release is created by GITHUB_TOKEN — a documented Actions safeguard against recursion. The CI/CD Pipeline cuts releases as github-actions[bot], so docs haven't auto-deployed since v0.9.3 (and won't going forward). This PR fixes it by converting docs.yml into a reusable workflow and invoking it directly from the release job.

Problem (WHY)

• v0.9.3 published at 2026-04-26T12:04:31Z (release)
• API check: repos/microsoft/apm/actions/runs?event=release returns 0 runs in the last 30 days, across the entire repo
• Last actual Deploy Docs deploy was a manual workflow_dispatch on 2026-04-23 (3 days before v0.9.3)
• Root cause: release was authored by github-actions[bot] (confirmed via API). GitHub Actions documents: "events triggered by the GITHUB_TOKEN [...] will not create a new workflow run"

So the published site at https://microsoft.github.io/apm still serves pre-0.9.3 content despite a successful release.

Approach (WHAT)

Convert docs.yml into a reusable workflow (workflow_call) and have the CI/CD Pipeline's create-release job invoke it directly via a new deploy-docs job. No new credentials; no event-loss risk.

Why this over the alternatives

Approach	New creds?	Coupling	Failure modes
workflow_call from release job (this PR)	None	Explicit, intentional	Direct invocation — no event-loss risk
workflow_run event chain	None	Implicit, name-based ("CI/CD Pipeline")	Always runs the default-branch workflow file (cut-at-tag pinning gotcha); fires on every CI/CD completion → must filter conclusion + branch + detect "was a release cut"
Fine-grained PAT in release step	PAT secret	Loose (release event)	Tied to a user; expires (max 1y); Microsoft PAT policies still apply; rotation burden
GitHub App token	App install	Loose (release event)	App install on a Microsoft-org repo requires security review
Fold docs into CI/CD Pipeline	None	Maximally tight	Loses PR-time docs build; can't deploy docs without re-running CI

The workflow_call approach is the right level of coupling for this case: the docs site is part of the release artifact, not an independent observer, so the release pipeline declaring "publishing a release includes deploying its docs" is correct domain modeling.

Implementation (HOW)

docs.yml — add workflow_call trigger with an is_prerelease input, extend the existing gating conditions on build and deploy jobs to honor it. Keep release: published, pull_request, and workflow_dispatch triggers as-is for backward compatibility (human-cut releases, PR builds, manual re-publish all continue to work).

build-release.yml — add a deploy-docs job that needs: [create-release], gated to stable tags only (is_prerelease != 'true'), and uses: ./.github/workflows/docs.yml with is_prerelease: false. Job declares its own permissions: (contents: read, pages: write, id-token: write) — these bound what the called workflow can request.

deploy-docs:
  name: Deploy Docs
  needs: [create-release]
  if: github.ref_type == 'tag' && needs.create-release.outputs.is_prerelease != 'true'
  uses: ./.github/workflows/docs.yml
  permissions:
    contents: read
    pages: write
    id-token: write
  with:
    is_prerelease: false

Trade-offs

• Trades event-driven loose coupling for explicit pipeline composition. For a single repo where the release pipeline owns end-to-end shipping (artifacts + docs + downstream packages), composition is the right call. If APM later grows to N independent post-release consumers maintained by different teams, revisit (App-token + release: published becomes more attractive at that scale).
• release: published trigger retained. Slightly more surface area in the trigger list, but it's a safety net — human-cut releases (rare but possible) still deploy docs without further work.

Validation evidence

• actionlint clean for the changes (only pre-existing SC2086 shellcheck infos elsewhere in build-release.yml)
• YAML loads cleanly via yaml.safe_load; both jobs lists parse as expected:
  • docs.yml jobs: build, deploy
  • build-release.yml jobs: ..., create-release, deploy-docs, gh-aw-compat, ...
• ASCII-only (verified: 0 non-ASCII bytes added in docs.yml)
• All existing trigger paths preserved (PR-time build, manual workflow_dispatch, human-cut release: published)

How to test

1. Backfill v0.9.3: trigger Deploy Docs via workflow_dispatch on main to republish the v0.9.3 docs site immediately (no merge needed).
2. End-to-end on next release: cut the next tag (v0.9.4 or later); confirm a Deploy Docs job now appears as a child of the CI/CD Pipeline run, and https://microsoft.github.io/apm reflects the new version within minutes.
3. PR build still works: this PR itself should trigger a Deploy Docs build-only run if it touches docs/** (it doesn't, so no run expected — matches current behavior).
4. Prerelease gating: cut any prerelease tag (vX.Y.Z-rc1); confirm deploy-docs job is skipped (if: evaluates false).

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

[Copilot]

Pull request overview

This PR fixes docs not deploying after bot-created releases by converting the existing Deploy Docs workflow into a reusable workflow (workflow_call) and explicitly invoking it from the release pipeline after a stable tag release is published.

Changes:

• Added workflow_call support to docs.yml with an is_prerelease input and updated gating so stable workflow_call runs upload artifacts and deploy.
• Added a deploy-docs job in build-release.yml that calls docs.yml after create-release, skipping prereleases.

Show a summary per file

File	Description
.github/workflows/docs.yml	Adds workflow_call entrypoint + prerelease-aware gating for upload/deploy.
.github/workflows/build-release.yml	Invokes docs deployment explicitly after create-release for stable tags.

Copilot's findings

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