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..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. 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. 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 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 | 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..67a76be854 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, 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: ```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..6c95888fad --- /dev/null +++ b/apps/docs/content/docs/compute/deploy-on-push.mdx @@ -0,0 +1,142 @@ +--- +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 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. + +## How it works + +Push-to-deploy has two parts, 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. + +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. + +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. 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 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 +``` + +## 2. Link the directory to the project + +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 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 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 the 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 +``` + +A few settings to be aware of: + +- `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. + +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 with the same deploy report you know from your terminal: + +```text no-copy +my-app +├─ db postgres-database db_def456 +└─ api compute-service cps_abc123 + https://xyz.ewr.prisma.build +``` + +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 a branch to try the preview flow: + +```bash +git switch -c feature/search +git push -u origin feature/search +``` + +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 +``` + +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 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 apply to CI deploys too. 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..a937bcd2eb 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. 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, from connection to a live preview per branch, follow [Deploy on push](/compute/deploy-on-push). ## How it works @@ -14,12 +19,14 @@ 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 +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: ```npm @@ -32,11 +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 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 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: @@ -44,37 +47,24 @@ 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. 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. -- **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 its resources. Your production and default branches are exempt from this cleanup. -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. +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 -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---",