Skip to content

docs: show how to point uvx at an index hosting kirocrew - #33143

Merged
bolichen97 merged 1 commit into
mainfrom
fix/23488-uvx-mirror-index
Nov 8, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/23488-uvx-mirror-index

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An admin who copies the enterprise MCP governance guide's pypi registry example learns what fails when uvx has no index hosting the kirocrew wheel, and how to point uvx at one.

kirocrew is not on public PyPI, so the guide's pypi entries launch as uvx kirocrew@<version> <subcommand> and fail unless uvx can reach an index that hosts the wheel. The guide states that requirement in one sentence before the example, but never shows how to make uvx use such an index, and two reporters on #23488 read the example as working by default.

Builds on #28559 by @cruisercohen.

Why it matters

The reader is an enterprise admin configuring a governed fleet. Copying the example as written leaves every session without the Kiro Crew tools those entries serve, while kiro-cli mcp list still shows the servers as accepted, so nothing points at the cause. With the requirement stated but no way to meet it, the admin has to work out uv's index configuration alone, and the obvious attempt with the project's own release index fails.

Not a goal

  • Choosing a supported launch route other than a published wheel in an index (the locally installed command, a local endpoint): that stays a maintainer decision.
  • The server table and the JSON list: main already lists all eleven servers.
  • Publishing kirocrew to public PyPI.

What changed (motivation → approach → change)

An admin who follows the guide without an index gets servers that are accepted and never start, and the guide gives no way to set one up. The fix documents both, through uv's own configuration, which works however kiro-cli reads the registry entry.

In docs/guides/enterprise-mcp-governance.md, right after the registry example:

Added What it tells the admin
a note on the failure the servers show in kiro-cli mcp list, then uvx fails with kirocrew was not found in the package registry
a uv.toml [[index]] snippet where the file lives on each OS, and the release CDN's index as the URL, with the channel picked from the fleet's version (stable for no prerelease suffix, insider for rc, nightly for .dev), since each version is listed only on the channel that released it; it needs ignore-error-codes = [403] because the CDN answers 403 for packages it does not host, and uv stops at a 403
an own-index paragraph for clients that cannot reach the CDN; PyPI stays the fallback for the wheel's dependencies, default = true would drop it, and the index belongs in uv, not in registryBaseUrl

The sentence before the example and the "Known limitation" section point at that setup rather than saying the organisation must mirror the wheel.

Backwards compatibility

Compatible: documentation only; no code, setting or interface changes.

Removes nothing: the only reworded sentences still state the same requirement (an index hosting the wheel) and no instruction is dropped.

Tests

N/A, documentation only. ./scripts/docs-lint.sh and python3 scripts/docs_lint.py --test pass.

Manual verification

Checked with uv 0.12.3 on Linux, uvx kirocrew@0.12.0 --help, each uv.toml in an isolated XDG_CONFIG_HOME/uv/ (the ~/.config/uv/uv.toml path) with an isolated uv cache:

uv.toml Result
none fails: kirocrew was not found in the package registry (the note's text)
the guide's snippet (release CDN stable index, ignore-error-codes = [403]) resolves kirocrew from the CDN and its dependencies from PyPI; CLI help prints
the CDN index without ignore-error-codes fails: uv stops at the CDN's 403 and resolves no dependency
a local index serving only the v0.12.0 release wheel (404 for anything else) resolves; dependencies come from PyPI
the same index with default = true fails: no dependency can resolve

The CDN's three channel indexes list separate wheels: stable ends at 0.12.0, insider at 0.12.0rc10, nightly at a 0.13.0.dev build, so a version from one channel is missing from the others. The launch form (uvx kirocrew@<version> <subcommand>) comes from the two reports on #23488. https://pypi.org/pypi/kirocrew/json still answers 404.

Screenshots / video

N/A, documentation only: no frontend file changes.

Related Issues

Closes #23488

Sibling sweep

N/A: a docs: PR, not a fix or revert.

Pattern harvest

N/A: a docs: PR, not a fix or revert.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

This contribution is made under the project's Apache-2.0 license (see the Licensing section of CONTRIBUTING.md).

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 8, 2026 11:50
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 8, 2026
@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 0896f6342e6992452ecb0b6f412bd721a9570b23 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 0896f6342e6992452ecb0b6f412bd721a9570b23 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 0896f6342e6992452ecb0b6f412bd721a9570b23 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Docs only. The uv.toml route is the right layer for this, and nothing is taken away.

[DESIGN-REVIEWED] 0896f63

Description read

[DESCRIPTION-READ] 29c430b7dca6e549b0bcab748842616d8192e2e619d952f66421c4e81c13dd36

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 0896f6342e6992452ecb0b6f412bd721a9570b23 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0896f63

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 0896f6342e6992452ecb0b6f412bd721a9570b23 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 0896f6342e6992452ecb0b6f412bd721a9570b23 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 0896f63

Verdict parsed from the review's SHA-scoped output markers for commit 0896f6342e6992452ecb0b6f412bd721a9570b23.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 0896f6342e6992452ecb0b6f412bd721a9570b23 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 8, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 8, 2026 12:14
The enterprise MCP governance guide says its pypi registry example needs
an index hosting the kirocrew wheel, but never shows how to make uvx use
one, and a reader who copies the example sees accepted servers that
never start. Describe that failure after the example, show the uv index
configuration for the release CDN's per-channel index (picked by the
fleet's version, since each version is listed only on the channel that
released it; the CDN answers 403 for packages it does not host, so uv
needs ignore-error-codes to move on to PyPI) or an organisation's own
index, and say why default = true would drop PyPI for the wheel's
dependencies.

Builds on #28559.
@bolichen97
bolichen97 force-pushed the fix/23488-uvx-mirror-index branch from d89c98d to 0896f63 Compare November 8, 2026 13:56
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • fixed span=4737fe61afe4

fixed in 0896f63: the guide no longer says one CDN index hosts every published wheel. It says each version is listed only on the channel that released it, and picks the URL's channel by the fleet's version: stable for no prerelease suffix, insider for an rc version, nightly for a .dev version.
Grounded in release.yml (a prerelease tag publishes <base>rcN on insider, a bare tag publishes on stable), nightly.yml (<base>.dev<stamp>) and publish-cli.yml (each run writes only feed/<channel>/simple/; the stable-to-insider mirror never writes the insider index), and in the live indexes (stable ends at 0.12.0, insider at 0.12.0rc10, nightly at a 0.13.0.dev build).
[operator: bolichen97]

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 8, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. On this head the review checked several things. The stable / insider (rc) / nightly (.dev) rule matches the release and nightly workflows, and each channel publishes only its own simple index. ignore-error-codes = [403] matches how the CDN answers a missing key. The uv.toml paths are uv's standard user config locations. The install.md#installing-a-published-wheel-with-pip anchor resolves, and the failure text matches the reports on #23488.
Well done: each claim in the new text has a row in the manual verification table, including the two negative cases (no ignore-error-codes, and default = true losing the PyPI fallback). The guide then warns readers away from both.

  • Optional: run one governed session with the uv.toml snippet in place and confirm the servers start through a Kiro CLI registry launch. The current proof runs uvx directly.
  • Optional: after this merges, close #28559 as superseded by this PR, with credit to its author.

@bolichen97
bolichen97 merged commit ce36f8e into main Nov 8, 2026
99 checks passed
@bolichen97
bolichen97 deleted the fix/23488-uvx-mirror-index branch November 8, 2026 15:08
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(enterprise-mcp-governance): the documented kirocrew registry entry can't launch, because kirocrew isn't on PyPI

2 participants