Branches

Branches register environments as forks of a parent environment for schema diffing and merging. A branch captures the parent's schema as a merge base, enabling safe three-way merges and clean PR workflows.

Endpoints

POST /v1/organizations/{org}/projects/{project}/branches

Request body:

JSON

{
  "environment_id": "pr-42",
  "base_environment_id": "production"
}

base_environment_id is optional. When omitted, the branch has no merge base (useful for standalone review environments).

Response 200 OK:

JSON

{
  "environment_id": "pr-42",
  "base_environment_id": "production",
  "merge_base_schema_version": "abc123",
  "registered_at": "2026-01-01T00:00:00Z"
}

GET /v1/organizations/{org}/projects/{project}/branches

List all registered branches.

Response 200 OK:

JSON

{
  "branches": [
    {
      "environment_id": "pr-42",
      "base_environment_id": "production",
      "registered_at": "2026-01-01T00:00:00Z"
    }
  ]
}

POST /v1/organizations/{org}/projects/{project}/branches/diff

Compute the schema diff between two environments.

Request body:

JSON

{ "base": "production", "head": "pr-42" }

Response 200 OK:

JSON

{
  "changes": [
    {
      "kind": "table",
      "name": "payments",
      "action": "added",
      "definition": "CREATE TABLE payments (...)"
    },
    {
      "kind": "column",
      "table": "orders",
      "name": "paid_at",
      "action": "added",
      "definition": "timestamptz"
    }
  ]
}

POST /v1/organizations/{org}/projects/{project}/branches/merge

Merge the head environment's schema into the base environment.

Request body:

JSON

{ "base": "production", "head": "pr-42", "force": false }

With force: false, the merge fails if there are conflicts. With force: true, the head schema wins on all conflicts.

Response 200 OK:

JSON

{
  "merged": true,
  "changes": [...],
  "conflicts": []
}

POST /v1/organizations/{org}/projects/{project}/branches/{env}/pr

Link a branch to a pull request.

Request body:

JSON

{
  "provider": "github",
  "repository": "acme/store",
  "number": 42,
  "url_template": null
}

Supported providers: github, gitlab, bitbucket, generic.

For generic, provide url_template with {repo} and {number} placeholders:

JSON

{
  "provider": "generic",
  "repository": "acme/store",
  "number": 42,
  "url_template": "https://git.example.com/{repo}/pull/{number}"
}

CLI shortcuts

Terminal

scribase branch register acme store pr-42 --base production
scribase branch diff acme store production pr-42
scribase branch merge acme store production pr-42
scribase branch pr acme store pr-42 github acme/store 42
scribase branch list acme store

See scribase branch for the full local and remote branch reference.