vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-03-12 07:20:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: fix broken links checker and add CI docs (#13041)

Browse Source 
- Fix zh-CN/vps.md broken links (/railway  /install/railway)
- Add docs/ci.md explaining CI pipeline
- Add Experiments group to docs.json navigation
This commit is contained in:
max
2026-02-09 18:30:05 -08:00
committed by GitHub
parent ead3bb645f
commit 67d3bab890
4 changed files with 67 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
docs/ci.md
View File

@@ -1,155 +1,63 @@
---
title: CI Pipeline
description: How the OpenClaw CI pipeline works and why jobs are ordered the way they are.
description: How the OpenClaw CI pipeline works
---
# CI Pipeline
OpenClaw uses a tiered CI pipeline that fails fast on cheap checks before
running expensive builds and tests. This saves runner minutes and reduces
GitHub API pressure.
The CI runs on every push to `main` and every pull request. It uses smart scoping to skip expensive jobs when only docs or native code changed.
## Pipeline Tiers
## Job Overview
```
Tier 0 — Scope detection (~12 s, free runners)
docs-scope → changed-scope
| Job | Purpose | When it runs |
| ----------------- | ----------------------------------------------- | ------------------------- |
| `docs-scope` | Detect docs-only changes | Always |
| `changed-scope` | Detect which areas changed (node/macos/android) | Non-docs PRs |
| `check` | TypeScript types, lint, format | Non-docs changes |
| `check-docs` | Markdown lint + broken link check | Docs changed |
| `code-analysis` | LOC threshold check (1000 lines) | PRs only |
| `secrets` | Detect leaked secrets | Always |
| `build-artifacts` | Build dist once, share with other jobs | Non-docs, node changes |
| `release-check` | Validate npm pack contents | After build |
| `checks` | Node/Bun tests + protocol check | Non-docs, node changes |
| `checks-windows` | Windows-specific tests | Non-docs, node changes |
| `macos` | Swift lint/build/test + TS tests | PRs with macos changes |
| `android` | Gradle build + tests | Non-docs, android changes |
Tier 1 — Cheapest gates (parallel, ~43 s)
check-format secrets
## Fail-Fast Order
Tier 2 — After format (parallel, ~2 min)
check-lint code-analysis
Jobs are ordered so cheap checks fail before expensive ones run:
Tier 3 — Build (~3 min)
build-artifacts release-check
1. `docs-scope` + `code-analysis` + `check` (parallel, ~1-2 min)
2. `build-artifacts` (blocked on above)
3. `checks`, `checks-windows`, `macos`, `android` (blocked on build)
Tier 4 — Tests (~5 min)
checks (node tsgo / test / protocol, bun test)
checks-windows (lint / test / protocol)
## Code Analysis
Tier 5 — Platform (most expensive)
macos (TS tests + Swift lint/build/test)
android (test + build)
ios (disabled)
```
The `code-analysis` job runs `scripts/analyze_code_files.py` on PRs to enforce code quality:
## Dependency Graph
- **LOC threshold**: Files that grow past 1000 lines fail the build
- **Delta-only**: Only checks files changed in the PR, not the entire codebase
- **Push to main**: Skipped (job passes as no-op) so merges aren't blocked
```
docs-scope ──► changed-scope ──┐
│
check-format ──► check-lint ──►├──► build-artifacts ──► release-check
├─► code-analysis ►│ └──► checks-windows
├──► checks
├──► macos
└──► android
secrets (independent)
```
When `--strict` is set, violations block all downstream jobs. This catches bloated files early before expensive tests run.
## Job Details
### Tier 0 — Scope Detection
| Job | Runner | Purpose |
| --------------- | --------------- | ----------------------------------------------------------------------- |
| `docs-scope` | `ubuntu-latest` | Detects docs-only PRs to skip heavy jobs |
| `changed-scope` | `ubuntu-latest` | Detects which areas changed (node/macos/android) to skip unrelated jobs |
### Tier 1 — Cheapest Gates
| Job | Runner | Purpose |
| -------------- | ----------------- | ------------------------------------------- |
| `check-format` | Blacksmith 4 vCPU | Runs `pnpm format` — cheapest gate (~43 s) |
| `secrets` | Blacksmith 4 vCPU | Runs `detect-secrets` scan against baseline |
### Tier 2 — After Format
| Job | Runner | Depends on | Purpose |
| --------------- | ----------------- | -------------- | ----------------------------------------------------------- |
| `check-lint` | Blacksmith 4 vCPU | `check-format` | Runs `pnpm lint` — cleaner output after format passes |
| `code-analysis` | Blacksmith 4 vCPU | `check-format` | Checks LOC thresholds — accurate counts need formatted code |
### Tier 3 — Build
| Job | Runner | Depends on | Purpose |
| ----------------- | ----------------- | ----------------------------- | -------------------------------- |
| `build-artifacts` | Blacksmith 4 vCPU | `check-lint`, `code-analysis` | Builds dist and uploads artifact |
| `release-check` | Blacksmith 4 vCPU | `build-artifacts` | Validates npm pack contents |
### Tier 4+ — Tests and Platform
| Job | Runner | Depends on | Purpose |
| ---------------- | ------------------ | ------------------------------------------------ | ------------------------------------------------------ |
| `checks` | Blacksmith 4 vCPU | `check-lint`, `code-analysis` | TypeScript checks, tests (Node + Bun), protocol checks |
| `checks-windows` | Blacksmith Windows | `build-artifacts`, `check-lint`, `code-analysis` | Windows-specific lint, tests, protocol checks |
| `macos` | `macos-latest` | `check-lint`, `code-analysis` | TS tests + Swift lint/build/test (PR only) |
| `android` | Blacksmith 4 vCPU | `check-lint`, `code-analysis` | Gradle test + build |
## Code-Analysis Gate
The `code-analysis` job runs `scripts/analyze_code_files.py` on PRs to catch:
1. **Threshold crossings** — files that grew past 1000 lines in the PR
2. **Already-large files growing** — files already over 1000 lines that got bigger
3. **Duplicate function regressions** — new duplicate functions introduced by the PR
When `--strict` is set, any violation fails the job and blocks all downstream
work. On push to `main`, the code-analysis steps are skipped (the job passes as a
no-op) so pushes still run the full test suite.
### Excluded Directories
The analysis skips: `node_modules`, `dist`, `vendor`, `.git`, `coverage`,
`Swabble`, `skills`, `.pi` and other non-source directories. See the
`SKIP_DIRS` set in `scripts/analyze_code_files.py` for the full list.
## Fail-Fast Behavior
**Bad PR (formatting violations):**
- `check-format` fails at ~43 s
- `check-lint`, `code-analysis`, and all downstream jobs never start
- Total cost: ~1 runner-minute
**Bad PR (lint or LOC violations, good format):**
- `check-format` passes → `check-lint` and `code-analysis` run in parallel
- One or both fail → all downstream jobs skipped
- Total cost: ~3 runner-minutes
**Good PR:**
- Critical path: `check-format` (43 s) → `check-lint` (1m 46 s) → `build-artifacts` → `checks`
- `code-analysis` runs in parallel with `check-lint`, adding no latency
## Composite Action
The `setup-node-env` composite action (`.github/actions/setup-node-env/`)
handles the shared setup boilerplate:
- Node.js 22 setup
- pnpm via corepack + store cache
- Optional Bun install
- `pnpm install` with retry
The `macos` job also caches SwiftPM packages (`~/Library/Caches/org.swift.swiftpm`)
to speed up dependency resolution.
This eliminates ~40 lines of duplicated YAML per job.
## Push vs PR Behavior
| Trigger | `code-analysis` | Downstream jobs |
| -------------- | ----------------------------- | --------------------- |
| Push to `main` | Steps skipped (job passes) | Run normally |
| Pull request | Full analysis with `--strict` | Blocked on violations |
Excluded directories: `node_modules`, `dist`, `vendor`, `.git`, `coverage`, `Swabble`, `skills`, `.pi`
## Runners
| Name | OS | vCPUs | Used by |
| ------------------------------- | ------------ | ----- | ---------------- |
| `blacksmith-4vcpu-ubuntu-2404` | Ubuntu 24.04 | 4 | Most jobs |
| `blacksmith-4vcpu-windows-2025` | Windows 2025 | 4 | `checks-windows` |
| `macos-latest` | macOS | — | `macos`, `ios` |
| `ubuntu-latest` | Ubuntu | 2 | Scope detection |
| Runner | Jobs |
| ------------------------------- | ----------------------------- |
| `blacksmith-4vcpu-ubuntu-2404` | Most Linux jobs |
| `blacksmith-4vcpu-windows-2025` | `checks-windows` |
| `macos-latest` | `macos`, `ios` |
| `ubuntu-latest` | Scope detection (lightweight) |
## Local Equivalents
```bash
pnpm check # types + lint + format
pnpm test # vitest tests
pnpm check:docs # docs format + lint + broken links
pnpm release:check # validate npm pack
```

20
docs/docs.json
View File

@@ -1232,6 +1232,16 @@
{
"group": "Release notes",
"pages": ["reference/RELEASING", "reference/test"]
},
{
"group": "Experiments",
"pages": [
"experiments/onboarding-config-protocol",
"experiments/plans/cron-add-hardening",
"experiments/plans/group-policy-hardening",
"experiments/research/memory",
"experiments/proposals/model-config"
]
}
]
},
@@ -1751,6 +1761,16 @@
{
"group": "发布说明",
"pages": ["zh-CN/reference/RELEASING", "zh-CN/reference/test"]
},
{
"group": "实验性功能",
"pages": [
"zh-CN/experiments/onboarding-config-protocol",
"zh-CN/experiments/plans/cron-add-hardening",
"zh-CN/experiments/plans/group-policy-hardening",
"zh-CN/experiments/research/memory",
"zh-CN/experiments/proposals/model-config"
]
}
]
},

