Azure DevOps | Stoaken Integrations

What it does

Pull in CI: an azure-pipelines.yml step runs stoaken export --check on pull request builds.
Push on publish: a standard Stoaken webhook posts to an Incoming WebHook service connection. Azure's endpoint for this is public, needs no authorisation, and takes any JSON body (docs). The pipeline filters on type: release.published, exports the tokens, pushes stoaken/tokens and opens a pull request with az repos pr create.

Before you start

A Stoaken API key and a stoaken.config.json with exports (see /docs/cli).
Brand Admin in Stoaken, on the Team plan.
Project Administrator in Azure DevOps, to add a service connection.

Setup

Go to Project settings > Service connections > New > Incoming WebHook. Set WebHook Name to stoaken and Service connection name to StoakenWebhook. Leave Secret and Http Header empty: Azure checks HMAC-SHA1 signatures, and Stoaken signs with Standard Webhooks.
Commit azure-pipelines.yml to the default branch (template: azurePipelines() in src/lib/integrations/pipelines.ts), create the pipeline from it, and add the secret variable STOAKEN_TOKEN:

trigger: none
resources:
  webhooks:
    - webhook: Stoaken
      connection: StoakenWebhook
      filters:
        - path: type
          value: release.published
steps:
  - checkout: self
    persistCredentials: true
  - script: npx --yes stoaken@latest export --check
    condition: eq(variables['Build.Reason'], 'PullRequest')
    env:
      STOAKEN_TOKEN: $(STOAKEN_TOKEN)
  # … export, push stoaken/tokens, az repos pr create

On the repository's security settings, give <Project> Build Service Contribute, Create branch and Contribute to pull requests.
For pull request checks on Azure Repos, add a Build validation branch policy that uses this pipeline. GitHub and Bitbucket repositories use the YAML pr trigger instead.
In Stoaken, choose Add a webhook, set Send as to Stoaken event, use the address https://dev.azure.com/ORG/_apis/public/distributedtask/webhooks/stoaken?api-version=6.0-preview, and pick Release published.

Configuration

Payload fields can be used in the YAML as ${{ parameters.Stoaken.data.version }}. Don't reference a whole object, because that produces invalid YAML and the run won't start.
Secret variables must be mapped into each step with env:, as the template does.

Try it

Send test should get 200. It doesn't start a run, because the filter needs release.published.
Send a sample with Release published starts a run and, if anything changed, opens a pull request.

Troubleshooting

500 "Cannot find webhook for the given webHookId": the pipeline YAML isn't on the default branch yet, or it has never run. Run it once by hand.
Run starts, push fails (403): the Build Service lacks Contribute or Create branch.
PR step fails: az repos pr create works for Azure Repos only. For a GitHub-hosted repository, use the GitHub guide.

Limits

No signature check on Azure's side: anyone with the webhook address can start a run, which then only exports the live release. Treat the address as a secret.
Azure DevOps Services. Server 2020.1 and later have the same webhook resource but use their own host name.