prisma · AmanVarshney01 · Apr 29, 2026
diff --git a/docs/product/command-principles.md b/docs/product/command-principles.md
@@ -100,6 +100,27 @@ Example:
 
 - `project link`
 
+### `connect`
+
+Connect a project to an external provider integration.
+
+`connect` is different from `link`:
+
+- `link` binds local repo context to an existing Prisma resource
+- `connect` configures remote project metadata for an external integration
+
+Example:
+
+- `project connect-repo`
+
+### `disconnect`
+
+Remove a project-level external provider integration.
+
+Example:
+
+- `project disconnect-repo`
+
 ### `deploy`
 
 Build and release an app into a target branch.

diff --git a/docs/product/command-spec.md b/docs/product/command-spec.md
@@ -22,6 +22,9 @@ Out of scope for the current preview:
 - `migrate`
 - product-specific namespaces such as `compute`
 
+The GitHub branch automation slice extends the `project` group with repository
+connection commands. It does not add a top-level `git` or `github` group.
+
 ## Global Rules
 
 - Canonical shape is `prisma <group> <action>`.
@@ -42,6 +45,39 @@ Out of scope for the current preview:
 - `prisma.config.ts` stores only the linked project id.
 - Remote commands do not silently change local context.
 
+## Current Provider-Backed Prototype
+
+The long-term MVP command model remains environment-based.
+
+The current real provider does not yet expose first-class environment resources or source-revision promotion semantics through the Management API. Until that changes, the real-provider prototype uses this temporary contract:
+
+- fixture mode continues to model the target MVP `env` behavior
+- real-provider mode currently supports linked `project`, selected `app`, and `deployment`
+- real-provider mode does not yet support project repository connection APIs
+- fixture mode stores project repository connections in local CLI state to validate the command language
+- local prototype app selection lives in `.prisma/cli/state.json`, keyed by linked project
+- local prototype release flows also persist the last deployment this CLI believes is live for each project/app
+- when no saved live deployment exists yet, the prototype falls back to treating the most recent deployment as live
+- `prisma.config.ts` remains project-only
+- `env list`, `env show`, and `env use` return `FEATURE_UNAVAILABLE` in real-provider mode
+- `app logs` resolves deployments in the current app/deployment prototype model and streams provider-backed logs
+- `app promote <deployment> [--app <name>]` switches which deployment is live for the selected app
+- `app rollback [--app <name>] [--to <deployment>]` switches the selected app back to an earlier deployment
+- provider compute service/version resources remain implementation detail and are not surfaced as CLI nouns
+
+## Interactivity and Confirmation
+
+- Commands default to TTY-aware interaction behavior unless a command is intentionally non-interactive.
+- `--interactive` and `--no-interactive` override that default.
+- `-y` and `--yes` accept confirmation prompts when a command supports confirmation.
+- `--json` and non-interactive mode never block on a prompt.
+
+When confirmation is required and a prompt cannot be shown:
+
+- the command must fail with a structured actionable error
+- the error should explain what required confirmation
+- the error should suggest `-y` when `-y` is a valid bypass
+
 ## Context Resolution
 
 ### Project
