Add the operator documentation site and enable docs deployment #36

agent-pi · 2026-10-17T02:42:14Z

agent-pi commented

2026-10-17 02:42:14 +00:00

The operator documentation lives in a mkdocs (Material) site: seven pages covering what xique is, container bring-up from the shipped quadlets, the full XIQUE_* reference, upgrades and forward-only migrations, backup and restore with the WAL checkpoint story, and the xique CLI. Content is derived from the repository's own artifacts and extends — without contradicting — the README's quick-start sections.

mkdocs.yml + docs/ (index, install, config, upgrade, backup, cli)
Docs deps in the dev group: mike~=2.2.0, mkdocs~=1.6.1, mkdocs-material~=9.7.7, mkdocs-git-revision-date-localized-plugin~=1.6.0
deploy-docs enabled with yunjin's release gate (github.event_name == 'release' && !github.event.release.prerelease) — the job already guards on version tags, deploys with mike to the pages branch, and uploads to git-pages for xique.marvin8.zone. First publish run is expected to fail once, pending the operator's one-time manual step
README gains a Documentation section (site link + local preview)

Verified with mkdocs build --strict and the full uv run nox suite.

Closes #16

The operator documentation lives in a mkdocs (Material) site: seven pages covering what xique is, container bring-up from the shipped quadlets, the full `XIQUE_*` reference, upgrades and forward-only migrations, backup and restore with the WAL checkpoint story, and the `xique` CLI. Content is derived from the repository's own artifacts and extends — without contradicting — the README's quick-start sections. - `mkdocs.yml` + `docs/` (index, install, config, upgrade, backup, cli) - Docs deps in the dev group: `mike~=2.2.0`, `mkdocs~=1.6.1`, `mkdocs-material~=9.7.7`, `mkdocs-git-revision-date-localized-plugin~=1.6.0` - `deploy-docs` enabled with yunjin's release gate (`github.event_name == 'release' && !github.event.release.prerelease`) — the job already guards on version tags, deploys with mike to the `pages` branch, and uploads to git-pages for xique.marvin8.zone. First publish run is expected to fail once, pending the operator's one-time manual step - README gains a Documentation section (site link + local preview) Verified with `mkdocs build --strict` and the full `uv run nox` suite. Closes #16

agent-pi added 3 commits

2026-10-17 02:42:14 +00:00

📝 docs: add the operator documentation site ff3ddc3880

👷 ci: deploy docs on release fa6b7c39cc

📝 docs: link the documentation site from the README

/ gitleaks (pull_request) Successful in 16s

Details

/ pr-review (pull_request) Successful in 2m20s

Details

/ checks (pull_request) Successful in 3m46s

Details

/ publish-container (pull_request) Has been skipped

Details

/ deploy-docs (pull_request) Has been skipped

Details

/ container (pull_request) Successful in 1m32s

Details

f5f9d02172

forgejo-actions reviewed

2026-10-17 02:44:33 +00:00

forgejo-actions left a comment

WuMing

Found 3 issue(s). See inline comments below.

## WuMing Found **3** issue(s). See inline comments below.

pylock.toml

					
				@ -163,2 +191,4 @@

				]

				[[packages]]

				name = "charset-normalizer"

security [MEDIUM]

A08 Software and Data Integrity Failures: charset-normalizer 3.5.2 appears to be a future version (current latest is 3.3.2). Combined with other future-dated packages, this suggests the lock file may have been manually tampered with or generated against an untrusted package index, compromising dependency integrity.

**security** [MEDIUM] A08 Software and Data Integrity Failures: charset-normalizer 3.5.2 appears to be a future version (current latest is 3.3.2). Combined with other future-dated packages, this suggests the lock file may have been manually tampered with or generated against an untrusted package index, compromising dependency integrity.

pylock.toml

					
				@ -307,0 +440,4 @@

				wheels = [{ url = "https://files.pythonhosted.org/packages/a0/61/5c78b91c3143ed5c14207f463aecfc8f9dbb5092fb2869baf37c273b2705/gitdb-4.0.12-py3-none-any.whl", upload-time = 2025-01-02T07:20:43Z, size = 62794, hashes = { sha256 = "67073e15955400952c6565cc3e707c554a4eea2e428946f7a4c162fab9bd9bcf" } }]

				[[packages]]

				name = "gitpython"

security [HIGH]

A03 Injection: GitPython 3.2.1 is a future/suspicious version. GitPython has known command injection CVEs (e.g., CVE-2023-41040). Verify this exact version is legitimate and patched. If this is a typo or malicious package, it could allow arbitrary code execution via crafted Git operations.

**security** [HIGH] A03 Injection: GitPython 3.2.1 is a future/suspicious version. GitPython has known command injection CVEs (e.g., CVE-2023-41040). Verify this exact version is legitimate and patched. If this is a typo or malicious package, it could allow arbitrary code execution via crafted Git operations.

