feat: add advisory linter compatibility checks to CI and release

.github/workflows/ci_workflow.yml

@@ -17,3 +17,6 @@ jobs:
   linter:
     needs: [build]
     uses: ./.github/workflows/azdev_linter.yml
+  index-compatibility:
+    needs: [build]
+    uses: ./.github/workflows/index_compatibility.yml

.github/workflows/index_compatibility.yml

@@ -0,0 +1,73 @@
+name: "[auto] Index compatibility"
+permissions: {}
+on:
+  workflow_call:
+
+jobs:
+  index-compatibility:
+    name: Index compatibility
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      AZURE_CORE_COLLECT_TELEMETRY: "no"
+      PYTHONNOUSERSITE: "1"
+      PYTHONPATH: ""
+    steps:
+      - name: Initialize isolated paths
+        shell: bash
+        run: |
+          echo "COMPAT_ROOT=$RUNNER_TEMP/index-compatibility" >> "$GITHUB_ENV"
+          echo "AZURE_CONFIG_DIR=$RUNNER_TEMP/index-compatibility/azure-config" >> "$GITHUB_ENV"
+          echo "AZDEV_CONFIG_DIR=$RUNNER_TEMP/index-compatibility/azdev-config" >> "$GITHUB_ENV"
+          echo "AZURE_EXTENSION_DIR=$RUNNER_TEMP/index-compatibility/extensions" >> "$GITHUB_ENV"
+          echo "AZURE_EXTENSION_DEV_SOURCES=$RUNNER_TEMP/index-compatibility/azure-cli-extensions" >> "$GITHUB_ENV"
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          path: source
+          persist-credentials: false
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: azure-iot-cli-ext
+          path: ${{ env.COMPAT_ROOT }}/wheels
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.14"
+      - name: Check candidate against index CI
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p "$COMPAT_ROOT/reports" "$COMPAT_ROOT/run"
+          {
+            unset PYTHONHOME
+            python -m venv "$COMPAT_ROOT/venv"
+            source "$COMPAT_ROOT/venv/bin/activate"
+            cd "$COMPAT_ROOT/run"
+            git clone --quiet --depth 1 --single-branch -b dev https://github.com/Azure/azure-cli.git "$COMPAT_ROOT/azure-cli"
+            git clone --quiet --depth 1 --single-branch -b main https://github.com/Azure/azure-cli-extensions.git "$COMPAT_ROOT/azure-cli-extensions"
+            python -m pip install --upgrade pip
+            python -m pip install azdev==0.2.13 build wheel
+            azdev setup -c "$COMPAT_ROOT/azure-cli" -r "$COMPAT_ROOT/azure-cli-extensions" --debug
+            python "$GITHUB_WORKSPACE/source/scripts/check_index_compatibility.py" --work-dir "$COMPAT_ROOT"
+          } 2>&1 | tee "$COMPAT_ROOT/reports/setup.log"
+      - name: Publish compatibility summary
+        if: always()
+        shell: bash
+        run: |
+          mkdir -p "$COMPAT_ROOT/reports"
+          if [ ! -f "$COMPAT_ROOT/reports/summary.md" ]; then
+            printf '%s\n' '# Index compatibility' \
+              '**Incomplete:** setup, artifact download, or checker execution did not complete. See the job logs.' \
+              'This advisory check does not replace the required linter or gate release approval.' \
+              > "$COMPAT_ROOT/reports/summary.md"
+            echo "::error::Index compatibility did not complete; inspect the job logs."
+          fi
+          cat "$COMPAT_ROOT/reports/summary.md" >> "$GITHUB_STEP_SUMMARY"
+      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        if: always()
+        with:
+          name: index-compatibility
+          path: ${{ env.COMPAT_ROOT }}/reports/
+          if-no-files-found: error
+          retention-days: 14

.github/workflows/release_workflow.yml

@@ -50,6 +50,11 @@ jobs:
     uses: ./.github/workflows/azdev_linter.yml
     with:
       continue-on-error: ${{ github.event.inputs.continue-on-error == 'true' }}
+  index-compatibility:
+    permissions:
+      contents: read
+    needs: [build]
+    uses: ./.github/workflows/index_compatibility.yml
   int_test:
     permissions:
       contents: read

CONTRIBUTING.md

@@ -77,6 +77,34 @@ az iot central app -h
 
 If this works, then you should now be able to make changes to the extension and have them reflected immediately in your az cli.
 
+## Index-compatible lint
+
+PR CI and the release workflow run a separate **Index compatibility** job on the
+same `azure-iot-cli-ext` wheel artifact as the existing linter. It uses a clean
+environment, Azure CLI `dev`, and the merged extension-index `main` configuration.
+It does not register this repository as an extension source or copy our local
+exclusions into the installed wheel. The existing required linter is unchanged.
+
+HIGH findings, setup errors, and an empty command selection make this advisory
+check red. MEDIUM-only findings produce warnings with a green check, matching
+azdev's exit policy. Keep `index-compatibility / Index compatibility` **non-required**
+in branch protection/rulesets. Do not mask failures with `continue-on-error`.
+The release approval and drafting jobs do not depend on this advisory job; the
+overall workflow can therefore be red even when the release path succeeds.
+
+Review the completed report before approving a release, especially pending
+upstream exemption PRs. A local-only exclusion is informational, not proof that
+an exemption is justified. Fix actual command/help defects; request narrowly
+scoped upstream exemptions only when the rule does not fit the command's contract.
+Unmerged upstream PRs are never used to declare compatibility.
+
+The job summary and `index-compatibility` artifact contain HIGH/MEDIUM findings,
+local-only exclusions, raw logs, exclusion snapshots, wheel hash, and resolved
+source/CLI/index commits and tool versions. The workflow currently mirrors
+index CI's Python 3.14 and azdev 0.2.13 setup; toolchain drift fails explicitly
+instead of silently claiming parity. Use **CI Build and Test**'s manual dispatch
+to rerun it on a branch without starting a release or accessing Azure resources.
+
 ## Unit and Integration Testing
 
 Tests are organized into folders by resource in `azext_iot\tests\`: