Skip to content

Latest commit

 

History

History
316 lines (223 loc) · 16 KB

ci-fix.md

File metadata and controls

316 lines (223 loc) · 16 KB
Raw

CI Fix Guide

Short link: aka.ms/ci-fix

This guide provides detailed troubleshooting instructions for the automated validation tooling checks running on Azure REST API specs PRs submitted to this repo.

If you need help with your specs PR, please first thoroughly read the aka.ms/azsdk/pr-getting-help document.

Table of Contents

Prerequisites

Most guides here require for you to have npm installed, which you can get by installing Node.js.

Checks troubleshooting guides

CredScan

This check is owned by One Engineering System. See 1ES CredScan for help.

PoliCheck

This check is owned by One Engineering System. See 1ES PoliCheck for help.

SDK azure-powershell

Important

  • This check is never blocking merging of a spec PR, even if it fails.
  • The SDK azure-powershell check is owned by the Azure.Core team, not the Azure SDK team.

The owner of this check is Yeming Liu from the Azure.Core team. Please reach out to him with any questions.

SDK azure-sdk-for-* checks, like SDK azure-sdk-for-go

Important

  • The SDK azure-sdk-for-* checks are owned by the Shanghai division of the Azure SDK team, not the core Redmond Azure SDK team.
  • Only SDK azure-sdk-for-go check failure will block a specs PR, because this check serves as a canary for the entire SDK azure-sdk-for-* group of checks.

If you have an issue or with any of checks listed in the first column of the table below:

Check name Owner
SDK azure-sdk-for-go Ray Chen
SDK azure-sdk-for-java Weidong Xu
SDK azure-sdk-for-js Qiaoqiao Zhang
SDK azure-sdk-for-net Wei Hu
SDK azure-sdk-for-net-track2 Wei Hu
SDK azure-sdk-for-python Yuchao Yan

Do the following:

  1. Attempt to diagnose the issue yourself:
    1. Look at the affected PR's checks tab for the failing check.
    2. Click on the View Azure DevOps build log for more details. link from that tab and inspect the devOps logs. For example, for SDK azure-sdk-for-go check look into the SDK azure-sdk-fo-go job, SDK Automation task logs.
  2. If your investigation denotes this is likely a bug in the check itself and not your PR, reach out to the owner of the check per the aforementioned table.

Swagger APIView

Various APIViews are generated as part of the Azure REST API specs PR build. Among these are TypeSpec and Swagger as well as any other language that is being generated in the run. When everything is successful you should see a comment box similar to the picture below showing the APIViews generated for TypeSpec or Swagger, plus all other languages being generated.

alt text

If an expected APIView was not generated, follow the step below to troubleshoot.

  • On the CI check click on details > View Azure DevOps build log for more details to view the devOps logs.
  • Investigate the CI job for the languge with error. TypeSpec and Swagger APIViews are generated as part of the AzureRestApiSpecsPipeline stage in the TypeSpecAPIView and SwaggerAPIView jobs respectively, while APIViews for other SDK languges are generated in their respective language jobs in the SDK Automation stage.
  • Ensure that all previous checks in the job are green before proceeding.

Diagnosing APIView failure for SDK Language (not Swagger or TypeSpec)

  1. Check for an unexpected skip of the Publish SDK APIView Artifact to Pipeline Artifacts and Generate SDK APIView step.
  2. Look in SDK Automation step to verify that the API token generation completed successfully.
  3. Search logs for Read Temp File
  4. Below Read Temp File find the .json object and search within to locate the apiViewArtifact property.
  5. If not present, the APIView parser for the language failed to generate the APIView Token Artifacts.
  6. Please contact APIView Support Teams Channel for assistance.

Swagger ApiDocPreview

If you see Swagger ApiDocPreview check fail with a failure like this one:

Rule Message
❌ RestBuild error "logUrl":"https://apidrop.visualstudio.com/Content%20CI/_build/results?buildId=373646&view=logs&j=fd490c07-0b22-5182-fac9-6d67fe1e939b",
"detail":"Run.ps1 failed with exit code 1 "

Refer to troubleshooting REST API documentation.

Swagger Avocado

Important

Swagger Avocado check is not a blocking for merging your PR, even if it fails. It is left to the discretion of the PR reviewer if the Avocado failure actually needs to be addressed or suppressed.

Get help fixing Avocado validation failures

Refer to Avocado README for detailed description of validations and how-to-fix guidance.

Run avocado locally

npm install -g @azure/avocado

avocado

When type avocado in command line, avocado will validate in the current directory.

