hmbown--codewhale/docs/CNB_MIRROR.md

CNB Cool mirror

cnb.cool/codewhale.net/codewhale is a one-way mirror of this GitHub repository for users on networks where GitHub is slow or blocked (primarily mainland China). The mirror receives every push to main, every fix/*, rebrand/*, and work/v* branch used for first-party release work, and every v* release tag.

Provenance

GitHub is the sole canonical source. All releases, tags, and source code originate at github.com/Hmbown/CodeWhale. The CNB mirror is a read-only replica maintained by the Sync to CNB workflow — it exists solely to serve users behind GFW-blocked or slow GitHub connections.

Every CNB release includes codewhale-artifacts-sha256.txt — a SHA256 manifest of the CNB-built Linux x64 binaries, generated from the same source commit that is tagged on GitHub. (CNB builds from source, so these checksums cover the CNB-built artifacts, not GitHub's release assets.) Verify a downloaded binary against it:

# Verify a downloaded CNB binary against the CNB manifest
sha256sum -c codewhale-artifacts-sha256.txt

How it works

The mirror is maintained by the Sync to CNB GitHub Actions workflow:

• Trigger: push to main, push of any v* tag, release work branches matching work/v*, first-party fix and rebrand branches matching fix/* and rebrand/*, or workflow_dispatch for manual recovery.
• Auth: HTTPS basic auth as user cnb with the CNB_GIT_TOKEN repository secret as the password.
• Scope: only the ref that triggered the run is pushed. Tag pushes push exactly that tag. Branch pushes mirror main, first-party fix/*/rebrand/* branches, or explicitly matched release branches. Other feature branches and dependabot refs are intentionally not mirrored.
• Concurrency: runs are serialized via a cnb-sync concurrency group so the back-to-back main push and tag push from auto-tag.yml cannot race each other.
• Retry: each push is retried up to three times with linear backoff (5s, 10s) before the workflow gives up.

CNB pipeline configuration is also source-controlled in GitHub at /.cnb.yml. This is deliberate: the sync workflow force-mirrors GitHub refs to CNB, so pipeline files created only on the CNB side will be overwritten. Submit .cnb.yml changes through GitHub PRs and let the one-way mirror carry them to CNB.

CNB tag releases

When CNB receives a v* tag, the root .cnb.yml tag pipeline builds Linux x64 release assets from source and publishes a CNB release with:

• codewhale-linux-x64
• codewhale-tui-linux-x64
• codewhale-artifacts-sha256.txt

This gives users who can reach CNB but not GitHub a CNB-native release path. GitHub remains the canonical macOS/Windows release matrix; the CNB tag pipeline is the China-friendly Linux x64 fallback.

CNB Linux CI and release preflight

First-party fix/* and rebrand/* branches are mirrored to CNB so the heavy Linux Rust gates run on Tencent-hosted runners instead of GitHub Actions:

• ./scripts/release/check-versions.sh
• cargo fmt --all -- --check
• cargo check --workspace --all-targets --locked
• cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
• cargo test --workspace --all-features --locked
• cargo build --release --locked -p codewhale-cli -p codewhale-tui
• node scripts/release/npm-wrapper-smoke.js

Release branches matching work/v* also run ./scripts/release/publish-crates.sh dry-run. GitHub Actions keeps the cheap drift/fmt statuses plus the macOS and Windows jobs that CNB cannot replace.

Verifying the mirror after a release

After release.yml completes for a vX.Y.Z tag, the CNB mirror should have both the new commit on main and the new tag:

# Quick check: does the new tag exist on CNB?
git ls-remote https://cnb.cool/codewhale.net/codewhale.git \
    refs/tags/vX.Y.Z

# Quick check: is CNB's main at the same commit as origin/main?
gh_main=$(git ls-remote https://github.com/Hmbown/CodeWhale.git refs/heads/main | awk '{print $1}')
cnb_main=$(git ls-remote https://cnb.cool/codewhale.net/codewhale.git refs/heads/main | awk '{print $1}')
test "$gh_main" = "$cnb_main" && echo "in sync" || echo "DIVERGED: gh=$gh_main cnb=$cnb_main"

Or check the workflow run directly:

gh run list --workflow=sync-cnb.yml --repo Hmbown/CodeWhale --limit 5

If the most recent run for the release tag is success, the mirror caught it. If it's failure, fix or re-run the mirror workflow before directing users to the mirrored tag.

Manual fallback

Manual mirror repair is maintainer-only. Do not put PATs in remote URLs or publish force-push recipes in contributor-facing docs. Use the configured GitHub Actions secret and the workflow dispatch path whenever possible.

Re-trigger the workflow manually

If the workflow is healthy but happened to fail on the release run (e.g. a transient CNB outage that's since cleared), retrigger it without pushing anything:

gh workflow run sync-cnb.yml --repo Hmbown/CodeWhale

workflow_dispatch runs against the workflow's default branch (main), so this will sync the current main to CNB. To re-sync a specific tag, the manual git push cnb path above is the way.

Rotating CNB_GIT_TOKEN

If the workflow starts failing with auth errors and the token has expired:

1. Log in to cnb.cool and generate a new personal access token with repo (push) scope.
2. Update the CNB_GIT_TOKEN repository secret:

   gh secret set CNB_GIT_TOKEN --repo Hmbown/CodeWhale
   

3. Re-trigger the workflow on a recent commit:

   gh workflow run sync-cnb.yml --repo Hmbown/CodeWhale
   

4. Confirm the run succeeds via gh run list --workflow=sync-cnb.yml.

Binary release assets and codewhale update

CNB now builds Linux x64 assets for v* tags from the source-controlled .cnb.yml pipeline. GitHub remains the canonical macOS/Windows release matrix. Users behind GitHub-blocking networks should use one of these paths:

• cargo install from the CNB mirror:

  cargo install --git https://cnb.cool/codewhale.net/codewhale --tag vX.Y.Z codewhale-cli
  cargo install --git https://cnb.cool/codewhale.net/codewhale --tag vX.Y.Z codewhale-tui
  

  (Both binaries are required — the dispatcher and the TUI ship separately; see AGENTS.md for the two-binary install rationale.) Linux build-time dependencies (build-essential, pkg-config, libdbus-1-dev on Debian/Ubuntu) are required — see INSTALL.md.

• CNB release assets for Linux x64, when the matching CNB tag pipeline has completed successfully. Download codewhale-linux-x64, codewhale-tui-linux-x64, and codewhale-artifacts-sha256.txt from the CNB release for vX.Y.Z, then verify the binaries against the manifest.

• DEEPSEEK_TUI_RELEASE_BASE_URL environment variable, if a CDN mirror of release assets exists. The npm wrapper installer and codewhale update read this variable to redirect binary downloads. For codewhale update, also set DEEPSEEK_TUI_VERSION=X.Y.Z so the updater can label the mirrored release without contacting GitHub. The directory pointed to must contain codewhale-artifacts-sha256.txt and the platform binaries; format matches a GitHub Release asset directory.

Clone from CNB

For a stable install, clone main or a release tag from:

https://cnb.cool/codewhale.net/codewhale.git

The mirror receives main, release tags, and matched release branches. GitHub is the fallback when the CNB workflow or credentials are unhealthy.

CNB deploy-button examples live in deploy/tencent-lighthouse/cnb/. They are not active until copied into .cnb.yml and .cnb/tag_deploy.yml, because live deploy jobs require a Lighthouse deploy key, target host, and explicit CNB quota/billing policy.