4
docs/zh-CN/vps.md
View File

@@ -19,8 +19,8 @@ x-i18n:
## 选择提供商
- **Railway**（一键 + 浏览器设置）：[Railway](/railway)
- **Northflank**（一键 + 浏览器设置）：[Northflank](/northflank)
- **Railway**（一键 + 浏览器设置）：[Railway](/install/railway)
- **Northflank**（一键 + 浏览器设置）：[Northflank](/install/northflank)
- **Oracle Cloud（永久免费）**：[Oracle](/platforms/oracle) — $0/月（永久免费，ARM；容量/注册可能不太稳定）
- **Fly.io**：[Fly.io](/install/fly)
- **Hetzner（Docker）**：[Hetzner](/install/hetzner)

3
package.json
View File

@@ -36,11 +36,10 @@
"build:plugin-sdk:dts": "tsc -p tsconfig.plugin-sdk.dts.json",
"canvas:a2ui:bundle": "bash scripts/bundle-a2ui.sh",
"check": "pnpm format:check && pnpm tsgo && pnpm lint",
"check:docs": "pnpm format:docs:check && pnpm lint:docs && pnpm docs:build",
"check:docs": "pnpm format:docs:check && pnpm lint:docs && pnpm docs:check-links",
"check:loc": "node --import tsx scripts/check-ts-max-loc.ts --max 500",
"dev": "node scripts/run-node.mjs",
"docs:bin": "node scripts/build-docs-list.mjs",
"docs:build": "cd docs && pnpm dlx --reporter append-only mint broken-links",
"docs:check-links": "node scripts/docs-link-audit.mjs",
"docs:dev": "cd docs && mint dev",
"docs:list": "node scripts/docs-list.js",