@@ -238,6 +274,185 @@ prisma-cli project link
 prisma-cli project link proj_123
 ```
 
+## `prisma-cli project connect-repo [git-url]`
+
+Purpose:
+
+- connect the linked Prisma project to a GitHub repository
+
+Behavior:
+
+- requires auth
+- requires an existing linked project
+- in the current real-provider prototype, returns `FEATURE_UNAVAILABLE`
+- the behavior below remains the target M2 contract and current fixture-mode contract
+- if `[git-url]` is provided, parses it as a GitHub repository URL
+- if `[git-url]` is omitted, reads the local Git `origin` remote URL
+- accepts common GitHub URL forms such as:
+  - `https://github.com/prisma/prisma-cli`
+  - `https://github.com/prisma/prisma-cli.git`
+  - `git@github.com:prisma/prisma-cli.git`
+- rejects unsupported providers with `REPO_PROVIDER_UNSUPPORTED`
+- writes the repository connection as project metadata on the platform
+- does not write the repository connection to `prisma.config.ts`
+- does not create branches synchronously
+- enables future branch and pull request webhook automation for that project
+
+Current fixture-mode note:
+
+- the repo connection is stored in `.prisma/cli/state.json`, keyed by linked project
+- this local storage is a prototype stand-in for platform project metadata
+
+In `--json`, `result` uses this stable shape:
+
+```json
+{
+  "linkedProjectId": "proj_123",
+  "workspace": {
+    "id": "ws_123",
+    "name": "Acme Inc"
+  },
+  "project": {
+    "id": "proj_123",
+    "name": "Acme Dashboard"
+  },
+  "repositoryConnection": {
+    "provider": "github",
+    "repository": {
+      "owner": "prisma",
+      "name": "prisma-cli",
+      "url": "https://github.com/prisma/prisma-cli"
+    },
+    "automation": {
+      "branches": true,
+      "pullRequests": true,
+      "comments": true
+    },
+    "installation": {
+      "status": "pending",
+      "id": null
+    }
+  }
+}
+```
+
+Rules:
+
+- `repositoryConnection.provider` is `github` in the MVP
+- `installation.status` may be `pending` until the GitHub App installation callback is complete
+- branch automation begins only after installation access and repository mapping are complete
+
+Help:
+
+- description: `Connect the linked project to a GitHub repository.`
+- examples:
+  - `prisma-cli project connect-repo`
+  - `prisma-cli project connect-repo git@github.com:prisma/prisma-cli.git`
+
+Example human output:
+
+```text
+project connect-repo → Connecting the linked project to a GitHub repository.
+
+│  project:     Acme Dashboard
+│  workspace:   Acme Inc
+│  repository:  prisma/prisma-cli
+│  provider:    GitHub
+│  mode:        apply
+│
+│  Read more    docs/product/command-spec.md#prisma-project-connect-repo-git-url
+
+◇ Applying repository connection...
+✔ Applied 1 operation(s)
+  Branch automation is now pending GitHub App installation.
+```
+
+## `prisma-cli project disconnect-repo`
+
+Purpose:
+
+- disconnect the GitHub repository from the linked Prisma project
+
+Behavior:
+
+- requires auth
+- requires an existing linked project
+- in the current real-provider prototype, returns `FEATURE_UNAVAILABLE`
+- the behavior below remains the target M2 contract and current fixture-mode contract
+- removes the project repository connection
+- stops future branch and pull request automation for that project
+- does not delete the linked Prisma project
+- does not delete `prisma.config.ts`
+- does not delete historical branches synchronously
+- retention for existing branches follows the documented branch retention policy
+
+Current fixture-mode note:
+
+- clears the local repo connection from `.prisma/cli/state.json`
+
+In `--json`, `result` uses the same shape as `project connect-repo`, with
+`repositoryConnection: null`.
+
+Help:
+
+- description: `Disconnect the GitHub repository from the linked project.`
+- examples:
+  - `prisma-cli project disconnect-repo`
+
+Example human output:
+
+```text
+project disconnect-repo → Disconnecting the GitHub repository from the linked project.
+
+│  project:     Acme Dashboard
+│  workspace:   Acme Inc
+│  repository:  prisma/prisma-cli
+│  mode:        apply
+│
+│  Read more    docs/product/command-spec.md#prisma-project-disconnect-repo
+
+◇ Applying repository disconnection...
+✔ Applied 1 operation(s)
+  Branch automation is no longer active for this project.
+```
+
+## GitHub Branch Automation
+
+GitHub branch automation is platform behavior enabled by `project connect-repo`.
+
+Subscribed GitHub App events:
+
+- `installation`
+- `installation_repositories`
+- `push`
+- `pull_request`
+
+Webhook rules:
+
+- webhook signatures must be validated before processing
+- webhook delivery ids must be stored so repeated delivery is idempotent
+- `push` events for `refs/heads/<branch>` with `deleted: false` upsert the matching Prisma branch
+- `push` events for `refs/heads/<branch>` with `deleted: true` move the matching Prisma branch into the documented retention state
+- `pull_request` events with `opened`, `reopened`, `synchronize`, or `edited` upsert the matching Prisma branch and attach PR metadata
+- `pull_request` events with `closed` update PR metadata and then apply the branch retention policy
+- branch rename is treated as delete/create unless a reliable provider event is available
+- fork pull requests do not create deployable branches in M2 unless explicitly allowed by a later security decision
+
+PR comment rules:
+
+- comments use the GitHub issue comment API because pull requests are issues
+- comments must be sticky and updated in place using a hidden marker
+- comments must clearly say that branch sync succeeded while preview deployment is pending M3
+- inability to write a comment should not roll back branch sync
+
+M2 non-goals:
+
+- app build system
+- automatic Compute deployment
+- preview URL going live
+- applying schema from source into preview DB
+- build logs
+
 ## `prisma-cli branch list`
 
 Purpose:

diff --git a/docs/product/error-conventions.md b/docs/product/error-conventions.md
@@ -158,6 +158,9 @@ These codes are the minimum stable set for the MVP:
 - `CONFIRMATION_REQUIRED`
 - `REMOVE_FAILED`
 - `FEATURE_UNAVAILABLE`
+- `REPO_NOT_CONNECTED`
+- `REPO_PROVIDER_UNSUPPORTED`
+- `LOGS_FAILED`
 - `BUILD_FAILED`
 - `RUN_FAILED`
 - `DEPLOY_FAILED`
@@ -177,6 +180,9 @@ Recommended meanings:
 - `CONFIRMATION_REQUIRED`: command cannot continue without confirmation in the current mode
 - `REMOVE_FAILED`: app removal could not complete remotely
 - `FEATURE_UNAVAILABLE`: the command exists in the CLI model, but the current preview cannot support it yet
+- `REPO_NOT_CONNECTED`: a command expected a project repository connection, but none exists
+- `REPO_PROVIDER_UNSUPPORTED`: a repository URL could be parsed, but the provider is not supported by the MVP
+- `LOGS_FAILED`: log streaming could not be started or completed cleanly
 - `BUILD_FAILED`: build failed before a healthy deployment existed
 - `RUN_FAILED`: local framework run command could not be started or exited unsuccessfully
 - `DEPLOY_FAILED`: deployment or post-build health failed

diff --git a/docs/product/output-conventions.md b/docs/product/output-conventions.md
@@ -71,6 +71,8 @@ Current MVP commands map to patterns like this:
 | `branch list` | `list` |
 | `branch show` | `show` |
 | `branch use` | `mutate` |
+| `project connect-repo` | `mutate` |
+| `project disconnect-repo` | `mutate` |
 
 No current MVP command uses `verify` or `inspect`, but new commands must still choose one existing pattern rather than inventing a new one casually.
 

diff --git a/docs/product/resource-model.md b/docs/product/resource-model.md
@@ -112,6 +112,63 @@ Rules:
 - the app may be selected or created as part of app deployment workflows
 - app selection is local CLI state when needed for the preview package
 
+### Repository Connection
+
+`repository connection` is the remote source-control binding for a Prisma project.
+
+M2 relevance:
+
+- connects a Prisma project to a GitHub repository
+- enables branch and pull request webhook automation
+- is stored as platform project metadata, not in `prisma.config.ts`
+- does not imply app build, deploy, preview URL, schema application, or database provisioning
+
+MVP rules:
+
+- only GitHub is supported
+- the CLI may infer a repository from the local `origin` remote
+- users may also pass an explicit GitHub repository URL
+- disconnecting a repository stops future GitHub automation for the project
+- historical branches may remain according to the retention policy
+
+Current provider-backed prototype note:
+
+- platform repo-connection APIs are not available in this repo
+- fixture mode stores the connection in local CLI state so the intended command language can be validated
+- real-provider mode returns `FEATURE_UNAVAILABLE` until platform APIs exist
+
+### Branch
+
+`branch` is the project-scoped Prisma representation of a remote source branch.
+
+M2 relevance:
+
+- created or updated from GitHub branch and pull request webhook events
+- records source metadata such as repository, branch name, head commit, and pull request link
+- is the future attachment point for preview databases, apps, and deployments
+- is not itself a deployment
+
+M2 rules:
+
+- pushing a remote GitHub branch creates or updates the matching Prisma branch
+- opening or updating a pull request links PR metadata to the matching Prisma branch
+- repeated webhook deliveries must be idempotent
+- branch deletion or PR closure moves the Prisma branch into the documented retention state
+- if branch retention is not yet decided, deletion and closure must surface as an open product dependency rather than silently deleting data
+
+Non-goals for M2:
+
+- app build
+- automatic Compute deployment
+- preview URL going live
+- applying schema from source into a preview database
+- build logs
+
+Current provider-backed prototype note:
+
+- branch webhook ingestion belongs to the platform backend, not the local CLI package
+- the CLI only starts or removes the project repository connection
+
 ### Deployment
 
 `deployment` is one build-and-release instance of an app.
@@ -170,6 +227,7 @@ future schema, database, and migration workflows awkward.
 
 ```text
 workspace -> project
+project -> repository connection
 project -> branch
 branch -> app*
 branch -> database*

diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -13,6 +13,7 @@ Run:
 ```bash
 pnpm prisma-cli --help
 pnpm prisma-cli auth login
+pnpm prisma-cli project connect-repo git@github.com:org/repo.git
 pnpm prisma-cli app deploy --env DATABASE_URL=postgresql://example
 pnpm prisma-cli app list-env
 ```