lakebase-scm-workflows
lakebase-scm-workflows – agent contract
Agent-facing contract: operating rules (.env, git hooks, credential single-seam), concrete code patterns for each substrate primitive, and reference pointers.
For the human-facing overview (prerequisites, installation, prompts, journey, CLI cheat sheet) see README.md.
FIRST: load the parent databricks-lakebase skill for Lakebase Postgres CLI basics (project / branch / endpoint shapes, name formats, "never delete the production branch" rule). This skill composes on top of it.
Project state – when .env matters
The substrate API takes explicit args (instance, branch, etc.) on every public function – agents can drive every operation without a project .env at all. But when an agent is acting AS the developer in a checked-out paired project, the project's .env is the source of truth for "which Lakebase branch is this workspace currently paired with."
| Agent context | .env contract |
|---|---|
| In a checked-out paired project (Claude Code / Cursor / Genie Code on a developer's machine) | Respect it. Read LAKEBASE_PROJECT_ID to derive instance. After git checkout, call syncEnvToCurrentBranch({ cwd }) so .env matches the new branch – otherwise the bundled CI scripts (refresh-token.sh, flyway-migrate.sh) and the git hooks operate on stale credentials. |
| Sandbox / no workspace (Claude Desktop, OpenAI Agent Builder, exploratory) | Ignore it. Pass instance and branch explicitly per call. Substrate never requires .env. |
| Bootstrapping a new project | N/A. createProject creates the .env for you as step 7. No .env exists before that. |
Connection-block keys (managed by syncEnvToCurrentBranch / updateEnvConnection / post-checkout.sh):