The HugeGraph AI CI workflow owns push/PR selection and shared configuration. Its preflight checks synchronized release metadata and runs the release-tooling and selection-policy tests. The selected suites and changed paths are recorded in the job summary. A failed diff or preflight fails CI rather than skipping tests.
| Change | Default runtime tests |
|---|---|
| Repository-level README/Markdown outside tested modules | No runtime environment, Docker or custom CodeQL |
| Module README/docs, including examples and data files | Owning module, preserving documentation/example contracts |
| Python client | Client plus downstream LLM and MCP |
| Standalone LLM SDK | SDK plus downstream LLM compatibility tests |
| LLM | LLM |
| MCP | MCP |
| Root dependency/release configuration or shared CI setup | Client, SDK, LLM and MCP |
| Module CI workflow | That module and its downstream consumers |
| Docker configuration or LLM image build script | LLM |
Archive exclusions (.gitattributes) | Client archive installation guard and downstream LLM/MCP |
Ruff runs once for Python/lint/shared configuration changes using uvx, without installing application dependencies. License checks share the preflight runner. Every pyproject.toml change selects quality checks, including module and nested configurations that may change Ruff/type-check behavior. Dependency review runs for dependency changes on same-repository PRs; its token restrictions for fork PRs are unchanged. Deleted files and both sides of a rename participate in selection.
SDK changes run the SDK distribution contracts and downstream LLM adapter tests, without selecting unrelated client/MCP suites. The SDK workflow builds outside the application workspace and verifies both wheel and sdist in clean environments with only base dependencies. Offline examples and installed-wheel tests run before optional provider extras are installed. Provider contracts then share the primary-runtime SDK runner, avoiding a duplicate build and setup job.
Ordinary runs use the primary Python version defined in tool.hugegraph.ci in the root pyproject.toml. Each application module reuses one dependency environment and one HugeGraph service for its unit, integration and smoke phases. Existing coverage thresholds remain enforced. Integration tests fail if the service is unavailable. Server image digests and the /versions response are logged; versions.core must match the prepared release version. Backend capability gates remain unchanged. Following Server latest is an intentional development/test policy, so a future master image changing its core version is expected to fail this guard. The Compose HUGEGRAPH_SERVER_IMAGE override supports reproducible deployments with a verified release tag or digest without pinning the CI image.
The primary-runtime client job also verifies the actual git archive source distribution: ML and Docker remain excluded, all included workspace packages build, and uv sync --all-packages plus uv pip check validate installation. This archive check is separate from release metadata validation, which needs the complete commit tree before distribution exclusions are applied.
GitHub-owned setup-python selects the interpreter; the root uv version is installed with pip before project dependencies are managed with uv. This avoids third-party setup actions blocked by ASF‘s action allowlist. GitHub cache restores uv/pip downloads by component, Python runtime and relevant manifests; uv caches are pruned before upload. LLM jobs also cache NLTK and tiktoken data. Coverage uses sys.monitoring on the supported Python 3.12–3.14 runtimes. The older C tracer makes Jieba’s generated POS tables very slow to import on 3.12; the coverage thresholds and measured application code are unchanged. Ruff, dependency review and CodeQL each have a single job rather than a runtime matrix. New PR heads cancel superseded PR runs because each PR diff covers its whole branch. Push, scheduled and manual runs use unique run groups and are not cancelled or replaced by later runs, preserving every incremental main-push diff.
The default toolchain is uv + Ruff + ty. The uv version is defined in tool.hugegraph.ci; Ruff and ty use >= lower bounds in root development dependencies. CI reads those lower bounds and uses the same ranges. Local pre-commit hooks run Ruff through uv, without a fixed remote hook revision. The legacy formatting/lint script now uses uv/Ruff/ty instead of Black/Pylint; -b and -p retain their format/lint selections.
ty runs on the primary-runtime client, SDK, LLM and MCP jobs by default, without adding runners. MCP uses its standalone Python environment for import resolution. Application type checks retain the existing advisory status: the current ty baseline contains unresolved diagnostics, so a ty failure is visible but does not fail CI Result. Ruff and tests remain blocking. Clearing that baseline and making application type checks blocking is separate work. Release/CI scripts have a clean ty baseline and are checked as a blocking step in the existing quality runner, using their Python 3.12+ target.
Python source/stub and dependency-manifest changes select CodeQL, preserving PR/main scanning on repositories without GitHub default setup. Weekly/full and manual CodeQL runs are also supported. Module Markdown alone does not select CodeQL, but still runs its owning module's contract tests. Non-Markdown files under docs/ use the same source/data rules as other files.
When CodeQL is selected, preflight reads the repository‘s workflow metadata with actions:read. An active dynamic/github-code-scanning/codeql workflow means GitHub default setup already owns scanning, so the custom CodeQL job is skipped. This avoids both duplicate runners and GitHub’s rejection of advanced SARIF uploads while default setup is enabled. Without an active default scanner, the selected custom workflow runs normally. Metadata-query failures fail preflight. GitHub default scans keep their own triggers and check results, outside CI Result; a manual codeql selection does not force a new default-setup scan.
Use CI Result as the required branch-protection check for jobs owned by this workflow. It fails for any failed/cancelled selected job or failed preflight and accepts intentionally skipped suites. When GitHub default CodeQL setup is active, keep its emitted code-scanning check separately required because that scan deliberately remains outside CI Result. Without default setup, the selected custom CodeQL job is aggregated into CI Result. Replace old per-module matrix check names in repository rules when adopting this workflow; code changes here do not update GitHub rules.
The regular test workflows are reusable and receive configuration from preflight. They do not independently trigger duplicate runs. PR labeling and other repository administration workflows retain their existing triggers.