Guide

GitHub branching

Install the Layerbase GitHub App on a repository, map it to a database, and Layerbase keeps a staging database branch in sync with your git flow. When a pull request merges into your base branch, the staging branch is reset against production, so staging always mirrors what just shipped. The App install is its own grant, so it works no matter how you sign in to Layerbase, whether that is Google or GitHub.

How it works

A Layerbase database branch is a full, writable copy of its parent. On branch-ready (ZFS) storage a branch is an instant copy-on-write fork, not a slow byte copy, so a branch gets its own data in seconds. You install the App once, map a repository, and Layerbase reacts to GitHub webhooks:

• Your base git branch (usually main) is treated as production and uses your main database.
• Your staging git branch uses a database branch forked from production.
• When a pull request merges into the base branch, the staging database branch is reset against production for you (if you opt in).

Branching runs on any Layerbase engine that supports it. See database branching for the current engine list.

Before you start

You need a database on Layerbase Cloud and a GitHub repository you can install an App on. Branching also requires branch-ready storage, which is a one-click toggle (next step).

1. Turn on Instant branches

Open the database on Layerbase Cloud, go to its Settings tab, and turn on Instant branches. That puts the database on branch-ready (ZFS) storage so branches are instant. New databases on branchable engines are created on branch-ready storage already, so this is often just a flip of the toggle. If the database is not yet on branch-ready storage, enabling it runs a brief, one-time move (a few minutes, once); your connection string stays the same either way.

2. Connect GitHub

Go to Integrations and click Connect GitHub. You will be sent to GitHub to install the Layerbase App, then returned to the dashboard. This is a repository install, independent of how you sign in, so a Google-login account connects it just the same. The connection is shared with your team, so any member can wire up a repository against it.

3. Install the App on your repos

On GitHub, choose the account or organization and pick the repositories to grant access to. You can select a single repo or all of them, and change the selection later from GitHub Settings, then Installed GitHub Apps. The install brings its own webhooks, so there is no per-repo webhook to configure by hand.

4. Create a mapping

Back in the dashboard, click New mapping and fill in:

• Database: the production database to fork from.
• Repository: one of the repos you installed the App on.
• Base branch: your production git branch, read straight from the repo.
• Staging git branch and the name for the Layerbase staging branch to create.
• Reset staging on merge: re-fork staging from production when a PR merges to your base branch.

On Create mapping, Layerbase ensures the database is branchable and forks the staging branch. From then on, GitHub events drive the sync.

Reset staging on every merge (optional)

With Reset staging on merge on, Layerbase re-forks the staging branch from production whenever a pull request merges into your base branch. This keeps staging close to production, and is destructive: it discards whatever was in the staging branch. The connection string does not change, so nothing downstream needs re-wiring. It is off by default.

Permissions we ask for

The Layerbase GitHub App is deliberately read-only. It never gets write access to your repository, and it does not push code, open pull requests, or change any files.

What about environment variables?

Unlike the Vercel integration, GitHub has no deployment platform to inject a connection string into, so this integration does not set any environment variables. Your branch databases show up in the dashboard with their own connection strings, and CI or application code can resolve a branch by name through the branch API or the layerbase CLI. That keeps the credential in your own secret store rather than written back into GitHub.

Per-branch preview databases (rolling out)

A per-branch mode, where every feature branch gets its own database branch forked from production and is cleaned up automatically when the git branch is deleted or its pull request closes, is on the way. It is not enabled yet. Today a mapping keeps one shared staging branch in sync; the per-branch option turns on for everyone once the automatic cleanup has proven itself.

Removing a mapping

Delete a mapping from the Integrations page. Your production database and the Layerbase staging branch are left untouched; delete the branch from its dashboard page if you want it gone. Mark any database or branch as persistent on its Settings tab to protect it from automated cleanup entirely. To disconnect GitHub entirely, uninstall the App from your repository on GitHub.