pylock.toml

					
				@ -348,6 +490,13 @@ index = "https://pypi.org/simple"

				sdist = { url = "https://files.pythonhosted.org/packages/f5/08/8eea9d4b8302028f3abb2c0813953f7aec26d33b7a8960ed760e65ff29fa/idna-3.20.tar.gz", upload-time = 2026-09-17T14:11:04Z, size = 216463, hashes = { sha256 = "a7db850025b95ded1eae8a46181a1a6c56c92c96f0e2b005d9ff8dc0210cab44" } }

				wheels = [{ url = "https://files.pythonhosted.org/packages/58/a2/bb081bab032533a855d44de1d56f8e8426114ff1ba5d1f07a438a0a654f8/idna-3.20-py3-none-any.whl", upload-time = 2026-09-17T14:11:03Z, size = 69583, hashes = { sha256 = "ab7ae7122974553370f0bdb919e1a960b2cd1bc1ef0276416d896db81c14582c" } }]

				[[packages]]

security [MEDIUM]

A06 Vulnerable and Outdated Components: 'inversion' 1.0.1 is an obscure package not commonly used in documentation build chains. Verify this is not a typo for a legitimate package or a potential supply chain attack via typosquatting or dependency confusion.

**security** [MEDIUM] A06 Vulnerable and Outdated Components: 'inversion' 1.0.1 is an obscure package not commonly used in documentation build chains. Verify this is not a typo for a legitimate package or a potential supply chain attack via typosquatting or dependency confusion.

agent-pi commented

2026-10-17 02:50:13 +00:00

🔴 Not actioned — suspicious package versions in `pylock.toml`

pylock.toml (GitPython) · pylock.toml (inversion) · pylock.toml (charset-normalizer)

A03/A06/A08: GitPython 3.2.1 is a future/suspicious version… 'inversion' 1.0.1 is an obscure package… charset-normalizer 3.5.2 appears to be a future version… the lock file may have been manually tampered with…

Declined — all three are ordinary transitive dependencies of the docs toolchain this PR adds, resolved by uv from the real package index with hashes pinned in the lock file; the lock is machine-generated (uv lock / uv export), never hand-edited, and the uv-lock/uv-export pre-commit hooks keep it that way. The dependency chains, from uv tree --invert:

gitpython 3.2.1 ← mkdocs-git-revision-date-localized-plugin 1.6.0 (direct dev dep)
inversion 1.0.1 ← verspec 0.1.2 ← mike 2.2.0 (direct dev dep) — verspec/inversion are mike's known version-spec helpers
charset-normalizer 3.5.2 ← requests 2.34.2 ← mkdocs-material 9.7.7 (direct dev dep)

On the specific claims: CVE-2023-41040 (GitPython) is fixed in 3.1.32 and the resolved 3.2.1 is past it; the advisory scanners in CI (pysentry) report no known advisories for any resolved version, and zaojun's supply-chain quarantine (min-age) passes. "Future version" and "tampered lock file" are stale-index assumptions, not findings about this repository.

### 🔴 Not actioned — suspicious package versions in `pylock.toml` [`pylock.toml` (GitPython)](https://forge.marvin8.zone/marvin8/xique/pulls/36#issuecomment-5888) · [`pylock.toml` (inversion)](https://forge.marvin8.zone/marvin8/xique/pulls/36#issuecomment-5889) · [`pylock.toml` (charset-normalizer)](https://forge.marvin8.zone/marvin8/xique/pulls/36#issuecomment-5890) > A03/A06/A08: GitPython 3.2.1 is a future/suspicious version… 'inversion' 1.0.1 is an obscure package… charset-normalizer 3.5.2 appears to be a future version… the lock file may have been manually tampered with… Declined — all three are ordinary transitive dependencies of the docs toolchain this PR adds, resolved by `uv` from the real package index with hashes pinned in the lock file; the lock is machine-generated (`uv lock` / `uv export`), never hand-edited, and the `uv-lock`/`uv-export` pre-commit hooks keep it that way. The dependency chains, from `uv tree --invert`: - `gitpython 3.2.1` ← `mkdocs-git-revision-date-localized-plugin 1.6.0` (direct dev dep) - `inversion 1.0.1` ← `verspec 0.1.2` ← `mike 2.2.0` (direct dev dep) — `verspec`/`inversion` are mike's known version-spec helpers - `charset-normalizer 3.5.2` ← `requests 2.34.2` ← `mkdocs-material 9.7.7` (direct dev dep) On the specific claims: CVE-2023-41040 (GitPython) is fixed in 3.1.32 and the resolved 3.2.1 is past it; the advisory scanners in CI (`pysentry`) report no known advisories for any resolved version, and `zaojun`'s supply-chain quarantine (min-age) passes. "Future version" and "tampered lock file" are stale-index assumptions, not findings about this repository.

marvin8 approved these changes

2026-10-17 03:20:24 +00:00

Dismissed

agent-pi added 1 commit

2026-10-17 03:21:28 +00:00

📝 docs: wire the material version selector to mike

/ gitleaks (pull_request) Successful in 13s

Details

/ pr-review (pull_request) Successful in 1m11s

Details

/ checks (pull_request) Successful in 3m41s

Details