---
name: nvx-promote-openvmm-pin
description: "Pin a reviewed OpenVMM revision in NVX: verify its provenance and signature, commit the gitlink and the OpenVMM roadmap mapping, validate the exact pin, and land the OpenVMM pull request by fast-forward. Use for OpenVMM pin updates, clean replacement pull requests, source-equivalence checks, and mapping new chain commits in the OpenVMM upstream roadmap."
argument-hint: "<OpenVMM PR URL or revision> [target=origin/dev] [Draft|Ready]"
title: nvx-promote-openvmm-pin
canonical_url: https://skilld.dev/gh/microsoft/nvx/nvx-promote-openvmm-pin
last_updated: 2026-11-17T22:02:29.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/roadmap.md](https://skilld.dev/api/skills-raw/microsoft/nvx/nvx-promote-openvmm-pin/references/roadmap.md).
>
> If the user asked to install this Skill, run `npx skilld install microsoft/nvx/nvx-promote-openvmm-pin`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/nvx-promote-openvmm-pin`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/microsoft/nvx/nvx-promote-openvmm-pin) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/nvx-promote-openvmm-pin`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/nvx-promote-openvmm-pin --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/nvx-promote-openvmm-pin --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Promote An OpenVMM Pin

A promotion is two signed NVX commits directly on the target: one that moves
the `openvmm` gitlink, with only the coordinated changes that the revision
needs, then one that maps the pinned commits in the
[OpenVMM upstream roadmap](../../../doc/openvmm-upstream-roadmap.md). Never
merge or copy OpenVMM history into NVX. Moving the whole chain onto a newer
upstream `main` is [nvx-rebase-openvmm-chain](../nvx-rebase-openvmm-chain/SKILL.md)
instead. Commands use `python3`; use `python` on Windows.

## 1. State And Inputs

- Record both repositories before fetching or switching anything:
  `git status --short --branch`, `git submodule status -- openvmm`, and
  `git -C openvmm status --short --branch`. Never update, switch, reset, or
  clean a dirty repository; use an approved worktree or ask. Follow
  [the OpenVMM instructions](../../../openvmm/.github/copilot-instructions.md)
  for OpenVMM source work.
- Confirm the inputs: the OpenVMM pull request or exact revision; the target,
  `origin/dev` once `origin` resolves to `microsoft/nvx`; prerequisite
  revisions; whether it replaces an earlier pull request; and Draft or Ready,
  recommending Draft until the local gates pass.
- Fetch only the refs that you need. The tools stop on a shallow `openvmm/`;
  unshallow it from a remote that resolves to `microsoft/openvmm`.

## 2. Verify The Source

```console
python3 scripts/openvmm_pin.py source REVISION --pr NUMBER
```

It reports the full SHA, the signature, the tree, and the pull request's head,
base, state, review, and checks. Stop when the revision is missing, is not the
pull request's head, or lacks a prerequisite, and report an unverifiable
signature rather than treat it as verified. For a replacement of a reviewed
revision, `python3 scripts/openvmm_pin.py equivalence OLD NEW --old-base B
--new-base B` claims tree identity only for equal trees, and otherwise patch
equivalence from the range diff; never infer equivalence from titles or file
lists.

## 3. The Gitlink Commit

1. On a fresh branch from the refreshed target, with both repositories clean,
   run `git -C openvmm switch --detach REVISION`, and inspect
   `git diff --submodule=log -- openvmm`.
2. Compare what `nvx` copies from OpenVMM, which only the NVX CLI jobs check:

   ```console
   cargo test --locked --manifest-path nvx/Cargo.toml --no-default-features --test openvmm_vectors -- --ignored
   cargo test --locked --manifest-path nvx/Cargo.toml --no-default-features --test openvmm_cpu_profiles -- --ignored
   ```

   Each stops at its first failure. Fix it and rerun until both pass:
   - a vector file differs: copy it unchanged into
     `nvx/tests/vectors/openvmm/`, and record the revision in
     [the vectors' README](../../../nvx/tests/vectors/README.md#openvmms-vectors);
   - an excerpt is no longer a run of whole lines of its file: copy the new
     lines unchanged into it, and record the revision the same way;
   - a version differs: change it where the test names it, in
     `nvx/src/host/snapshot/manifest.rs`,
     `nvx/src/host/artifacts/compatibility.rs`, or `nvx/src/guest/time/`,
     with the code that reads what it versions;
   - a CPU profile was added, revised, or removed: update
     `nvx/src/host/cli/cpu_generations.json` and the copy in
     `scripts/nvx_tools/time_abi.py`.
3. `python3 scripts/local_gates.py --run` runs the gates that these changes
   select, such as `nvx`'s.
4. Stage only the gitlink and the coordinated changes, and commit, signed,
   when the user asked for commits or a pull request, with a subject such as
   `openvmm: pin <topic>`. Stop rather than commit unsigned, and never amend or
   rewrite a published commit without authorization.

## 4. The Roadmap Commit

1. `python3 scripts/openvmm_pin.py roadmap REVISION --target TARGET` checks
   that the previous pin is an ancestor and that the chain has no merges, and
   prints the pin's position and distance from the mapped tip, the new
   commits' positions with ready-made table rows, the earlier chain commits
   that change the same files, and whether the new commits apply to upstream
   `main`. When the previous pin is not an ancestor, it says whether the pull
   request needs a rebase onto the pin and new OpenVMM CI, or whether the
   chain itself was rebased, which nvx-rebase-openvmm-chain handles.
2. Edit the roadmap as [references/roadmap.md](https://skilld.dev/api/skills-raw/microsoft/nvx/nvx-promote-openvmm-pin/references/roadmap.md)
   describes, then check it, and the links, before committing:

   ```console
   python3 scripts/openvmm_pin.py check-roadmap --worktree
   python3 scripts/check_markdown_links.py
   git diff --check
   ```

3. Commit it, signed, with a subject such as
   `doc: map the <topic> in the OpenVMM roadmap`, and a message that names the
   new positions and the pin, says what the commits change, and gives the
   pin's distance from the mapped tip.
4. `python3 scripts/openvmm_pin.py check-branch --target TARGET` requires
   exactly these two signed commits on the target, the first changing the
   gitlink and the coordinated paths that it lists, and the second only the
   roadmap, which names the gitlink as its pin.

## 5. Validate The Exact Pin

- `python3 scripts/nvx.py verify`.
- `python3 scripts/nvx.py check-openvmm-ci --revision REVISION` records
  OpenVMM's own CI of the exact pin, which NVX CI requires
  ([OpenVMM CI](../../../doc/ci.md#openvmm-ci)) and which an OpenVMM pull
  request gets only once it is ready for review, from a `microsoft/openvmm`
  branch. A pending job is still running; a failed one needs a rerun or a fix
  in OpenVMM before the promotion can pass.
- For OpenVMM source changes made in this task, run the nested repository's
  package-scoped gates; for a pin of reviewed source, cite its exact-head
  OpenVMM evidence, and never claim checks that did not run.
- Choose runtime checks from the changed behavior:
  [nvx-run-microvm](../nvx-run-microvm/SKILL.md) for a smoke test or a
  failure, and [nvx-collect-benchmarks](../nvx-collect-benchmarks/SKILL.md)
  only when the change needs performance evidence. Report backends that you
  could not reach as left to CI.

## 6. Pull Request And Landing

- Right before pushing, fetch the target again; when it moved, rebuild both
  commits on it, derive the roadmap's numbers again, and rerun the validation.
- Fill the [pull request template](../../pull_request_template.md): the scope
  and exclusions under **What does this pull request change?**, the reason
  for the pin under **Why is this change needed?**, the validation and the
  exact head submitted to CI under **How was this change validated?**, the
  **Checklist**, and an **OpenVMM pin** section with the OpenVMM pull request
  and exact pinned SHA, the prerequisites and their states, the equivalence
  evidence in its precise term, the roadmap positions, and the landing order.
  Ask whether it is Draft or Ready.
- Follow only the run of the current head, and triage failures with
  [nvx-triage-ci-run](../nvx-triage-ci-run/SKILL.md). Its `openvmm-ci` job
  waits up to 300 minutes for OpenVMM's CI of the pin; when a required OpenVMM
  job failed, rerun it in OpenVMM, then rerun `openvmm-ci`.
- The pinned revision must be on `feature/microvm/dev` before the NVX pull
  request merges. `microsoft/openvmm` only squash-merges, so land the OpenVMM
  pull request by fast-forward, and only when the user asks:
  `python3 scripts/openvmm_pin.py land REVISION --remote REMOTE` prints the
  push, and `--push` runs it, never forced. When the branch moved past the
  pull request's base, the pull request needs a rebase, new OpenVMM CI, and a
  new promotion.

## Report

Report the source pull request and revision, the signature, the prerequisites,
the equivalence method and result, the target commit, both commits and their
files, the roadmap positions and the pin's distance from the mapped tip, the
comparisons of the vectors and CPU profiles, the local validation, the pull
request's URL and state, the exact-head workflow run, the OpenVMM pull
request's landing, and every blocked or pending gate.