Note: When running in OpenAPI spec PR pipeline, Avocado only report errors with file updates in the PR, but ignore the errors existing in base. However when running Avocado against local directory, it reports all errors existing in the files.

  • Run all specs: Clone the repo azure/azure-rest-api-specs and run "avocado" in folder azure/azure-rest-api-specs.
  • Run single service specs: create a folder specification. and move your service specs folder in specification. run "avocado"

Swagger BreakingChange and BreakingChange(Cross-Version)

See aka.ms/azsdk/pr-brch-deep. If you want a quick read, see only the summary section.

Run oad locally

To repro issues with "breaking changes" checks, you can locally run the tool that powers them: Azure/openapi-diff, aka oad:

npm install -g @azure/oad
oad compare <old-spec-path> <new-spec-path>

Please see readme for how to install or run tool in details. Refer to Oad Docs for detailed description of all oad rules.

Swagger LintDiff and Swagger Lint(RPaaS)

The LintDiff validation tool runs linting rules against specification difference. Two specifications are compared: the specification as it would be when proposed PR is merged, vs the specification as seen before the PR is merged.

Refer to openapi-authoring-automated-guidelines for detailed description of all lint rules and how-to-fix guidance. If that guidance is not enough, please also refer to the LintDiff rules.md doc. It links to .md files related to given error, containing instructions how to fix them.

To reproduce LintDiff failures locally, see CONTRIBUTING.md / How to locally reproduce a LintDiff failure occurring on a PR.

Swagger LintDiff for TypeSpec: troubleshooting guides

https://github.com/Azure/azure-rest-api-specs/wiki/Swagger-LintDiff-for-TypeSpec

Swagger ModelValidation

To repro issues with Swagger ModelValidation locally:

npm install -g oav
oav validate-example <openapi-spec-path>

Please see readme for how to install or run tool in details. Refer to Semantic and Model Violations Reference for detailed description of validations and how-to-fix guidance. Refer to Swagger-Example-Generation for example automatic generation.

Swagger PrettierCheck

First, ensure you have fulfilled Prerequisites as explained above.

To update all the spec files for a given service run the following:

# To fix all the files in the repo run from the root of the repo
cd <local_repo_clone_root>

# OPTIONAL STEP: To fix a particular service OpenAPI spec cd to that directory like
cd specification/contosowidgetmanager

# Install the dependencies to the local 'node_modules' folder.
npm install

# Run 'prettier --check' to verify the problems can be reproduced locally
npx prettier --check **/*.json

# Run 'prettier --write' to fix the problems.
npx prettier --write **/*.json

Then please commit and push changes made by prettier.

Prettier reference

Swagger SemanticValidation

To repro issues with Swagger SemanticValidation locally:

npm install -g oav
oav validate-spec <openapi-spec-path>

Please see readme for how to install or run tool in details. Refer to Semantic and Model Violations Reference for detailed description of validations and how-to-fix guidance.

Swagger SpellCheck

If you receive a spelling failure either fix the spelling to match or if there are words that need to be suppressed for your service then add the word to the override list in cspell.json. Either add to your existing section or create a new section for your specific spec or service family if the work is more generally used in lots of files under your service.

 "overrides": [
    ... example of specific file override
    {
        "filename": "**/specification/hdinsight/resource-manager/Microsoft.HDInsight/preview/2015-03-01-preview/cluster.json",
        "words": [
            "saskey"
        ]
    }
    ... example of specific service family override
    {
        "filename": "**/specification/cognitiveservices/**/*.json",
        "words": [
            "flac",
            "mpga"
        ]
    }

Words are case-insensitive so use lower case for the word list.

If you need more information on see cspell configuration.

Note: We are trying to move away from one shared dictionary file so try and avoid editing custom-words.txt in the root as it will likely go away in the future.

TypeSpec Validation

https://github.com/Azure/azure-rest-api-specs/wiki/TypeSpec-Validation

license/cla

This check is owned by One Engineering System. See 1ES GitHub inside Microsoft for help.

Suppression Process

In case there are validation errors reported against your service that you believe do not apply, we have a suppression process you can follow to permanently remove these reported errors for your specs. Refer to the suppression guide for detailed guidance.

Checks not covered by this guide

If you have an issue with a check that is not covered by this guide and the help at aka.ms/azsdk/pr-getting-help, see aka.ms/azsdk/support.

Obsolete checks

Following checks have been removed from the validation toolchain as of August 2023.

  • API Readiness Check
  • Service API Readiness Test
  • Traffic validation