Shared App Source

Bkper-managed app source gives your team and coding agents one shared private codebase for a Bkper app. Authorized app developers can clone the same repository, improve it locally, and continue from one shared history without setting up a separate Git host.

Shared app source supports development collaboration. It does not automatically build or deploy your app.

Who can access the source

The app owner and users matched by the developers field in bkper.yaml can read and update managed source. This includes configured domain patterns such as *@example.com.

App users and Book collaborators do not receive source access unless they also match the app’s developer policy.

Start a shared codebase

A standalone app becomes eligible for Bkper-managed source when:

• bkper.yaml is at the root of its Git repository.
• The current branch is main for the first managed sync.
• The working tree is clean and has at least one commit.
• No Git remote is configured.

bkper app init initializes Git on main, but it does not create the first commit. Review and commit the app before its first sync:

bkper app init my-app
cd my-app

# Review the generated app, then commit it
git add .
git commit -m "Initial app"

bkper app sync

For an eligible app, bkper app sync creates its private Bkper-managed source and configures it as origin. The same command also syncs app metadata from bkper.yaml.

Clone and continue together

Any authorized app developer can start from the shared codebase:

bkper app clone <appId>
cd <appId>
bun install

bkper app clone copies the repository but does not install dependencies or run repository scripts. A teammate or coding agent can then work in the local clone, run the project’s checks, commit changes, and push them back to the shared repository. Another authorized developer can pull or clone that history and continue the work.

Keep agent instructions such as AGENTS.md in the repository so every teammate and coding agent starts with the same project context and safety rules.

Source synchronization is not deployment

Source storage and app deployment are separate operations:

Action	What it does with source	Does it deploy?
git push	Stores committed source in the managed repository.	No
bkper app sync	Safely pushes managed source, then syncs app metadata from bkper.yaml.	No
npm run build	Creates local build output in dist/.	No
bkper app deploy	Pushes and verifies the managed commit, then uploads the existing local build.	Yes

An ordinary Git push never deploys. bkper app deploy also does not run a build, so build locally before deploying the result you intend to release.

Managed sync and deploy require a clean, committed working tree and use fast-forward safety checks. The CLI does not automatically commit, merge, rebase, force-push, reset, or discard files.

External Git and monorepos

Bkper-managed source is optional. Existing workflows remain external when:

• the app already has a GitHub, GitLab, or other provider remote;
• bkper.yaml is inside a monorepo rather than at the repository root; or
• the app is otherwise not rooted in a standalone Git repository.

Clone those apps from their external provider. bkper app clone is for Bkper-managed source only.

Moving an existing standalone app from an external provider is intentional: the CLI never removes or renames an existing remote. Before changing remotes, make sure every branch and tag you want to preserve is available locally and the current main branch is clean and committed. Removing all external remotes and running bkper app sync then activates managed source for an eligible app.

The repoUrl field in bkper.yaml is app-listing metadata. It does not select managed or external source mode.

Next steps

• Your First App — Scaffold an app and establish its shared source
• Building & Deploying — Build, sync, preview, and deploy explicitly
• CLI — Install the CLI and review its app-development workflows
• Coding Agents — Give coding agents the Bkper and project context they need