Migrate API Doc Preview

[danieljurek]

Migrate API Doc Preview to Azure DevOps pipeline that invokes a pipeline in the docs org, waits for the pipeline to finish, then report status via a commit status:

The commit status is updated as relevant things happen in the orchestration pipeline. Commit statuses are not check statuses so they may not work for required pipelines. At this point docs is not a required check so this is not a hindrance.

It is possible to set check statuses, but those aggregate to check suites in "strange" ways in the GitHub UI and so are not advisable because they can cause confusion.

Tests

Success

Sample build: https://dev.azure.com/azure-sdk/internal/_build/results?buildId=5078254&view=logs&j=407c8e09-36f7-5b0b-5ef1-9a46f011447b&t=b7bb9f89-2346-5516-09dd-ff209e5433c8

Sample docs build: https://dev.azure.com/apidrop/Content%20CI/_build/results?buildId=551536&view=logs&j=fd490c07-0b22-5182-fac9-6d67fe1e939b

Docs preview: https://review.learn.microsoft.com/en-us/rest/api/azure-rest-preview/?branch=preview%2FAzure%2Fazure-rest-api-specs%2Fpr%2F35018%2Fbuild%2F5078254%2Fattempt%2F1&view=azure-rest-preview

Orchestration pipeline failure

Sample build: https://dev.azure.com/azure-sdk/internal/_build/results?buildId=5078190&view=logs&j=407c8e09-36f7-5b0b-5ef1-9a46f011447b

Docs pipeline failure

Sample build: https://dev.azure.com/azure-sdk/internal/_build/results?buildId=5078217&view=logs&j=407c8e09-36f7-5b0b-5ef1-9a46f011447b

Corresponding docs build: https://dev.azure.com/apidrop/Content%20CI/_build/results?buildId=551533&view=results

Timeout

Looking over history about 10% of runs last longer than 9 minutes which could put us close to a 10 minute timeout for the AzureCLI@2 token.

I initially thought timeout could be tested by finding a spec that took a "long time" time to build in another pipeline run. That did not prove to be the case. Time variation appears to depend on other factors.

To test timeout, I added code to throw an exception in api-doc-preview-wait.mjs after 3 minutes. This way the script would "timeout" and fail and the pipeline task's retryCountOnTaskFailure would kick in and retry the task.

Example pipeline run: https://dev.azure.com/azure-sdk/internal/_build/results?buildId=5078095&view=logs&j=407c8e09-36f7-5b0b-5ef1-9a46f011447b&t=b7bb9f89-2346-5516-09dd-ff209e5433c8

The log shows the script failing, AzureCLI@2 re-authorizing and then continuing:

[openapi-pipeline-app]

Next Steps to Merge

Next steps that must be taken to merge this PR:

• ❌ The required check named Protected Files has failed. Refer to the check in the PR's 'Checks' tab for details on how to fix it and consult the aka.ms/ci-fix guide

[openapi-pipeline-app]

PR validation pipeline restarted successfully. If there is ApiView generated, it will be updated in this comment.

[github-actions]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

Language	API Review for Package
Swagger	Microsoft.Contoso

[mikeharder]

in comments

[danieljurek]

This can merge.