Document gh-aw-agents federated credential for AzDO /review trigger

[kubaflo]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Summary

Docs-only. Documents the federated credential the AzDO /review trigger actually needs after #35951 / #35974 moved the AZDO_TRIGGER_* secrets to the gh-aw-agents GitHub environment.

Why

After #35974 added environment: gh-aw-agents to the trigger-review job in review-trigger.yml, the job's GitHub OIDC sub claim changed from repo:dotnet/maui:ref:refs/heads/main to repo:dotnet/maui:environment:gh-aw-agents. The AzDO managed identity has no federated credential for that subject, so the "Exchange for AzDO Token" step fails with:

AADSTS700213: No matching federated identity record found for presented
assertion subject 'repo:dotnet/maui:environment:gh-aw-agents'

The token exchange fails before the pipeline is queued, so every /review adds the s/agent-review-in-progress label and the always() cleanup step immediately removes it (the review never starts). Example: run 27772519590 on #21169.

.github/docs/trigger-azdo-pipeline-setup.md was stale — it documented an example environment named azdo-trigger, not the real gh-aw-agents.

Changes (.github/docs/trigger-azdo-pipeline-setup.md)

• Replace the stale azdo-trigger environment example with the required gh-aw-agents federated credential, noting it is mandatory because the AZDO_TRIGGER_* secrets are environment-scoped.
• Rewrite the "Subject claim mapping" note: a GitHub environment: claim overrides the branch/PR claim, so this is the subject trigger-review presents today.
• Add an AADSTS700213 troubleshooting row and a lessons-learned item.

The actual fix (out of scope for this PR — infra)

This PR only documents the credential; an operator with Azure access still needs to create it:

az identity federated-credential create \
  --name github-actions-env-gh-aw-agents \
  --identity-name id-maui-azdo-trigger \
  --resource-group rg-maui-automation \
  --issuer "https://token.actions.githubusercontent.com" \
  --subject "repo:dotnet/maui:environment:gh-aw-agents" \
  --audiences "api://AzureADTokenExchange"

Note

🤖 This PR (description and doc changes) was generated by GitHub Copilot CLI on behalf of @kubaflo.

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 36000

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 36000"