chore: merge main after RPM installer integration

Signed-off-by: Evan Lezar <elezar@nvidia.com>

Author: elezar

.agents/skills/watch-github-actions/SKILL.md

@@ -132,6 +132,18 @@ not substitute the current `main` tip or the event's older PR base SHA. Merge
 groups and manual runs use their explicit baseline. Findings are reported by
 `Reject new high or critical findings`; distinguish those from scanner failures.
 
+For `Protobuf Compatibility`, check the logged train and comparison baseline.
+Branch Checks compares the prospective merge tree with its target; Release Tag
+compares the tagged candidate with the previous stable release. Both use
+the shared `check-protobuf-compatibility` action with `nix run .#check-protobuf-compatibility -- <ref>`.
+During `0.x`, a minor train permits compatibility findings
+as warnings; a patch train or no active train rejects them. Compare the current
+train's version with the latest stable release; commit messages are irrelevant.
+Compilation, baseline, and tool errors remain fatal. The `protobuf_compatibility` suite participates in
+the `release-tag-v1` qualification profile. Failed qualification prevents stable
+publication but still allows pre-release artifacts to publish with the failure
+recorded.
+
 View logs for a specific run:
 
 ```bash

.github/actions/check-protobuf-compatibility/action.yml

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+name: Check Protobuf Compatibility
+description: Check protobuf compatibility against the target or latest stable release using the release train policy. Requires a checkout with full history and tags.
+
+inputs:
+  ref:
+    description: PR or merge-group target branch/commit, or release tag to qualify.
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - uses: ./.github/actions/setup-nix
+
+    - name: Check protobuf compatibility
+      shell: bash
+      env:
+        CHECK_REF: ${{ inputs.ref }}
+      run: |
+        nix run .#check-protobuf-compatibility --no-write-lock-file -- "$CHECK_REF"

.github/actions/pr-gate/action.yml

@@ -16,6 +16,9 @@ outputs:
   should_run:
     description: "true if the workflow should proceed, false otherwise"
     value: ${{ steps.gate.outputs.should_run }}
+  base_sha:
+    description: "Target branch commit SHA for a mirrored pull request, or empty for other events"
+    value: ${{ steps.gate.outputs.base_sha }}
   labels_json:
     description: "JSON array of PR label names for push-triggered mirror runs, or [] otherwise"
     value: ${{ steps.gate.outputs.labels_json }}
@@ -40,16 +43,19 @@ runs:
         if [ "$EVENT_NAME" != "push" ]; then
           echo "labels_json=[]" >> "$GITHUB_OUTPUT"
           echo "should_run=true" >> "$GITHUB_OUTPUT"
+          echo "base_sha=" >> "$GITHUB_OUTPUT"
           exit 0
         fi
 
         if [ "$GET_PR_INFO_OUTCOME" != "success" ]; then
           echo "labels_json=[]" >> "$GITHUB_OUTPUT"
           echo "should_run=false" >> "$GITHUB_OUTPUT"
+          echo "base_sha=" >> "$GITHUB_OUTPUT"
           exit 0
         fi
 
         head_sha="$(jq -r '.head.sha' <<< "$PR_INFO")"
+        base_sha="$(jq -r '.base.sha // empty' <<< "$PR_INFO")"
         labels_json="$(jq -c '[.labels[].name]' <<< "$PR_INFO")"
         if [ -z "$REQUIRED_LABEL" ]; then
           has_label=true
@@ -67,3 +73,4 @@ runs:
 
         echo "labels_json=$labels_json" >> "$GITHUB_OUTPUT"
         echo "should_run=$should_run" >> "$GITHUB_OUTPUT"
+        echo "base_sha=$base_sha" >> "$GITHUB_OUTPUT"

.github/workflows/branch-checks.yml

@@ -30,12 +30,33 @@ jobs:
       pull-requests: read
     outputs:
       should_run: ${{ steps.gate.outputs.should_run }}
+      base_sha: ${{ steps.gate.outputs.base_sha }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - id: gate
         uses: ./.github/actions/pr-gate
 
+  protobuf-compatibility:
+    name: Protobuf Compatibility
+    needs: pr_metadata
+    if: needs.pr_metadata.outputs.should_run == 'true'
+    runs-on: linux-amd64-cpu8
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: ./.github/actions/check-protobuf-compatibility
+        with:
+          ref: >-
+            ${{ github.event_name == 'workflow_dispatch'
+                && format('refs/remotes/origin/{0}', github.event.repository.default_branch)
+                || github.event.merge_group.base_sha
+                || needs.pr_metadata.outputs.base_sha }}
+
   mise-lockfile:
     name: mise Lockfile
     needs: pr_metadata

.github/workflows/release-tag.yml

@@ -223,11 +223,28 @@ jobs:
       checkout-ref: ${{ needs.compute-versions.outputs.source_sha }}
       conformance-artifact-prefix: openshell-conformance
 
+  protobuf-compatibility:
+    name: Protobuf Compatibility
+    needs: compute-versions
+    runs-on: linux-amd64-cpu8
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: ${{ needs.compute-versions.outputs.source_sha }}
+
+      - uses: ./.github/actions/check-protobuf-compatibility
+        with:
+          ref: refs/tags/${{ env.RELEASE_TAG }}
+
   qualification-result:
     name: Release Qualification
     if: always()
     needs:
       - compute-versions
+      - protobuf-compatibility
       - security
       - conformance-integration
       - feature-specific-integration
@@ -253,6 +270,7 @@ jobs:
           DOCKER_E2E_RESULT: ${{ needs.docker-e2e.result }}
           FEATURE_INTEGRATION_RESULT: ${{ needs.feature-specific-integration.result }}
           IS_PRERELEASE: ${{ needs.compute-versions.outputs.is_prerelease }}
+          PROTO_COMPATIBILITY_RESULT: ${{ needs.protobuf-compatibility.result }}
           SECURITY_RESULT: ${{ needs.security.result }}
           SOURCE_SHA: ${{ needs.compute-versions.outputs.source_sha }}
           VM_E2E_RESULT: ${{ needs.vm-e2e.result }}
@@ -277,6 +295,7 @@ jobs:
             echo
             echo "| Suite | Result |"
             echo "| --- | --- |"
+            echo "| Protobuf API compatibility | ${PROTO_COMPATIBILITY_RESULT} |"
             echo "| Security | ${SECURITY_RESULT} |"
             echo "| Conformance integration | ${CONFORMANCE_RESULT} |"
             echo "| Feature integration | ${FEATURE_INTEGRATION_RESULT} |"

CI.md

@@ -17,6 +17,55 @@ Manual admission does not change the bot's automatic trust policy for ready PRs.
 
 Merge queue validation is a second integration gate for `main`. After a PR has passed the required PR-head statuses, a maintainer adds it to the merge queue. GitHub creates a temporary merge-group branch that combines the latest `main`, the queued PR, and any earlier queued PRs. The same required `OpenShell / ...` status contexts are then published against the merge-group SHA before GitHub merges it.
 
+### Protobuf API compatibility
+
+`Protobuf Compatibility` runs in Branch Checks and Release Tag through the shared
+`check-protobuf-compatibility` action and Nix app. The app supplies Python, Buf,
+and Git from the flake lockfile.
+It uses Buf's `FILE` policy for the `proto/`
+module, covering SDK descriptors and extension contracts. Storage-only protobufs
+remain subject to their separate durability checks.
+
+Branch Checks compares the prospective merge tree with the PR target commit,
+so additions on the target do not look like deletions in an outdated PR. Merge
+queues use their base commit. Both paths resolve the train from tags reachable
+from that target, preventing a PR from selecting its own train. The checkout
+must contain full history and tags; the checker leaves HEAD and working files
+unchanged.
+
+The current train's version is compared with the latest stable release. During
+`0.x`, a minor increment permits breaking changes: for example, `0.2.0-pre.N`
+after stable `0.1.2`. A patch increment such as `0.1.3-pre.N` rejects them.
+Commit messages do not affect this decision. No active train also rejects
+breaking changes. Allowed findings remain visible as warnings; schema errors,
+missing baselines, merge conflicts, and tool failures always fail the check.
+
+Release Tag compares the tagged candidate cumulatively against the previous
+stable release, using the same minor-versus-patch policy. Its result is part
+of the qualification profile: failure blocks stable publication, while a
+pre-release can still publish with failed qualification recorded. This checks
+protobuf compatibility; SDK/configuration compatibility and migration review
+remain separate qualification work.
+
+Fetch the target and tags to check committed branch changes locally, replacing
+`origin/main` for another target:
+
+```shell
+git fetch origin main --tags
+nix run .#check-protobuf-compatibility -- origin/main
+```
+
+The same command accepts a release tag to qualify it against the previous stable
+release. Branch names and commit SHAs select the branch comparison instead:
+
+```shell
+nix run .#check-protobuf-compatibility -- refs/tags/v0.2.0-pre.1
+```
+
+For an intentional minor-train incompatibility, record the Buf finding,
+linked issue, consumer impact, and migration plan in the PR. Keep the finding
+visible; do not disable the job or add a broad Buf ignore rule.
+
 Windows PR checks are opt-in: add `test:windows`, then select **Re-run all jobs**
 on the current Windows MSVC run. Subsequent mirrored commits run them automatically.
 Windows checks are not required for merging and do not run in merge queues.
@@ -182,7 +231,7 @@ jobs:
 ```
 
 Set `needs: security` on a downstream promotion job to require successful scans.
