ADR-0025: Microsoft Teams and Zendesk actions
- Status: Accepted
- Date: 2026-09-21
- Amends: ADR-0020 and ADR-0022, which name Slack and email as the only actions a rule ReleaseFlow sets off itself may take. Microsoft Teams now joins them, for the reason those documents give rather than despite it.
Context
ADR-0024 added the two wiki destinations. These are the last two of the old project's eight: a message through a Microsoft Teams Workflows callback, and an article in a Zendesk Help Center.
They are opposites, and almost every decision below follows from that. Teams tells people something: the message scrolls away and nothing is left to be found again. Zendesk publishes a page: an article that exists cannot be unsaid, and a second one is somebody's problem.
Decision
- Teams may be fired by a schedule; Zendesk may not. The rule ReleaseFlow has always
kept is that a rule nobody is watching may only tell people something. Until now that
was written as "Slack and email", because those were the only two that qualified. Teams
qualifies for exactly the same reason, so the check is now
tellsPeople(actionType)and the rule says what it always meant. Zendesk joins GitHub Releases, Notion, Confluence and the public changelog on the other side: a cron rule would publish the same article every cycle, and a reminder works on a release that is not published yet. - The Teams callback is guarded by its shape, not by an allowlist. The URL a Workflows
flow hands out is both the destination and the credential — the
sigin its query is what authorises the call. Slack's deployment allowlist cannot be copied here, because the host label belongs to the customer's own environment and no list could name it in advance. SoTeamsWebhookUrlrequires HTTPS, one label beneath.environment.api.powerplatform.com, the default port or 443, no credentials or fragment, the Workflows trigger path (with or without the newercu/{unit}/segment), and asigparameter with a value. It is checked when the action is written and again before every delivery. Because the URL is a credential, a redirect is never followed: following one would hand the signature to another origin. - The query is split and walked, not matched. A pattern asked to find
sig=inside a string somebody else chose is the shape of problem the ReDoS fixes in this repository already removed once. Splitting on&and comparing is plainer and cannot back-track. - Teams is sent plain text, and the request is what gets measured. One JSON object with
a
textfield holdingRelease <version>, a newline, and the note. Teams bounds the request rather than the message, so the payload is written first and its 28 KiB is measured on those bytes — the check still happens before any network call. - A Zendesk delivery is two calls, and they are allowed to fail differently. A
short-lived token from
POST /oauth/tokenswith the client-credentials grant andwritescope, then the article. Nothing is published until the second call, so every way the first can fail isFAILED, including a server error and a lost connection: repeating it cannot duplicate an article that was never created, and calling itUNKNOWNwould ask a person to confirm a duplicate that cannot exist. The second call follows the usual rule — 4xx including 429 isFAILED, 5xx or a lost connection isUNKNOWN. A 2xx that names no article isUNKNOWNtoo, because nobody can say from it whether one was written. - The token lives for one delivery. It is a local variable, fetched per delivery, never cached, stored, or logged. Caching it would mean holding somebody's credential across deliveries for a saving nothing here needs.
- A Zendesk subdomain is one DNS label, not a URL.
ZendeskTenantlower-cases it and accepts only a label, so the only address the action can reach ishttps://{subdomain}.zendesk.com— there is nothing in the configuration for a request to point elsewhere. Section and user-segment ids are positive numbers this side can still count with. - The article is the HTML the application already trusts.
MarkdownHtml.render, as the public changelog and the Confluence action use, bounded at 1,000,000 bytes before the token is even asked for. The article is created withdraft=falseandnotify_subscribers=false, and carriesuser_segment_idonly when one is configured: ReleaseFlow does not decide to email a customer's subscribers. - Two more stand-in base URLs, for the same reason as the last slice.
releaseflow.automation.teams.api-base-urlreplaces only the origin and keeps the path and the signature;releaseflow.automation.zendesk.api-base-urlreplaces the help centre's origin. Both are empty by default, both leave the validation in place, and neither changes what is recorded: a Zendesk link is thehtml_urlZendesk itself returned.
Consequences
- A rule fired by a schedule can now reach a chat, which is what most people wanted from
one. The invariant is looser in letter and identical in spirit; the conflict message,
AGENTS.md, and the README all say the new list. - A Zendesk OAuth failure reads as
FAILEDeven when Zendesk was the thing that broke. That is deliberate and is the one place in automation where a 5xx does not becomeUNKNOWN;zendesk_auth_unavailabledistinguishes it from a refusal for anybody reading run history. - An article, like a Notion or Confluence page, cannot be found again: nothing searches
for one a previous run wrote. An unconfirmed delivery stays
UNKNOWNuntil a person accepts that a second article may appear. - Eight kinds of Action now share one
configurationobject and one pair of secret columns. That has held without strain, but Zendesk's four keys are the most any action carries; a ninth destination needing more is where a typed, per-type configuration would finally earn its place. - Only Teams Workflows in the commercial cloud. Office 365 connectors are being retired, and sovereign clouds, Graph bots, and Entra-authenticated flows have different addresses and a different credential lifecycle.