BetterDesk/docs/important/ci-troubleshooting.md

GitHub Actions — troubleshooting

Quick map of CI workflows, common failures, and local commands that mirror branch protection checks.

Required checks (branch protection)

Workflow	What it enforces	Local mirror
Version Verify	Tier 1/2 files match VERSION	node scripts/bump-version.js --verify
Secret Scan	Gitleaks + operator fingerprint ban	gitleaks detect --source . --config .gitleaks.toml and bash scripts/check-no-sensitive-paths.sh
Web Console CI	npm ci, moderate+ audit, Jest	cd web-nodejs && npm ci && npm audit --omit=dev --audit-level=moderate && npm run test:ci

Why many jobs run after one push

A single push to dev can trigger:

1. First wave: CodeQL (5 languages), Secret Scan, path-filtered CI, Version Bump (dev)
2. Second wave: Version Bump commit → Version Verify, Docker Publish (if paths match)

Merges to main add tag + release + server binary builds. This is expected; failures look worse than they are when several independent checks fail for different reasons.

Common failures

Version Verify — betterdesk.sh: expected X, got Y

Version drift in installer scripts. Fix:

node scripts/bump-version.js --sync
node scripts/bump-version.js --verify

Secret Scan — leaks found

Operator fingerprints must not appear in tracked sources:

• Lab LAN host 192.168.0.x (specific test IP blocked — use 203.0.113.x in docs/examples)
• Developer home paths under /home/... (build machines must not leak into commits)
• SSH user@internal-ip patterns from private runbooks

Sidecar binaries under betterdesk-agent-client/src-tauri/binaries/ are not committed; they are built locally/CI with go build -trimpath via build.rs.

Web Console CI — Jest failures

cd web-nodejs
npm ci
npm run test:ci

Web Console CI — npm audit

Moderate+ production vulnerabilities fail CI. Fix with dependency bumps or documented overrides in web-nodejs/package.json.

CodeQL red on Dependabot PRs

Dependabot PRs skip SARIF upload (GitHub permission limitation). Analysis still runs; push to dev/main uploads results. This is intentional in .github/workflows/codeql.yml.

Version Bump (dev) — failed to push some refs

Concurrent pushes to dev. Workflow retries with git pull --rebase. If it persists, wait for the other push to finish and re-run the failed job.

Release server — Go version mismatch

release-server.yml uses go-version-file: betterdesk-server/go.mod (same as Go Server CI).

Pre-merge checklist (dev → main)

See PRE_RELEASE_CHECKLIST.md. Minimum before opening the release PR:

node scripts/bump-version.js --verify
cd web-nodejs && npm ci && npm audit --omit=dev --audit-level=moderate && npm run test:ci
gitleaks detect --source . --config .gitleaks.toml
bash scripts/check-no-sensitive-paths.sh