From 9efe6c788069d6f7041cce8c9c0686ebdfbd1082 Mon Sep 17 00:00:00 2001 From: Kristof Siket Date: Tue, 15 Sep 2026 14:53:31 +0200 Subject: [PATCH 1/3] fix(cli): stop promising deploy-on-push without a workflow The platform retired build-on-push when build-runner was removed (pdp-control-plane, 2026-09-07): a push to a connected repository now records the branch and never starts a build. Builds run in the repository's own GitHub Actions through prisma/cloud-deploy-action, which the connection authorises via the run's OIDC token. Console import writes that workflow in a setup pull request; `prisma git connect` does not, so a repository connected from the CLI deployed nothing on push while the skill, the help text, and the group card all said "no workflow file is required". Fix the shipped prisma-platform-core-concepts skill to describe the real contract with a minimal workflow, add the failure mode to the quick reference, and make `git connect` name the workflow as the next step in both human and JSON output. Co-Authored-By: Claude Fable 5.1 --- packages/cli/src/cli.ts | 14 +++-- packages/cli/src/commands/git/connect.ts | 34 ++++++++-- packages/cli/tests/git.test.ts | 18 +++++- skills/prisma-platform-core-concepts/SKILL.md | 62 ++++++++++++++++--- 4 files changed, 108 insertions(+), 20 deletions(-) diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts index e48d9eee..7d1c7427 100644 --- a/packages/cli/src/cli.ts +++ b/packages/cli/src/cli.ts @@ -187,7 +187,10 @@ export const cliGroups: Readonly< run: "project create my-app", brief: "Create a Project, link this directory", }, - { run: "git connect", brief: "Connect GitHub so every push deploys" }, + { + run: "git connect", + brief: "Connect GitHub; its deploy workflow then deploys pushes", + }, { run: "project env add KEY=value --role preview", brief: "Set env vars services get at deploy", @@ -262,9 +265,9 @@ export const cliGroups: Readonly< }, git: { brief: - "Manage the GitHub connection that deploys on push. Connect or disconnect a repository", + "Manage the GitHub connection behind deploy-on-push. Connect or disconnect a repository", description: - "Connecting a GitHub repository turns on deploy-on-push: pushing a Git branch builds and deploys it to a matching Platform Branch. Disconnecting stops push deploys without touching anything already deployed.", + "Connecting a GitHub repository turns on deploy-on-push: the repository's prisma/cloud-deploy-action workflow authenticates through the connection and deploys every pushed branch to a matching Platform Branch. The platform does not build on push; the workflow does. Disconnecting stops push deploys without touching anything already deployed.", }, service: { brief: @@ -468,7 +471,10 @@ export function buildCli(): Cli { run: "project create my-app", brief: "Create a Project, link this directory", }, - { run: "git connect", brief: "Connect GitHub so every push deploys" }, + { + run: "git connect", + brief: "Connect GitHub; its deploy workflow then deploys pushes", + }, { run: "deploy", brief: "Or build and deploy straight from this machine", diff --git a/packages/cli/src/commands/git/connect.ts b/packages/cli/src/commands/git/connect.ts index ddf212dc..86e695ad 100644 --- a/packages/cli/src/commands/git/connect.ts +++ b/packages/cli/src/commands/git/connect.ts @@ -38,6 +38,18 @@ import { } from "./context"; import { installWaitFailedError } from "./errors"; +/** Where the deploy workflow's inputs and the minimal file are documented. */ +const WORKFLOW_DOCS_URL = + "https://github.com/prisma/cloud-deploy-action#readme"; + +/** The platform never builds on push; the repository's own Actions workflow + * does, so a connection without one deploys nothing. Console import writes + * the file through a setup pull request; this command does not. */ +const WORKFLOW_DETAIL = + "Deploys run from the repository's GitHub Actions workflow (prisma/cloud-deploy-action); the platform does not build on push."; +const WORKFLOW_NEXT_STEP = + "If the repository has no .github/workflows/prisma-deploy.yml yet, add one running prisma/cloud-deploy-action@v1 with `id-token: write`; without it, pushes deploy nothing."; + /** The legacy wait line, printed once before the poll loop. */ const WAIT_MESSAGE = "Waiting for GitHub App installation or repository access approval..."; @@ -127,7 +139,17 @@ function connectPresentations( return { stdout: () => [], json: () => result, - next: () => [], + next: () => [ + { + kind: "edit-file", + label: WORKFLOW_NEXT_STEP, + }, + { + kind: "open-url", + label: "Workflow reference (prisma/cloud-deploy-action)", + url: WORKFLOW_DOCS_URL, + }, + ], human: (): Block[] => [ { kind: "summary", @@ -143,7 +165,10 @@ function connectPresentations( { label: "status", value: connection.status }, ], }, - { kind: "list", items: [formatGitConnectionDetail(connection.status)] }, + { + kind: "list", + items: [formatGitConnectionDetail(connection.status), WORKFLOW_DETAIL], + }, ], }; } @@ -159,9 +184,10 @@ export const gitConnectCommand = defineCommand({ flags: { project: projectFlag }, }, help: { - summary: "Connect a project to a GitHub repository so every push deploys", + summary: + "Connect a project to a GitHub repository so its deploy workflow deploys every push", description: - "Turns on deploy-on-push: once connected, pushing a Git branch builds and deploys it to a matching Platform Branch, an isolated environment with its own services, databases, and buckets. If the Prisma GitHub App does not cover the repository yet, the command opens the install page and waits. Run without a URL to use this repository's origin remote.", + "Links the repository to the project. Once connected, the repository's prisma/cloud-deploy-action workflow authenticates each run through GitHub's OIDC token and deploys every pushed branch to a matching Platform Branch, an isolated environment with its own services, databases, and buckets. The platform does not build on push itself: a repository without the workflow must add .github/workflows/prisma-deploy.yml (importing in the Console opens a pull request that adds it). If the Prisma GitHub App does not cover the repository yet, the command opens the install page and waits. Run without a URL to use this repository's origin remote.", examples: [ "git connect", "git connect git@github.com:prisma/prisma-cli.git", diff --git a/packages/cli/tests/git.test.ts b/packages/cli/tests/git.test.ts index 9c4d3ad2..fdc63d58 100644 --- a/packages/cli/tests/git.test.ts +++ b/packages/cli/tests/git.test.ts @@ -265,7 +265,10 @@ describe("prisma git connect", () => { }, { kind: "list", - items: ["GitHub branch automation is active for this project."], + items: [ + "GitHub branch automation is active for this project.", + "Deploys run from the repository's GitHub Actions workflow (prisma/cloud-deploy-action); the platform does not build on push.", + ], }, ]); }); @@ -683,7 +686,18 @@ describe("prisma git connect", () => { automation: { branches: true, pullRequests: false, comments: false }, }, }, - nextActions: [], + nextActions: [ + { + kind: "edit-file", + label: + "If the repository has no .github/workflows/prisma-deploy.yml yet, add one running prisma/cloud-deploy-action@v1 with `id-token: write`; without it, pushes deploy nothing.", + }, + { + kind: "open-url", + label: "Workflow reference (prisma/cloud-deploy-action)", + url: "https://github.com/prisma/cloud-deploy-action#readme", + }, + ], }); }); diff --git a/skills/prisma-platform-core-concepts/SKILL.md b/skills/prisma-platform-core-concepts/SKILL.md index b40ad9c0..ae11b5b2 100644 --- a/skills/prisma-platform-core-concepts/SKILL.md +++ b/skills/prisma-platform-core-concepts/SKILL.md @@ -3,7 +3,7 @@ name: prisma-platform-core-concepts metadata: library: "prisma" library_version: "8.0.0-rc.15" - version: 2026.9.1 + version: 2026.9.2 description: >- Use when hosting, deploying, or operating an app on the Prisma Platform: projects, branches, preview environments, services and their versions, @@ -119,8 +119,9 @@ another project or branch explicitly. There is no separate "preview environment" object to create or configure. The branch is the environment, and branches come into being by deploying to them: -1. **Push a git branch** (with the GitHub integration connected): the - platform creates the branch environment on the fly, builds, and deploys. +1. **Push a git branch** (with the GitHub integration connected and the + deploy workflow in the repository): the workflow builds and deploys, and + the platform creates the branch environment on the fly. 2. **Deploy a stage from the CLI**: `prisma deploy module.ts --stage pr-42` creates a branch named `pr-42` and deploys the identical app graph into it. A stage name must be a valid git ref name; an invalid name is a hard @@ -142,13 +143,45 @@ Preview lifecycle rules: ## Two ways to deploy -**GitHub (recommended).** Install the Prisma GitHub app and connect the -repository: `prisma git connect`, or import the repository in the Console. -From then on, every push builds and deploys on the platform. A push to the -default branch deploys production; a push to any other branch creates or -updates that branch's preview environment. No workflow file is required, and -previews come free with every branch. Opening a pull request does not itself -deploy anything; previews track branch pushes. +**GitHub (recommended).** Two pieces, both required: the Prisma GitHub App +connected to the repository, and a GitHub Actions workflow in the repository +that runs `prisma/cloud-deploy-action`. The platform does not build on push. +The workflow builds in the repository's own Actions and deploys with a +short-lived credential exchanged from the run's OIDC token; the connection +is what authorises that exchange, and it also tears a preview down when its +git branch is deleted. Importing the repository in the Console opens a setup +pull request that adds the workflow. `prisma git connect` only creates the +connection, so a repository connected from the CLI adds the workflow itself. +The minimal `.github/workflows/prisma-deploy.yml`: + +```yaml +name: prisma-deploy +on: + push: +permissions: + contents: read + id-token: write +jobs: + deploy: + if: github.ref_type == 'branch' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 24 + - uses: oven-sh/setup-bun@v2 + - uses: prisma/cloud-deploy-action@v1 + with: + build-command: npm run build +``` + +From then on, every push runs the workflow. A push to the default branch +deploys production; a push to any other branch creates or updates that +branch's preview environment, so previews come free with every branch. +Opening a pull request does not itself deploy anything; previews track +branch pushes. A connected repository without the workflow gets branch +bookkeeping and preview teardown from the platform, and no builds. **CLI.** `prisma deploy module.ts` deploys production directly; add `--stage ` for a preview. Authenticate once with `prisma auth login` @@ -324,6 +357,12 @@ Windows is not supported for the local stack yet. 10. **A deployed service errors on its first timestamp read (`RUNTIME.TEMPORAL_UNAVAILABLE`).** The runtime has no global `Temporal`; see the Compute runtime section for the polyfill. +11. **The repository is connected, but a push built nothing.** The platform + does not build on push; the repository's own workflow does. Make sure + `.github/workflows/prisma-deploy.yml` exists on the pushed branch and + that a run appears under the repository's Actions tab. A connected + repository with no workflow records the branch and deploys nothing, and + no error is raised anywhere. ## What the platform doesn't do yet @@ -340,6 +379,9 @@ Name the gap instead of inventing an API: enough to name here. 4. **No bucket rename** and no bucket-to-branch re-association after creation; re-create instead. +5. **No build on push without a workflow.** The GitHub connection authorises + deploys and tears previews down; it never starts a build. The + `prisma/cloud-deploy-action` workflow is the build. For anything else missing, run the nearest group with `--help` before concluding it does not exist, and route requests with `prisma feedback` From 69b5e200ca95723b7e68d64a7967a35cec269b1f Mon Sep 17 00:00:00 2001 From: Kristof Siket Date: Tue, 15 Sep 2026 14:59:09 +0200 Subject: [PATCH 2/3] fix(cli): say the deploy workflow must exist on the pushed branch GitHub reads workflows from the pushed commit, so a branch that lacks .github/workflows/prisma-deploy.yml deploys nothing even when the repository is connected. Name that condition in the skill, the help rows, and the git connect output (CodeRabbit finding). Co-Authored-By: Claude Fable 5.1 --- packages/cli/src/cli.ts | 6 ++++-- packages/cli/src/commands/git/connect.ts | 4 ++-- packages/cli/tests/git.test.ts | 4 ++-- skills/prisma-platform-core-concepts/SKILL.md | 9 ++++++--- 4 files changed, 14 insertions(+), 9 deletions(-) diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts index 7d1c7427..c82cbb12 100644 --- a/packages/cli/src/cli.ts +++ b/packages/cli/src/cli.ts @@ -189,7 +189,8 @@ export const cliGroups: Readonly< }, { run: "git connect", - brief: "Connect GitHub; its deploy workflow then deploys pushes", + brief: + "Connect GitHub; branches carrying the deploy workflow deploy on push", }, { run: "project env add KEY=value --role preview", @@ -473,7 +474,8 @@ export function buildCli(): Cli { }, { run: "git connect", - brief: "Connect GitHub; its deploy workflow then deploys pushes", + brief: + "Connect GitHub; branches carrying the deploy workflow deploy on push", }, { run: "deploy", diff --git a/packages/cli/src/commands/git/connect.ts b/packages/cli/src/commands/git/connect.ts index 86e695ad..32919033 100644 --- a/packages/cli/src/commands/git/connect.ts +++ b/packages/cli/src/commands/git/connect.ts @@ -46,9 +46,9 @@ const WORKFLOW_DOCS_URL = * does, so a connection without one deploys nothing. Console import writes * the file through a setup pull request; this command does not. */ const WORKFLOW_DETAIL = - "Deploys run from the repository's GitHub Actions workflow (prisma/cloud-deploy-action); the platform does not build on push."; + "Deploys run from the repository's GitHub Actions workflow (prisma/cloud-deploy-action), which must exist on each pushed branch; the platform does not build on push."; const WORKFLOW_NEXT_STEP = - "If the repository has no .github/workflows/prisma-deploy.yml yet, add one running prisma/cloud-deploy-action@v1 with `id-token: write`; without it, pushes deploy nothing."; + "If the repository has no .github/workflows/prisma-deploy.yml yet, add one running prisma/cloud-deploy-action@v1 with `id-token: write`; a push of any branch that lacks the file deploys nothing."; /** The legacy wait line, printed once before the poll loop. */ const WAIT_MESSAGE = diff --git a/packages/cli/tests/git.test.ts b/packages/cli/tests/git.test.ts index fdc63d58..54842286 100644 --- a/packages/cli/tests/git.test.ts +++ b/packages/cli/tests/git.test.ts @@ -267,7 +267,7 @@ describe("prisma git connect", () => { kind: "list", items: [ "GitHub branch automation is active for this project.", - "Deploys run from the repository's GitHub Actions workflow (prisma/cloud-deploy-action); the platform does not build on push.", + "Deploys run from the repository's GitHub Actions workflow (prisma/cloud-deploy-action), which must exist on each pushed branch; the platform does not build on push.", ], }, ]); @@ -690,7 +690,7 @@ describe("prisma git connect", () => { { kind: "edit-file", label: - "If the repository has no .github/workflows/prisma-deploy.yml yet, add one running prisma/cloud-deploy-action@v1 with `id-token: write`; without it, pushes deploy nothing.", + "If the repository has no .github/workflows/prisma-deploy.yml yet, add one running prisma/cloud-deploy-action@v1 with `id-token: write`; a push of any branch that lacks the file deploys nothing.", }, { kind: "open-url", diff --git a/skills/prisma-platform-core-concepts/SKILL.md b/skills/prisma-platform-core-concepts/SKILL.md index ae11b5b2..bd768259 100644 --- a/skills/prisma-platform-core-concepts/SKILL.md +++ b/skills/prisma-platform-core-concepts/SKILL.md @@ -176,9 +176,12 @@ jobs: build-command: npm run build ``` -From then on, every push runs the workflow. A push to the default branch -deploys production; a push to any other branch creates or updates that -branch's preview environment, so previews come free with every branch. +From then on, every push of a branch that carries the workflow file runs +it; GitHub reads workflows from the pushed commit, so a branch created +before the file was added deploys nothing until it contains the file. A +push to the default branch deploys production; a push to any other branch +creates or updates that branch's preview environment, so previews come free +with every branch. Opening a pull request does not itself deploy anything; previews track branch pushes. A connected repository without the workflow gets branch bookkeeping and preview teardown from the platform, and no builds. From d614baafc33b99ab40b33906a48b12c2b754c200 Mon Sep 17 00:00:00 2001 From: Kristof Siket Date: Tue, 15 Sep 2026 14:59:21 +0200 Subject: [PATCH 3/3] docs(cli): document connectPresentations Co-Authored-By: Claude Fable 5.1 --- packages/cli/src/commands/git/connect.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/cli/src/commands/git/connect.ts b/packages/cli/src/commands/git/connect.ts index 32919033..8a436c3d 100644 --- a/packages/cli/src/commands/git/connect.ts +++ b/packages/cli/src/commands/git/connect.ts @@ -132,6 +132,8 @@ async function resolveInstalledRepository( return match; } +/** The connect result in every mode: the connection card, plus the + * workflow step the platform will not do for you. */ function connectPresentations( result: ProjectRepositoryConnectionResult, ): Presentations {