|
| 1 | +--- |
| 2 | +title: Deploy on push |
| 3 | +description: Graduate a Composer app from manual deploys to a Git workflow, with production deploys on push and an isolated preview environment per branch. |
| 4 | +url: /compute/deploy-on-push |
| 5 | +metaTitle: Deploy on push | Prisma Compute |
| 6 | +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. |
| 7 | +--- |
| 8 | + |
| 9 | +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: |
| 10 | + |
| 11 | +- A push to your default branch deploys **production**. |
| 12 | +- A push to any other branch deploys an isolated **preview stage**: its own services, its own databases, its own buckets, its own URL. |
| 13 | +- Deleting the branch tears the preview down. |
| 14 | +- No secrets land in the repository: workflow runs authenticate through GitHub's OIDC tokens. |
| 15 | + |
| 16 | +## How the pieces fit |
| 17 | + |
| 18 | +Push-to-deploy is two complementary halves, and you set up both: |
| 19 | + |
| 20 | +1. **The repository connection** ([`git connect`](/cli/v8/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. |
| 21 | +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/v8/deploy), targeting production or a stage named after the branch. |
| 22 | + |
| 23 | +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. |
| 24 | + |
| 25 | +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. |
| 26 | + |
| 27 | +## Prerequisites |
| 28 | + |
| 29 | +- 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. |
| 30 | +- Admin access to the GitHub repository, so you can install the Prisma GitHub App. |
| 31 | + |
| 32 | +## 1. Push the project to GitHub |
| 33 | + |
| 34 | +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/): |
| 35 | + |
| 36 | +```bash |
| 37 | +gh repo create my-app --private --source . --push |
| 38 | +``` |
| 39 | + |
| 40 | +## 2. Link the directory to the project |
| 41 | + |
| 42 | +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: |
| 43 | + |
| 44 | +```npm |
| 45 | +npx prisma@next project link my-app |
| 46 | +``` |
| 47 | + |
| 48 | +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/v8/project) for how the link is resolved. |
| 49 | + |
| 50 | +## 3. Connect the repository |
| 51 | + |
| 52 | +```npm |
| 53 | +npx prisma@next git connect https://github.com/you/my-app |
| 54 | +``` |
| 55 | + |
| 56 | +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. |
| 57 | + |
| 58 | +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. |
| 59 | + |
| 60 | +## 4. Add the deploy workflow |
| 61 | + |
| 62 | +Commit a workflow that runs [prisma/cloud-deploy-action](https://github.com/prisma/cloud-deploy-action) on every push: |
| 63 | + |
| 64 | +```yaml title=".github/workflows/prisma-deploy.yml" |
| 65 | +name: prisma-deploy |
| 66 | + |
| 67 | +on: |
| 68 | + push: |
| 69 | + |
| 70 | +concurrency: |
| 71 | + group: prisma-deploy-${{ github.ref }} |
| 72 | + cancel-in-progress: false |
| 73 | + |
| 74 | +permissions: |
| 75 | + contents: read |
| 76 | + id-token: write |
| 77 | + |
| 78 | +jobs: |
| 79 | + deploy: |
| 80 | + if: github.ref_type == 'branch' |
| 81 | + runs-on: ubuntu-latest |
| 82 | + steps: |
| 83 | + - uses: actions/checkout@v4 |
| 84 | + - uses: actions/setup-node@v4 |
| 85 | + with: |
| 86 | + node-version: 22 |
| 87 | + - uses: oven-sh/setup-bun@v2 |
| 88 | + - uses: prisma/cloud-deploy-action@v1 |
| 89 | + with: |
| 90 | + build-command: npm run build |
| 91 | +``` |
| 92 | +
|
| 93 | +Three lines carry the weight: |
| 94 | +
|
| 95 | +- **`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. |
| 96 | +- **`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`. |
| 97 | +- **`oven-sh/setup-bun@v2`** puts Bun on the runner PATH, which the action requires. |
| 98 | + |
| 99 | +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. |
| 100 | + |
| 101 | +## 5. Push to deploy production |
| 102 | + |
| 103 | +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: |
| 104 | + |
| 105 | +```text no-copy |
| 106 | +my-app |
| 107 | +├─ db postgres-database db_def456 |
| 108 | +└─ api compute-service cps_abc123 |
| 109 | + https://xyz.ewr.prisma.build |
| 110 | +``` |
| 111 | + |
| 112 | +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. |
| 113 | + |
| 114 | +## 6. Preview a branch |
| 115 | + |
| 116 | +Push any other branch: |
| 117 | + |
| 118 | +```bash |
| 119 | +git switch -c feature/search |
| 120 | +git push -u origin feature/search |
| 121 | +``` |
| 122 | + |
| 123 | +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: |
| 124 | + |
| 125 | +```npm |
| 126 | +npx prisma@next service list --branch feature/search |
| 127 | +``` |
| 128 | + |
| 129 | +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. |
| 130 | + |
| 131 | +## 7. Delete the branch to clean up |
| 132 | + |
| 133 | +```bash |
| 134 | +git push origin --delete feature/search |
| 135 | +``` |
| 136 | + |
| 137 | +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. |
| 138 | + |
| 139 | +## Forks and unconnected repositories |
| 140 | + |
| 141 | +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. |
| 142 | + |
| 143 | +## Troubleshooting |
| 144 | + |
| 145 | +- **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)). |
| 146 | +- **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). |
| 147 | +- **`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). |
| 148 | +- **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. |
| 149 | + |
| 150 | +## Next steps |
| 151 | + |
| 152 | +- [GitHub integration](/compute/github): what the repository connection is and does. |
| 153 | +- [Branching](/compute/branching): how preview branches relate to Git branches. |
| 154 | +- [Deploying](/composer/deploying): stages, deploy state, and per-stage secrets, which all apply to CI deploys. |
| 155 | +- [Environment variables](/compute/environment-variables): per-branch configuration for previews. |
0 commit comments