From e29ca4eefd79173e225013d68367ba1d56d73170 Mon Sep 17 00:00:00 2001 From: Kristof Siket Date: Tue, 25 Aug 2026 11:42:42 +0200 Subject: [PATCH 1/2] Document the GitHub Actions push-to-deploy flow for Composer apps The GitHub integration page described platform-side webhook builds ("push builds the pushed commit"), which is not how deploys work: deploys run in the repository's own GitHub Actions through prisma/cloud-deploy-action, while the connection contributes the OIDC credential exchange and the branch lifecycle automation (preview teardown on branch delete). - Add compute/deploy-on-push.mdx: a walkthrough from a locally deployed Composer app to push-to-deploy with per-branch preview stages, validated end to end against a real pipeline on 2026-08-25. - Rewrite compute/github.mdx around what the connection actually does, including the two entry paths (Console adds the workflow via PR, the CLI path does not) and the interactive-only git connect. - Align branching, deployments, index, cli/v8/git, composer/deploying, and the full-stack tutorial's next step with the real flow. Co-Authored-By: Claude Fable 5 --- .../docs/(index)/full-stack-tutorial.mdx | 2 +- apps/docs/content/docs/cli/git.mdx | 6 +- apps/docs/content/docs/composer/deploying.mdx | 4 +- apps/docs/content/docs/compute/branching.mdx | 3 +- .../content/docs/compute/deploy-on-push.mdx | 155 ++++++++++++++++++ .../docs/content/docs/compute/deployments.mdx | 4 +- apps/docs/content/docs/compute/github.mdx | 52 +++--- apps/docs/content/docs/compute/index.mdx | 2 +- apps/docs/content/docs/compute/meta.json | 1 + 9 files changed, 192 insertions(+), 37 deletions(-) create mode 100644 apps/docs/content/docs/compute/deploy-on-push.mdx diff --git a/apps/docs/content/docs/(index)/full-stack-tutorial.mdx b/apps/docs/content/docs/(index)/full-stack-tutorial.mdx index 150edb0363..9dd2e941fb 100644 --- a/apps/docs/content/docs/(index)/full-stack-tutorial.mdx +++ b/apps/docs/content/docs/(index)/full-stack-tutorial.mdx @@ -259,4 +259,4 @@ npx prisma@latest project delete --confirm - [Pick your framework](/guides): the same journey for Next.js, Nuxt, Astro, NestJS, TanStack Start, and more. - [Branching and previews](/compute/branching): every Git branch gets an isolated deployment. - [Learn the fundamentals](/orm/fundamentals/reading-data): reading, writing, relations, and transactions. -- [Deploy on push](/compute/github): connect GitHub so every commit deploys itself. +- [Deploy on push](/compute/deploy-on-push): connect GitHub so every commit deploys itself, with a preview environment per branch. diff --git a/apps/docs/content/docs/cli/git.mdx b/apps/docs/content/docs/cli/git.mdx index f7d94e8b9d..f8706110dd 100644 --- a/apps/docs/content/docs/cli/git.mdx +++ b/apps/docs/content/docs/cli/git.mdx @@ -6,7 +6,7 @@ metaTitle: git | Prisma 8 CLI metaDescription: Learn how to connect and disconnect a GitHub repository for Prisma Compute push-to-deploy with the unified Prisma CLI. --- -Use `git` commands to manage the GitHub repository connection. See [GitHub integration](/compute/github). +Use `git` commands to manage the GitHub repository connection. Connecting enables the OIDC credential exchange for GitHub Actions deploys and the branch lifecycle automation; the deploys themselves run in your repository's own workflow. See [GitHub integration](/compute/github) and [Deploy on push](/compute/deploy-on-push). ## Usage @@ -14,9 +14,11 @@ Use `git` commands to manage the GitHub repository connection. See [GitHub integ npx prisma@latest git connect ``` +Run it from a [linked](/cli/project) project directory. The command is interactive: it opens the browser to install the GitHub App when needed and waits for the install, so `--no-interactive` fails with `CLI.INTERACTION_REQUIRED`. Connecting from the CLI does not add a deploy workflow to the repository; [add it yourself](/compute/deploy-on-push#4-add-the-deploy-workflow), or connect through the [Console](https://pris.ly/pdp), which opens a pull request with the workflow. + ## Commands | Command | Description | | ------------------------ | ----------------------------------------------------------------- | | `git connect [git-url]` | Connect the linked project to a GitHub repository. Starts the GitHub App install flow if needed | -| `git disconnect` | Stop push-triggered automation. Keeps the project and existing branches | +| `git disconnect` | Stop the credential exchange and branch automation. Keeps the project and existing branches | diff --git a/apps/docs/content/docs/composer/deploying.mdx b/apps/docs/content/docs/composer/deploying.mdx index 2d1decbf40..9015968f4d 100644 --- a/apps/docs/content/docs/composer/deploying.mdx +++ b/apps/docs/content/docs/composer/deploying.mdx @@ -108,7 +108,9 @@ Destroying a stage removes its resources, then deletes its branch along with the ## CI -CI runs the same commands as your machine: set the two credential variables as CI secrets, build, and deploy. The per-PR environment pattern: +On GitHub, the ready-made path is [Deploy on push](/compute/deploy-on-push): connect the repository and add [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action) to your workflow. The action derives the target from the branch, so the default branch deploys production and every other branch deploys its own stage, and connected repositories authenticate through GitHub's OIDC tokens with no secrets at all. + +Any other CI runs the same commands as your machine: set the two credential variables as CI secrets, build, and deploy. The per-PR environment pattern: ```npm npx prisma@latest deploy module.ts --stage "pr-$PR_NUMBER" # on push diff --git a/apps/docs/content/docs/compute/branching.mdx b/apps/docs/content/docs/compute/branching.mdx index 69306ba9a1..b2c260e7bc 100644 --- a/apps/docs/content/docs/compute/branching.mdx +++ b/apps/docs/content/docs/compute/branching.mdx @@ -47,7 +47,7 @@ Listing branches doesn't expand the services and databases inside them. Use the You rarely create branches manually. They are created automatically: -- **From GitHub**: when a repo is connected, branch and push events create or update the matching platform branch automatically. To set this up, see the [GitHub integration docs](/compute/github). +- **From GitHub**: when a repo is connected, creating a Git branch creates the matching platform branch, and your repository's [deploy workflow](/compute/deploy-on-push) deploys each push to it as a preview. To set this up, see the [GitHub integration docs](/compute/github). - **From the CLI**: commands that target a branch that doesn't exist yet, such as `service create --branch feature/search` or a [Composer stage deploy](/composer/deploying), create it. Connecting GitHub doesn't create branches retroactively. It aligns your default branch with the repo's default branch and wires up automation for future events. @@ -59,4 +59,5 @@ When GitHub is connected, deleting a Git branch tears down the matching platform ## Next steps - [Environment variables](/compute/environment-variables): preview values and per-branch overrides. +- [Deploy on push](/compute/deploy-on-push): a preview environment for every branch you push. - [GitHub integration](/compute/github): keep platform branches in sync with your repo. diff --git a/apps/docs/content/docs/compute/deploy-on-push.mdx b/apps/docs/content/docs/compute/deploy-on-push.mdx new file mode 100644 index 0000000000..d07c140130 --- /dev/null +++ b/apps/docs/content/docs/compute/deploy-on-push.mdx @@ -0,0 +1,155 @@ +--- +title: Deploy on push +description: Graduate a Composer app from manual deploys to a Git workflow, with production deploys on push and an isolated preview environment per branch. +url: /compute/deploy-on-push +metaTitle: Deploy on push | Prisma Compute +metaDescription: Connect a GitHub repository and deploy a Prisma Composer app from GitHub Actions with prisma/cloud-deploy-action - production on the default branch, isolated preview stages per branch, automatic teardown. +--- + +You have a [Composer](/composer) app that deploys from your terminal with `deploy module.ts`, the way the [full-stack tutorial](/full-stack-tutorial) left you. This guide graduates it to a Git workflow: + +- A push to your default branch deploys **production**. +- A push to any other branch deploys an isolated **preview stage**: its own services, its own databases, its own buckets, its own URL. +- Deleting the branch tears the preview down. +- No secrets land in the repository: workflow runs authenticate through GitHub's OIDC tokens. + +## How the pieces fit + +Push-to-deploy is two complementary halves, and you set up both: + +1. **The repository connection** ([`git connect`](/cli/git)) installs the Prisma GitHub App and registers the repository against your project. That enables the **credential exchange**, so your GitHub Actions runs can trade their OIDC token for a short-lived workspace token, and the **branch lifecycle automation**, so deleting a Git branch tears down the matching preview. +2. **The deploy workflow** ([prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action)) runs in your own repository's GitHub Actions. On every push it installs dependencies, runs your build, and hands the result to the [`deploy` command](/cli/deploy), targeting production or a stage named after the branch. + +Each half is inert without the other. A connection with no workflow deploys nothing: connecting wires up automation, it doesn't build your commits. A workflow with no connection stays green but skips: without a credential the action reports `skipped-no-credential` and exits successfully, which is also why the workflow is harmless on forks. + +There are two ways in. Connecting through the [Console](https://pris.ly/pdp) opens a pull request that adds the workflow for you, so both halves arrive together. Connecting from the CLI, as this guide does, sets up the connection only: you add the workflow file yourself in step 4. + +## Prerequisites + +- A Composer app that builds and deploys from your machine. If you don't have one yet, the [full-stack tutorial](/full-stack-tutorial) gets you there in about 15 minutes. +- Admin access to the GitHub repository, so you can install the Prisma GitHub App. + +## 1. Push the project to GitHub + +If the app isn't on GitHub yet, create a repository from the project directory and push it. With the [GitHub CLI](https://cli.github.com/): + +```bash +gh repo create my-app --private --source . --push +``` + +## 2. Link the directory to the project + +The `git` commands operate on the project this directory is linked to. If you already deployed from this directory, it is linked. Otherwise, link it to the project your deploys created: + +```npm +npx prisma@latest project link my-app +``` + +Run this in the project root, next to `package.json` and `module.ts`. Linking pins the **current** directory (in a gitignored `.prisma/local.json`), and it will happily pin a parent directory without a warning; commands run from the project then fail with `PROJECT.SETUP_REQUIRED`. See the [`project` command reference](/cli/project) for how the link is resolved. + +## 3. Connect the repository + +```npm +npx prisma@latest git connect https://github.com/you/my-app +``` + +The command opens the browser to install the Prisma GitHub App on the repository if it isn't installed yet, then registers the connection. It needs you at the terminal: the install flow is interactive, and `--no-interactive` fails with `CLI.INTERACTION_REQUIRED` rather than printing an install URL to follow later. If you can't run it interactively, connect the repository through the [Console](https://pris.ly/pdp) instead. + +Connecting the CLI way does not add a workflow to the repository, and it does not deploy anything on its own. That's the next step. + +## 4. Add the deploy workflow + +Commit a workflow that runs [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action) on every push: + +```yaml title=".github/workflows/prisma-deploy.yml" +name: prisma-deploy + +on: + push: + +concurrency: + group: prisma-deploy-${{ github.ref }} + cancel-in-progress: false + +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: 22 + - uses: oven-sh/setup-bun@v2 + - uses: prisma/cloud-deploy-action@v1 + with: + build-command: npm run build +``` + +Three lines carry the weight: + +- **`id-token: write`** lets the job request an OIDC token from GitHub. The action exchanges it for a Prisma workspace token that expires after 30 minutes. That exchange only succeeds for the repository you connected in step 3, and it is the reason the workflow needs no secrets. +- **`build-command`** is your build, run verbatim. The action never guesses how to build your app; a repository that runs its source directly sets `build-command: none`. +- **`oven-sh/setup-bun@v2`** puts Bun on the runner PATH, which the action requires. + +The action deploys with the repository's own installed `prisma` version when it finds one, so keep your `prisma` devDependency current. The action's [README](https://github.com/prisma/cloud-deploy-action) documents every input, including `module` for an entry file that isn't `module.ts` and `working-directory` for monorepos. + +## 5. Push to deploy production + +Commit the workflow and push to your default branch. In the repository's **Actions** tab, the `prisma-deploy` run installs, builds, and deploys, and ends by printing the same deploy report you know from your terminal, public URL included: + +```text no-copy +my-app +├─ db postgres-database db_def456 +└─ api compute-service cps_abc123 + https://xyz.ewr.prisma.build +``` + +From here on, the default branch is your production pipeline: every push to it deploys production, and re-deploys are idempotent updates, exactly as if you had run `deploy module.ts` yourself. + +## 6. Preview a branch + +Push any other branch: + +```bash +git switch -c feature/search +git push -u origin feature/search +``` + +The action deploys it as a [stage](/composer/deploying#production-and-stages) named after the branch, which is a [preview branch](/compute/branching) of the same project: its own compute services, its own databases (assigned to the preview branch, not production), its own buckets, and its own URL. The only thing it shares with production is the code. Inspect it like any branch: + +```npm +npx prisma@latest service list --branch feature/search +``` + +Iterate on the branch and every push updates the same preview. The preview's configuration comes from the branch's [environment variables](/compute/environment-variables), so a preview never reads production values. + +## 7. Delete the branch to clean up + +```bash +git push origin --delete feature/search +``` + +The platform's branch automation, wired up by `git connect` in step 3, tears down the matching preview: services, databases, and buckets are removed. Teardown comes from the repository connection, not from the workflow, so it works even when no Actions run fires for the deletion. Your production and default branches are never touched by automated cleanup. + +## Forks and unconnected repositories + +GitHub does not mint OIDC tokens for workflow runs triggered from forks, and the credential exchange refuses repositories that aren't connected. In both cases the action skips instead of failing: the run stays green, prints a notice, and sets its `outcome` output to `skipped-no-credential`. Contributors can fork your repository without their pushes failing CI or reaching your workspace. + +## Troubleshooting + +- **The deploy step fails with `CLI.UNKNOWN_COMMAND`.** The action release predates the unified CLI: releases up to v1.5.0 invoke the `prisma composer` subcommands, which were removed in `prisma` `8.0.0-rc.8`. Use a release that invokes the top-level `deploy` command (see the action's [releases](https://github.com/prisma/cloud-deploy-action/releases)). +- **Commands fail with `PROJECT.SETUP_REQUIRED`.** The directory isn't linked, or you linked a parent directory. Re-run `project link` in the project root (step 2). +- **`git connect` fails with `CLI.INTERACTION_REQUIRED`.** The command can't complete non-interactively. Run it at a terminal, or connect through the [Console](https://pris.ly/pdp). +- **Runs are green but nothing deploys.** Check the run's log for `skipped-no-credential`: the repository isn't connected (step 3), or the run came from a fork. + +## Next steps + +- [GitHub integration](/compute/github): what the repository connection is and does. +- [Branching](/compute/branching): how preview branches relate to Git branches. +- [Deploying](/composer/deploying): stages, deploy state, and per-stage secrets, which all apply to CI deploys. +- [Environment variables](/compute/environment-variables): per-branch configuration for previews. diff --git a/apps/docs/content/docs/compute/deployments.mdx b/apps/docs/content/docs/compute/deployments.mdx index c592f075aa..1f712cfc8c 100644 --- a/apps/docs/content/docs/compute/deployments.mdx +++ b/apps/docs/content/docs/compute/deployments.mdx @@ -12,7 +12,7 @@ A deploy produces a **version** of a service: one built artifact that can serve Versions are created three ways: -- **A git push.** After you [connect a GitHub repository](/compute/github), pushing a branch builds and deploys it: the default Git branch deploys to production, and every other branch gets an isolated preview. +- **A git push.** After you [set up deploy on push](/compute/deploy-on-push), your repository's GitHub Actions workflow builds and deploys each pushed branch: the default Git branch deploys to production, and every other branch gets an isolated preview. - **The [Console](https://pris.ly/pdp).** Trigger a build and deploy from the browser. - **[`deploy`](/cli/deploy).** For a [Prisma Composer](/composer) app, `deploy` assembles the services you have already built and provisions them from your terminal or CI. @@ -80,6 +80,6 @@ This permanently deletes the service from the branch you target with `--branch`. ## Next steps - [Environment variables](/compute/environment-variables): persist config across deploys. -- [GitHub integration](/compute/github): the push-to-deploy flow in detail. +- [Deploy on push](/compute/deploy-on-push): the push-to-deploy flow in detail. - [Domains](/compute/domains): point a custom domain at production. - [Prisma Composer](/composer): declare the app the `deploy` command deploys. diff --git a/apps/docs/content/docs/compute/github.mdx b/apps/docs/content/docs/compute/github.mdx index bfc185cee4..952b0e32b1 100644 --- a/apps/docs/content/docs/compute/github.mdx +++ b/apps/docs/content/docs/compute/github.mdx @@ -1,12 +1,17 @@ --- title: GitHub -description: Connect a GitHub repository to a project and Prisma deploys on every push, with previews tracking your Git branches. +description: Connect a GitHub repository to a project to authenticate your Actions deploys and keep platform branches in sync with your Git branches. url: /compute/github metaTitle: GitHub integration | Prisma Compute -metaDescription: Connect a GitHub repository to Prisma Compute, deploy on push, and map repository branches to platform branches automatically. +metaDescription: Connect a GitHub repository to Prisma Compute to enable OIDC-authenticated deploys from GitHub Actions and automatic preview teardown when branches are deleted. --- -Connect a GitHub repository to a project and Prisma deploys on every push. Branch and push events map to platform branches automatically, so your previews track your Git branches. +Connecting a GitHub repository wires a project to your repo. The deploys themselves run in your own GitHub Actions, through [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action); what the connection contributes is everything around them: + +- **Credentials.** Workflow runs in the connected repository exchange their GitHub OIDC token for a short-lived Prisma workspace token, so the deploy workflow needs no secrets. +- **Branch lifecycle.** Branch events keep the matching platform branches in sync, including tearing a preview down when its Git branch is deleted. + +For the full setup, entry file to live preview, follow [Deploy on push](/compute/deploy-on-push). ## How it works @@ -14,12 +19,17 @@ The connection has two levels: -The workspace owns the GitHub App installation; each project points at a single repository. Once connected, Prisma listens for that repo's branch events and keeps the matching platform branches in sync. +The workspace owns the GitHub App installation; each project points at a single repository. Once connected, Prisma verifies the repository identity behind each credential exchange and listens for the repo's branch events. In beta, a project connects to one repository. ## Connect a repo +There are two ways in, and they don't set up the same things: + +- **Through the [Console](https://pris.ly/pdp)**: connecting a repository also opens a pull request that adds the deploy workflow, so the connection and the workflow arrive together. +- **From the CLI**: `git connect` sets up the connection only. You [add the workflow yourself](/compute/deploy-on-push#4-add-the-deploy-workflow). + From a linked project directory, connect your Git origin: ```npm @@ -32,11 +42,7 @@ To name the repository explicitly: npx prisma@latest git connect https://github.com/acme/shop ``` -If the GitHub App isn't installed yet, the CLI starts the install flow. In `--json` / `--no-interactive` mode it doesn't block: it prints the install URL to finish in the browser, so automation can hand the install off: - -```npm -npx prisma@latest git connect https://github.com/acme/shop --json --no-interactive -``` +If the GitHub App isn't installed yet, the CLI opens the browser to finish the install. The command is interactive: it waits for the install to complete, and `--no-interactive` fails with `CLI.INTERACTION_REQUIRED` rather than handing off an install URL. For headless setups, connect through the Console instead. Disconnect when you're done: @@ -44,37 +50,25 @@ Disconnect when you're done: npx prisma@latest git disconnect ``` -Disconnecting stops future automation. It doesn't delete the project or tear down existing branches. +Disconnecting stops the credential exchange and the branch automation. It doesn't delete the project or tear down existing branches. -## What events do +## What the connection does Once a project is connected: +- **Actions runs can authenticate.** A workflow job with `id-token: write` gets a workspace token through the OIDC exchange, valid for 30 minutes and only issued for the connected repository. Unconnected repositories and forks are refused, which the deploy action treats as "skip, stay green". - **Branch created** → creates the matching platform branch. -- **Push** → creates or resolves the matching branch and builds the pushed commit. -- **Branch deleted** → tears down the matching branch, unless it's the production or default branch. - -Connecting doesn't deploy anything on its own. It wires up automation for *future* events. Push a commit to trigger the first build. - -## CI and monorepos - -For an app with several services, declare them with [Prisma Composer](/composer) and deploy from CI with the [`deploy` command](/cli/deploy). Watch a service from CI or a terminal with a service token and explicit targets: - -```bash -PRISMA_SERVICE_TOKEN=... npx prisma@latest service show web \ - --project my-app \ - --json \ - --no-interactive -``` +- **Branch deleted** → tears down the matching platform branch and everything on it, unless it's the production or default branch. Those are always left alone. +- **Push** → deployed by your repository's own workflow, not by the platform. Connecting doesn't build or deploy anything on its own: a connected repo with no deploy workflow deploys nothing. -For pipelines that need a CLI-driven deploy rather than the push automation, use [Prisma Composer](/composer/deploying), which deploys from any CI with the same service token. +Connecting doesn't create branches retroactively either. It aligns your default branch with the repo's default branch and wires up automation for future events. ## What's not in beta -GitHub is the only supported provider; others return `REPO_PROVIDER_UNSUPPORTED`. The webhook path is branch- and push-driven. Each webhook deploy posts a "Prisma Compute Deploy" check run on the commit (success or failure, with the deploy URL) on a best-effort basis. Pull-request comments and preview comments aren't part of the beta surface. +GitHub is the only supported provider; others return `REPO_PROVIDER_UNSUPPORTED`. Pull-request comments and preview comments aren't part of the beta surface. ## Next steps +- [Deploy on push](/compute/deploy-on-push): the full walkthrough, from connection to per-branch previews. - [Branching](/compute/branching): how platform branches map to Git. -- [Deployments](/compute/deployments): what happens after a push builds. - [Environment variables](/compute/environment-variables): per-branch config for previews. diff --git a/apps/docs/content/docs/compute/index.mdx b/apps/docs/content/docs/compute/index.mdx index 33ebbf7622..85e245c1cb 100644 --- a/apps/docs/content/docs/compute/index.mdx +++ b/apps/docs/content/docs/compute/index.mdx @@ -38,7 +38,7 @@ Compute organizes everything into a few resources: - A **branch** maps to a Git branch in the linked repository. Each branch is an isolated environment with its own services, environment variables, and deployments, and can have its own database. - A **service** is an HTTP application, such as a frontend or backend. Each deploy of a service creates a **version**. One version is live at a time. -The default Git branch (usually `main`) is the **production** branch. Every other branch is a **preview** branch with its own Compute resources: services, deployments, and environment variables. Data isolation is yours to configure. A preview deploy reads the preview-scoped variables. If preview work must not touch production data, point the preview `DATABASE_URL` at a non-production database. See [Environment variables](/compute/environment-variables) for details. After you [connect a GitHub repository](/compute/github), pushing to a branch builds and deploys that branch automatically. +The default Git branch (usually `main`) is the **production** branch. Every other branch is a **preview** branch with its own Compute resources: services, deployments, and environment variables. Data isolation is yours to configure. A preview deploy reads the preview-scoped variables. If preview work must not touch production data, point the preview `DATABASE_URL` at a non-production database. See [Environment variables](/compute/environment-variables) for details. After you [set up deploy on push](/compute/deploy-on-push), pushing to a branch deploys that branch from your repository's GitHub Actions. The animation below shows how a project, its branches, and their infrastructure fit together, and how each branch's variables resolve by scope: diff --git a/apps/docs/content/docs/compute/meta.json b/apps/docs/content/docs/compute/meta.json index 91ac35489b..d396c756d7 100644 --- a/apps/docs/content/docs/compute/meta.json +++ b/apps/docs/content/docs/compute/meta.json @@ -16,6 +16,7 @@ "domains", "---Integrations---", "github", + "deploy-on-push", "deploy-button", "alchemy", "---More---", From 05ca829241f9701004a406817d7fc1a2527d6c4f Mon Sep 17 00:00:00 2001 From: Kristof Siket Date: Tue, 25 Aug 2026 11:51:07 +0200 Subject: [PATCH 2/2] Rework the push-to-deploy pages to follow the docs-writer style Apply the docs-writer skill's conventions to the new and rewritten pages: remove em dashes, contrast slogans, coined phrasings, and stacked absolutes; move failure notes inline with the step where the reader hits them instead of a separate troubleshooting section; trim the next-steps lists. Co-Authored-By: Claude Fable 5 --- apps/docs/content/docs/cli/git.mdx | 4 +- apps/docs/content/docs/composer/deploying.mdx | 2 +- .../content/docs/compute/deploy-on-push.mdx | 77 ++++++++----------- apps/docs/content/docs/compute/github.mdx | 18 ++--- 4 files changed, 42 insertions(+), 59 deletions(-) diff --git a/apps/docs/content/docs/cli/git.mdx b/apps/docs/content/docs/cli/git.mdx index f8706110dd..5a3eb5496a 100644 --- a/apps/docs/content/docs/cli/git.mdx +++ b/apps/docs/content/docs/cli/git.mdx @@ -6,7 +6,7 @@ metaTitle: git | Prisma 8 CLI metaDescription: Learn how to connect and disconnect a GitHub repository for Prisma Compute push-to-deploy with the unified Prisma CLI. --- -Use `git` commands to manage the GitHub repository connection. Connecting enables the OIDC credential exchange for GitHub Actions deploys and the branch lifecycle automation; the deploys themselves run in your repository's own workflow. See [GitHub integration](/compute/github) and [Deploy on push](/compute/deploy-on-push). +Use `git` commands to manage the GitHub repository connection. Connecting enables the OIDC credential exchange for GitHub Actions deploys and the branch lifecycle automation. See [GitHub integration](/compute/github) and [Deploy on push](/compute/deploy-on-push). ## Usage @@ -14,7 +14,7 @@ Use `git` commands to manage the GitHub repository connection. Connecting enable npx prisma@latest git connect ``` -Run it from a [linked](/cli/project) project directory. The command is interactive: it opens the browser to install the GitHub App when needed and waits for the install, so `--no-interactive` fails with `CLI.INTERACTION_REQUIRED`. Connecting from the CLI does not add a deploy workflow to the repository; [add it yourself](/compute/deploy-on-push#4-add-the-deploy-workflow), or connect through the [Console](https://pris.ly/pdp), which opens a pull request with the workflow. +Run it from a [linked](/cli/project) project directory. The command needs an interactive terminal: it opens the browser to install the GitHub App when needed and waits for the install. With `--no-interactive` it fails with `CLI.INTERACTION_REQUIRED`. Connecting from the CLI does not add a deploy workflow to the repository. [Add it yourself](/compute/deploy-on-push#4-add-the-deploy-workflow), or connect through the [Console](https://pris.ly/pdp), which opens a pull request with the workflow. ## Commands diff --git a/apps/docs/content/docs/composer/deploying.mdx b/apps/docs/content/docs/composer/deploying.mdx index 9015968f4d..67a76be854 100644 --- a/apps/docs/content/docs/composer/deploying.mdx +++ b/apps/docs/content/docs/composer/deploying.mdx @@ -108,7 +108,7 @@ Destroying a stage removes its resources, then deletes its branch along with the ## CI -On GitHub, the ready-made path is [Deploy on push](/compute/deploy-on-push): connect the repository and add [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action) to your workflow. The action derives the target from the branch, so the default branch deploys production and every other branch deploys its own stage, and connected repositories authenticate through GitHub's OIDC tokens with no secrets at all. +On GitHub, connect the repository and add [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action) to a workflow instead of scripting the deploy yourself. The action derives the target from the branch: the default branch deploys production, and every other branch deploys a stage named after it. Connected repositories authenticate through GitHub's OIDC tokens, without a stored secret. [Deploy on push](/compute/deploy-on-push) walks through the setup. Any other CI runs the same commands as your machine: set the two credential variables as CI secrets, build, and deploy. The per-PR environment pattern: diff --git a/apps/docs/content/docs/compute/deploy-on-push.mdx b/apps/docs/content/docs/compute/deploy-on-push.mdx index d07c140130..6c95888fad 100644 --- a/apps/docs/content/docs/compute/deploy-on-push.mdx +++ b/apps/docs/content/docs/compute/deploy-on-push.mdx @@ -6,32 +6,27 @@ metaTitle: Deploy on push | Prisma Compute metaDescription: Connect a GitHub repository and deploy a Prisma Composer app from GitHub Actions with prisma/cloud-deploy-action - production on the default branch, isolated preview stages per branch, automatic teardown. --- -You have a [Composer](/composer) app that deploys from your terminal with `deploy module.ts`, the way the [full-stack tutorial](/full-stack-tutorial) left you. This guide graduates it to a Git workflow: +You have a [Composer](/composer) app that you deploy by running `deploy module.ts` in a terminal. In this guide you connect its GitHub repository and add a deploy workflow, so pushing replaces that manual step: a push to the default branch updates production, every other branch gets an isolated preview environment, and deleting a branch cleans its preview up. -- A push to your default branch deploys **production**. -- A push to any other branch deploys an isolated **preview stage**: its own services, its own databases, its own buckets, its own URL. -- Deleting the branch tears the preview down. -- No secrets land in the repository: workflow runs authenticate through GitHub's OIDC tokens. +## How it works -## How the pieces fit +Push-to-deploy has two parts, and you set up both: -Push-to-deploy is two complementary halves, and you set up both: +1. **The repository connection.** [`git connect`](/cli/git) installs the Prisma GitHub App and registers the repository with your project. This lets workflow runs authenticate: a job exchanges its GitHub OIDC token for a Prisma workspace token that expires after 30 minutes, so the workflow needs no repository secrets. The connection also subscribes the project to branch events, which is what tears a preview down when its Git branch is deleted. +2. **The deploy workflow.** [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action) runs in your repository's GitHub Actions. On each push it installs dependencies, runs your build, and runs the [`deploy` command](/cli/deploy) against production or a stage named after the branch. -1. **The repository connection** ([`git connect`](/cli/git)) installs the Prisma GitHub App and registers the repository against your project. That enables the **credential exchange**, so your GitHub Actions runs can trade their OIDC token for a short-lived workspace token, and the **branch lifecycle automation**, so deleting a Git branch tears down the matching preview. -2. **The deploy workflow** ([prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action)) runs in your own repository's GitHub Actions. On every push it installs dependencies, runs your build, and hands the result to the [`deploy` command](/cli/deploy), targeting production or a stage named after the branch. +Connecting a repository does not deploy it; deploys come from the workflow. Without the connection, the workflow has no credential: the action prints a notice, sets its `outcome` output to `skipped-no-credential`, and exits successfully, so the run stays green. -Each half is inert without the other. A connection with no workflow deploys nothing: connecting wires up automation, it doesn't build your commits. A workflow with no connection stays green but skips: without a credential the action reports `skipped-no-credential` and exits successfully, which is also why the workflow is harmless on forks. - -There are two ways in. Connecting through the [Console](https://pris.ly/pdp) opens a pull request that adds the workflow for you, so both halves arrive together. Connecting from the CLI, as this guide does, sets up the connection only: you add the workflow file yourself in step 4. +You can connect in the [Console](https://pris.ly/pdp) or from the CLI. The Console opens a pull request that adds the workflow file at the same time. The CLI registers the connection only, and you add the workflow file yourself. This guide uses the CLI. ## Prerequisites -- A Composer app that builds and deploys from your machine. If you don't have one yet, the [full-stack tutorial](/full-stack-tutorial) gets you there in about 15 minutes. -- Admin access to the GitHub repository, so you can install the Prisma GitHub App. +- A Composer app that builds and deploys from your machine. The [full-stack tutorial](/full-stack-tutorial) ends with one. +- Admin access to the GitHub repository, so you can install the Prisma GitHub App on it. ## 1. Push the project to GitHub -If the app isn't on GitHub yet, create a repository from the project directory and push it. With the [GitHub CLI](https://cli.github.com/): +If the app is not on GitHub yet, create a repository from the project directory and push it. With the [GitHub CLI](https://cli.github.com/): ```bash gh repo create my-app --private --source . --push @@ -39,27 +34,27 @@ gh repo create my-app --private --source . --push ## 2. Link the directory to the project -The `git` commands operate on the project this directory is linked to. If you already deployed from this directory, it is linked. Otherwise, link it to the project your deploys created: +The `git` commands operate on the project this directory is linked to. If you have deployed from this directory before, it is already linked and you can skip this step. Otherwise, link it to the project your deploys created: ```npm npx prisma@latest project link my-app ``` -Run this in the project root, next to `package.json` and `module.ts`. Linking pins the **current** directory (in a gitignored `.prisma/local.json`), and it will happily pin a parent directory without a warning; commands run from the project then fail with `PROJECT.SETUP_REQUIRED`. See the [`project` command reference](/cli/project) for how the link is resolved. +Run the command in the project root, next to `module.ts`. Linking records the current directory, and it accepts a parent directory without a warning. If later commands fail with `PROJECT.SETUP_REQUIRED`, re-run `project link` from the project root. See the [`project` command reference](/cli/project) for how the link is stored and resolved. ## 3. Connect the repository +Connect the project to the repository from step 1: + ```npm npx prisma@latest git connect https://github.com/you/my-app ``` -The command opens the browser to install the Prisma GitHub App on the repository if it isn't installed yet, then registers the connection. It needs you at the terminal: the install flow is interactive, and `--no-interactive` fails with `CLI.INTERACTION_REQUIRED` rather than printing an install URL to follow later. If you can't run it interactively, connect the repository through the [Console](https://pris.ly/pdp) instead. - -Connecting the CLI way does not add a workflow to the repository, and it does not deploy anything on its own. That's the next step. +The command opens your browser to install the Prisma GitHub App if it is not installed yet, then registers the connection. It needs an interactive terminal. With `--no-interactive` it fails with `CLI.INTERACTION_REQUIRED`; if you cannot run it interactively, connect through the [Console](https://pris.ly/pdp) instead. ## 4. Add the deploy workflow -Commit a workflow that runs [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action) on every push: +Commit a workflow that runs the deploy action on every push: ```yaml title=".github/workflows/prisma-deploy.yml" name: prisma-deploy @@ -90,17 +85,17 @@ jobs: build-command: npm run build ``` -Three lines carry the weight: +A few settings to be aware of: -- **`id-token: write`** lets the job request an OIDC token from GitHub. The action exchanges it for a Prisma workspace token that expires after 30 minutes. That exchange only succeeds for the repository you connected in step 3, and it is the reason the workflow needs no secrets. -- **`build-command`** is your build, run verbatim. The action never guesses how to build your app; a repository that runs its source directly sets `build-command: none`. -- **`oven-sh/setup-bun@v2`** puts Bun on the runner PATH, which the action requires. +- `id-token: write` lets the job request the OIDC token that the action exchanges for a workspace token. Without this permission the exchange cannot happen and the run skips. +- `build-command` runs verbatim. The action does not detect your framework or build for you. If the app runs its source directly, set `build-command: none`. +- The action requires Bun on the runner PATH, which `oven-sh/setup-bun@v2` provides. -The action deploys with the repository's own installed `prisma` version when it finds one, so keep your `prisma` devDependency current. The action's [README](https://github.com/prisma/cloud-deploy-action) documents every input, including `module` for an entry file that isn't `module.ts` and `working-directory` for monorepos. +When the repository has a `prisma` devDependency, the action deploys with that installed version, so keep it current. The action's [README](https://github.com/prisma/cloud-deploy-action) documents the remaining inputs, including `module` for an entry file that is not `module.ts` and `working-directory` for monorepos. ## 5. Push to deploy production -Commit the workflow and push to your default branch. In the repository's **Actions** tab, the `prisma-deploy` run installs, builds, and deploys, and ends by printing the same deploy report you know from your terminal, public URL included: +Commit the workflow and push to your default branch. In the repository's **Actions** tab, the `prisma-deploy` run installs, builds, and deploys, and ends with the same deploy report you know from your terminal: ```text no-copy my-app @@ -109,47 +104,39 @@ my-app https://xyz.ewr.prisma.build ``` -From here on, the default branch is your production pipeline: every push to it deploys production, and re-deploys are idempotent updates, exactly as if you had run `deploy module.ts` yourself. +Every later push to the default branch updates production the same way, as if you had run `deploy module.ts` yourself. + +If the deploy step fails with `CLI.UNKNOWN_COMMAND`, the action release predates the unified CLI: releases up to v1.5.0 call the removed `prisma composer` commands. Use a release that runs the top-level `deploy` command; the action's [releases page](https://github.com/prisma/cloud-deploy-action/releases) lists what changed in each. If the run is green but its log shows `skipped-no-credential`, the repository is not connected; repeat step 3. Runs triggered from forks skip the same way, because GitHub does not issue OIDC tokens to them, so contributors' pushes keep a green CI without reaching your workspace. ## 6. Preview a branch -Push any other branch: +Push a branch to try the preview flow: ```bash git switch -c feature/search git push -u origin feature/search ``` -The action deploys it as a [stage](/composer/deploying#production-and-stages) named after the branch, which is a [preview branch](/compute/branching) of the same project: its own compute services, its own databases (assigned to the preview branch, not production), its own buckets, and its own URL. The only thing it shares with production is the code. Inspect it like any branch: +The action deploys the branch as a [stage](/composer/deploying#production-and-stages) named after it, which is a [preview branch](/compute/branching) of the same project. The preview has its own services, its own databases assigned to that branch, its own buckets, and its own URL. The only thing it shares with production is the code. Confirm it from your terminal: ```npm npx prisma@latest service list --branch feature/search ``` -Iterate on the branch and every push updates the same preview. The preview's configuration comes from the branch's [environment variables](/compute/environment-variables), so a preview never reads production values. +Further pushes to the branch update the same preview. Its configuration comes from the branch's [environment variables](/compute/environment-variables), so a preview reads preview-scoped values rather than production ones. ## 7. Delete the branch to clean up +When the branch has served its purpose, delete it: + ```bash git push origin --delete feature/search ``` -The platform's branch automation, wired up by `git connect` in step 3, tears down the matching preview: services, databases, and buckets are removed. Teardown comes from the repository connection, not from the workflow, so it works even when no Actions run fires for the deletion. Your production and default branches are never touched by automated cleanup. - -## Forks and unconnected repositories - -GitHub does not mint OIDC tokens for workflow runs triggered from forks, and the credential exchange refuses repositories that aren't connected. In both cases the action skips instead of failing: the run stays green, prints a notice, and sets its `outcome` output to `skipped-no-credential`. Contributors can fork your repository without their pushes failing CI or reaching your workspace. - -## Troubleshooting - -- **The deploy step fails with `CLI.UNKNOWN_COMMAND`.** The action release predates the unified CLI: releases up to v1.5.0 invoke the `prisma composer` subcommands, which were removed in `prisma` `8.0.0-rc.8`. Use a release that invokes the top-level `deploy` command (see the action's [releases](https://github.com/prisma/cloud-deploy-action/releases)). -- **Commands fail with `PROJECT.SETUP_REQUIRED`.** The directory isn't linked, or you linked a parent directory. Re-run `project link` in the project root (step 2). -- **`git connect` fails with `CLI.INTERACTION_REQUIRED`.** The command can't complete non-interactively. Run it at a terminal, or connect through the [Console](https://pris.ly/pdp). -- **Runs are green but nothing deploys.** Check the run's log for `skipped-no-credential`: the repository isn't connected (step 3), or the run came from a fork. +The platform tears down the matching preview: its services, databases, and buckets are removed. This automation comes from the connection you set up in step 3, so it runs whether or not a workflow fires for the deletion. Automated cleanup skips your production and default branches. ## Next steps - [GitHub integration](/compute/github): what the repository connection is and does. - [Branching](/compute/branching): how preview branches relate to Git branches. -- [Deploying](/composer/deploying): stages, deploy state, and per-stage secrets, which all apply to CI deploys. -- [Environment variables](/compute/environment-variables): per-branch configuration for previews. +- [Deploying](/composer/deploying): stages, deploy state, and per-stage secrets, which apply to CI deploys too. diff --git a/apps/docs/content/docs/compute/github.mdx b/apps/docs/content/docs/compute/github.mdx index 952b0e32b1..a937bcd2eb 100644 --- a/apps/docs/content/docs/compute/github.mdx +++ b/apps/docs/content/docs/compute/github.mdx @@ -6,12 +6,12 @@ metaTitle: GitHub integration | Prisma Compute metaDescription: Connect a GitHub repository to Prisma Compute to enable OIDC-authenticated deploys from GitHub Actions and automatic preview teardown when branches are deleted. --- -Connecting a GitHub repository wires a project to your repo. The deploys themselves run in your own GitHub Actions, through [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action); what the connection contributes is everything around them: +Connecting a GitHub repository wires a project to your repo. Deploys run in your own GitHub Actions, through [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action); the connection provides two things around them: - **Credentials.** Workflow runs in the connected repository exchange their GitHub OIDC token for a short-lived Prisma workspace token, so the deploy workflow needs no secrets. - **Branch lifecycle.** Branch events keep the matching platform branches in sync, including tearing a preview down when its Git branch is deleted. -For the full setup, entry file to live preview, follow [Deploy on push](/compute/deploy-on-push). +For the full setup, from connection to a live preview per branch, follow [Deploy on push](/compute/deploy-on-push). ## How it works @@ -25,10 +25,7 @@ In beta, a project connects to one repository. ## Connect a repo -There are two ways in, and they don't set up the same things: - -- **Through the [Console](https://pris.ly/pdp)**: connecting a repository also opens a pull request that adds the deploy workflow, so the connection and the workflow arrive together. -- **From the CLI**: `git connect` sets up the connection only. You [add the workflow yourself](/compute/deploy-on-push#4-add-the-deploy-workflow). +You can connect through the [Console](https://pris.ly/pdp) or from the CLI. The Console also opens a pull request that adds the deploy workflow to the repository. The CLI sets up the connection only, and you [add the workflow yourself](/compute/deploy-on-push#4-add-the-deploy-workflow). From a linked project directory, connect your Git origin: @@ -42,7 +39,7 @@ To name the repository explicitly: npx prisma@latest git connect https://github.com/acme/shop ``` -If the GitHub App isn't installed yet, the CLI opens the browser to finish the install. The command is interactive: it waits for the install to complete, and `--no-interactive` fails with `CLI.INTERACTION_REQUIRED` rather than handing off an install URL. For headless setups, connect through the Console instead. +If the GitHub App isn't installed yet, the CLI opens the browser to finish the install. The command needs an interactive terminal: it waits for the install to complete, and `--no-interactive` fails with `CLI.INTERACTION_REQUIRED`. For headless setups, connect through the Console instead. Disconnect when you're done: @@ -56,12 +53,11 @@ Disconnecting stops the credential exchange and the branch automation. It doesn' Once a project is connected: -- **Actions runs can authenticate.** A workflow job with `id-token: write` gets a workspace token through the OIDC exchange, valid for 30 minutes and only issued for the connected repository. Unconnected repositories and forks are refused, which the deploy action treats as "skip, stay green". +- **Actions runs can authenticate.** A workflow job with `id-token: write` gets a workspace token through the OIDC exchange. The token is valid for 30 minutes and is only issued for the connected repository; unconnected repositories and forks are refused, and the deploy action then skips with a green run. - **Branch created** → creates the matching platform branch. -- **Branch deleted** → tears down the matching platform branch and everything on it, unless it's the production or default branch. Those are always left alone. -- **Push** → deployed by your repository's own workflow, not by the platform. Connecting doesn't build or deploy anything on its own: a connected repo with no deploy workflow deploys nothing. +- **Branch deleted** → tears down the matching platform branch and its resources. Your production and default branches are exempt from this cleanup. -Connecting doesn't create branches retroactively either. It aligns your default branch with the repo's default branch and wires up automation for future events. +Pushes are not handled by the platform. Your repository's own workflow deploys them, so a connected repo without a deploy workflow deploys nothing. Connecting also doesn't create branches retroactively: it aligns your default branch with the repo's default branch and wires up automation for future events. ## What's not in beta