-The tagged release workflow records security and integration outcomes in a
+The tagged release workflow records protobuf, security, and integration outcomes in a
 qualification job after publishing its commit-addressed OCI images. A failed
 check remains visible in the workflow, but pre-release artifact assembly and
 publication continue. Stable publication currently requires the implemented
@@ -441,7 +490,7 @@ These workflows run after merge to publish dev/tagged artifacts and verify them.
 | File | Role |
 |---|---|
 | `.github/workflows/release-dev.yml` | Publishes the rolling `dev` build on every push to `main`. Builds gateway, sandbox, and supervisor images and binaries, packages, wheels, and pushes the Helm chart as `oci://ghcr.io/nvidia/openshell/helm-chart:0.0.0-dev` (plus an immutable `0.0.0-dev.<sha>` pin). Also dispatchable manually. |
-| `.github/workflows/release-tag.yml` | Publishes tagged stable releases and manually dispatched pre-releases. Its automatic tag trigger excludes `-pre.*`. Security and integration failures do not block pre-release artifact publication. Stable publication requires the currently implemented qualification profile to pass; the summary identifies the remaining RFC 0014 coverage. |
+| `.github/workflows/release-tag.yml` | Publishes tagged stable releases and manually dispatched pre-releases. Its automatic tag trigger excludes `-pre.*`. Protobuf, security, and integration failures do not block pre-release artifact publication. Stable publication requires the currently implemented qualification profile to pass; the summary identifies the remaining RFC 0014 coverage. |
 | `.github/workflows/release-canary.yml` | Smoke-tests published dev artifacts in the `macos`, `ubuntu-deb`, `ubuntu-snap-system-docker`, `fedora`, and `kubernetes` (kind + Helm) jobs. Each job reaches its gateway and creates, exercises, and deletes a sandbox. The Snap lanes verify a compatible system Docker lifecycle and `ubuntu-snap-docker-preflight` tests fail-fast behavior when Docker is absent or supplied by the Docker snap. It runs automatically after `Release Dev` succeeds and supports manual dispatch (`gh workflow run release-canary.yml --ref <branch>`). See the `test-release-canary` skill for the playbook and local kind reproduction. |
 
 ## Required status contexts

flake.nix

@@ -60,6 +60,13 @@
           pkg-config
           # Coverage.
           lcov
+          # mise dependencies
+          mise
+          cmakeMinimal
+          zlib
+          openssl_3_5
+          xz
+          gh
           kubernetes-helm
           syft
           trivy
@@ -125,9 +132,23 @@
           firmwarePkgs = tmachineRuntimePkgs;
         };
         artifacts = pkgs.callPackage ./tests/artifacts.nix { inherit rustToolchain toolchains; };
+        checkProtobufCompatibility = pkgs.writeShellApplication {
+          name = "check-protobuf-compatibility";
+          runtimeInputs = [
+            pkgs.buf
+            pkgs.git
+          ];
+          text = ''
+            exec ${pkgs.python3}/bin/python3 ${./tasks/scripts}/check_proto_compatibility.py "$@"
+          '';
+        };
       in
       {
         apps = {
+          check-protobuf-compatibility = {
+            type = "app";
+            program = "${checkProtobufCompatibility}/bin/check-protobuf-compatibility";
+          };
           build-artifacts = {
             type = "app";
             program = "${artifacts.all}/bin/build-artifacts";