nocobase/.github/V3-MIGRATION.md

NocoBase 3 repository migration

NocoBase 3 is maintained in nocobase/nocobase on v3-develop, with stable promotion to v3-main. The repository's default branch is main, which continues to maintain the v1/v2 line. See skills/README.md for global Skill installation commands that explicitly select the v3 branch and Skill directory.

Regular v3 development branches use <type>/v3-<name>, such as feat/v3-app-installer or fix/v3-release-routing. Quality, changeset, Docs and UI Library checks accept pull requests targeting these branches, with their existing path filters, so stacked pull requests receive the same checks as pull requests targeting v3-develop or v3-main; pushes continue to run these workflows only on v3-develop, and the stable guard continues to run only for pull requests targeting v3-main. GitHub Actions expresses the stacked target as the glob */v3-*; for a valid branch under this rule, with a non-empty type and name and no extra slash, that is equivalent to the bot and CI regular expression /^[^/]+\/v3-[^/]+$/.

Release routing

Executable v3 workflows live directly in .github/workflows/ and use the v3- filename prefix. Their corresponding entries on main dispatch the implementation on v3-develop. An implementation-only change needs a check that this dispatch still reaches it; input, trigger, or filename changes need a coordinated update of the entry on main too.

PR checks are selected from the pull request's workflow context, not from the default branch's workflow inventory. Quality and Changeset have no dispatcher on main. The Docs and UI Library entries on main accept only manual dispatch and forward it to v3-develop; changes to their source-side PR branch filters do not change that entry contract. Keep their filenames, dispatch inputs and destination synchronized when those change.

Workflow	Source and destination	Registry or output
v3-release-beta.yml	Release v3-develop, then merge version commits back there	Public npm, beta dist-tag
v3-merge-beta-to-stable.yml	Promote v3-develop into v3-main, then synchronize prerelease state back	Version promotion only
v3-release-stable.yml	Release v3-main, then synchronize back to v3-develop; an older branch uses keep_latest	Public npm, latest or legacy dist-tag
v3-github-release.yml	Aggregate release-beta/* or release/* tags	GitHub Release without taking the shared Latest marker
v3-studio-image.yml	Called by v3-release-beta.yml when it published @nocobase/studio	Public Studio image on Docker Hub and Aliyun's public registry
v3-pro-release-beta.yml, v3-pro-release-stable.yml, v3-pro-promote-to-stable.yml	The independent nocobase/nocobase3-pro repository, retaining its develop and main branches; OSS pins come from v3-develop and v3-main	The configured private Pro registry

When a beta release publishes @nocobase/studio, v3-release-beta.yml calls v3-studio-image.yml with the release's release-beta/<batch> tag. It builds NocoBase Studio's public image from that tag, whose pnpm build packs the universal runner and nb-studio packages at the exact versions Studio records into dist/runners, so the image serves the runner and CLI it was released with, and pushes it to Docker Hub and Aliyun's public registry (ALI_DOCKER_PUBLIC_REGISTRY) as nocobase/studio:<version> and :beta (:latest for a version without a prerelease part), like the v2 release images. The release job reads Studio's version from the packages it versioned once npm publish has succeeded; a release that does not version Studio builds nothing, and neither does a dry run. To rebuild, re-run that job of the release run. Internal images, with dev versions of Studio, nb-studio and the runner, are built by studio-image.yml in 2013xile/nocobase-ci and pushed to the internal registry. The stable release does not build an image.

release-beta/* and release/* remain release candidate branch and aggregate tag names. They are not replacements for the long-lived v3 branches. The Pro submodule path vendor/nocobase3 remains a directory name, not an OSS repository address.

Repository configuration to confirm

The source workflows already target the new OSS repository and public npm. Repository-level settings are separate from committed YAML; a maintainer must confirm the following on nocobase/nocobase before treating a release as operational. Local checks do not prove that secrets exist or that publishing permissions have been granted.

• The NocoBase GitHub App is installed for nocobase/nocobase; NOCOBASE_APP_ID and NOCOBASE_APP_PRIVATE_KEY are configured, with the contents and pull request permissions the release workflows require. Pro workflows also require App access to the independent Pro repository.
• NPM_TOKEN can publish the affected public @nocobase packages. Pro uses PRO_NPM_REGISTRY and PRO_NPM_TOKEN independently and must keep using its private registry.
• Branch protection and required checks refer to the v3- workflows and allow the configured release bot's squash merges and synchronization into v3-develop and v3-main.
• Default-branch dispatch entries are present on main, Actions is enabled, and the beta and stable workflows pass with dry_run: true before an actual publish. Pro dispatch input descriptions on main should name the OSS v3-develop / v3-main branches; their current descriptions still use the former OSS names, although dispatch already selects v3-develop.
• RELEASE_RESULT_FEISHU_WEBHOOK_URL is configured if internal release notifications are required.
• DOCKERHUB_USERNAME, DOCKERHUB_TOKEN, ALI_DOCKER_PUBLIC_REGISTRY, ALI_DOCKER_USERNAME and ALI_DOCKER_PASSWORD can push nocobase/studio for the Studio release image; they are the credentials the v2 release images already use.
• Documentation deployment uses the independent repository secrets V3_DOCS_ALI_OSS_BUCKET, V3_DOCS_ALI_OSS_REGION and V3_DOCS_ALI_CDN_DOMAIN; leave the existing v2 deployment targets unchanged. Documentation and UI Library share DOCS_ALI_OSS_ACCESS_KEY_ID and DOCS_ALI_OSS_ACCESS_KEY_SECRET, which must have access to their respective destinations. UI Library keeps its nocobase-ui-library bucket in cn-beijing. Both workflows publish on matching pushes to v3-develop, or when manually dispatched with publish enabled; no additional migration variable is required.
• Pull requests changing only docs/** skip Quality, Changeset Check and Guard Main; the Docs workflow checks and builds the documentation without publishing. Quality also skips documentation-only pushes to v3-develop, where Docs builds and publishes instead. Mixed changes retain the normal checks. These workflow-level path filters must be considered before making the skipped workflows required branch checks, because GitHub can leave required checks pending when a workflow is filtered out. Preview routing is managed separately by the bot.

Historical references

Published CHANGELOG.md entries and consumed .changeset/pre/ files retain links to the archived OSS repository as release history. Pro release-note conversion also accepts archived OSS links so those historical notes still point to their Pro source. These references and the independent Pro repository are intentional; current package metadata, installation commands, and usage links must point to nocobase/nocobase and select a v3 branch where needed.