Docs menu

Deployments

A deployment builds one commit of your app and releases it to an environment with no dropped requests. Every deploy can be canceled while it runs and rolled back after it succeeds.

On this page

A deployment takes one commit from your repo, builds it, and releases it to an environment. You can cancel a deployment while it runs and roll back to it after it succeeds. This page covers what happens between a push and your new code going live.

Build#

Primcloud detects your app's language from the files in your repo: package.json for Node.js, composer.json for PHP, Gemfile for Ruby, requirements.txt, Pipfile, or pyproject.toml for Python, and so on. The build then installs your dependencies, compiles your assets, and packages the app. Language Support covers what each language's build does.

The Build section of the deployment page shows the language it detected. An app built with more than one language, like a PHP app whose assets build with Bun, shows the app's own language. An environment's overview shows the language of its latest successful deployment, and your apps list shows its icon.

While a build runs, the Build section shows the step it's on, and the build log streams live. A failed build shows the step it failed in.

Builds reuse dependency downloads and compiled assets from earlier builds when nothing that affects them has changed, so most builds after the first are faster.

If any step fails (a dependency that won't resolve, a compile error, a broken Procfile), the deployment is marked Build Failed and your running app is untouched. Read the build log, fix the problem, and push a new commit or redeploy.

Release#

If your Procfile declares a release process, Primcloud runs it once against the new build before any traffic moves. Use it for database migrations or other work that has to happen once per deploy. If it exits non-zero, or is still running after your plan's time limit (20 minutes on Standard, 45 on Pro, 60 on Team), the deployment fails and the previous release keeps running.

Rollout#

Your process types then move to the new version, web first. New copies of web get traffic once they accept connections on the port in $PORT, and no old copy stops until a new one is ready to replace it, so no requests are dropped. There's nothing to configure. If the new copies still aren't accepting connections after 5 minutes, the deployment fails and the old ones keep serving. Other process types take no traffic, so they count as ready once they're running.

Old copies of web stop receiving new requests first, then get SIGTERM and have 30 seconds to finish what they're serving before they're stopped. Other process types get SIGTERM right away and have the same 30 seconds.

While the rollout runs, the Rollout section of the deployment page shows the step it's on, and a failed rollout shows the step it failed in.

If any process type fails to come up (a crash, a missing environment variable), the deployment fails and every process type goes back to the last Rollout Succeeded deployment: process types the failed deploy added are removed, ones it dropped come back, and copies that were still serving keep running. If the environment has never had a successful deployment, nothing is left running and your next deploy starts it fresh.

When every process type is on the new version, the deployment is marked Rollout Succeeded and it's live.

What triggers a deployment#

  • A push to the tracked branch. Primcloud deploys the pushed commit to the environment tracking that branch.
  • A manual deploy. Rebuilds and releases the live commit from the dashboard, without waiting for a push.
  • Saving secrets. Releases the live build again with the new values, without rebuilding. See Secrets.
  • Changing a formation's compute size. Releases the live build again at the new size, without rebuilding. See Compute.
  • A rollback or redeploy.

Status on GitHub#

Every deployment reports to its commit on GitHub as a check, so the commit, and any pull request whose latest commit it is, shows whether it deployed. The check is named <application> (<environment>) and links to the deployment in Primcloud. It shows:

  • Queued while the deployment waits for another build to finish.
  • In progress until the rollout ends.
  • Successful once the deployment reaches Rollout Succeeded.
  • Failed if the deployment fails, with the reason shown on the deployment page.
  • Canceled if you cancel it, or a newer deploy replaces it while it's queued.

Rollbacks, redeploys, manual deploys, and deploys from a secret or compute change each report on the commit they release.

A push your account can't deploy, for example because it has no payment method on file, creates no deployment. Its commit gets a failed check saying the account can't deploy right now. The check doesn't give the reason, since anyone who can see the repo can see its checks; open Primcloud to see it.

The check keeps its name as long as the application and environment keep theirs. When an environment tracks a pull request's branch, you can require its check in a branch protection rule, so the pull request can't merge until that environment has deployed its latest commit.

Every deployment also appears among the repo's deployments on GitHub, under an environment named like the check, so a pull request shows when its commits were deployed. The GitHub deployment shows:

  • Queued until its build starts.
  • In progress until its rollout ends.
  • Successful once the deployment reaches Rollout Succeeded, linking to the environment's live URL (its primary custom domain, if it has one) and to the deployment in Primcloud.
  • Failed if the deployment fails, with the reason shown on the deployment page.
  • Inactive if you cancel it, a newer deploy replaces it while it's queued, or a newer deployment of the environment succeeds after it.

A rollback shows as a new GitHub deployment of the commit it returns to.

Pull requests#

When a deploy ships a merged pull request, the pull request's number and title appear beside the commit in your deployment history and on the deployment page, linking to the pull request on GitHub. Rollbacks and redeploys show the pull request of the commit they bring back.

A deployment's header with its commit, author, the pull request it shipped, and branch

Deployment statuses#

  • Queued / Build Starting / Build Started: the build is waiting or running.
  • Build Succeeded: the build is done and the release is about to begin.
  • Build Failed: the build didn't complete. Your running app is unchanged.
  • Release Starting / Release Succeeded: the release process is running or has finished.
  • Release Failed: the release process exited non-zero, ran past its time limit, or couldn't start. Your running app is unchanged.
  • Rollout Started: your process types are moving to the new version.
  • Rollout Succeeded: everything runs the new version. This is the live release.
  • Rollout Failed: the rollout failed and your process types went back to the last live release.
  • Canceled: you canceled the deployment before it finished.

Canceling a deployment#

Cancel a deployment from its page any time before it finishes, including during the rollout.

A deployment's detail page with its Build and Rollout phases, the Build phase expanded to its streaming log

Canceling during the build or the release process leaves your running app untouched. Canceling during the rollout returns every process type to the last Rollout Succeeded deployment. If the environment has never had one, its process types are removed and your next deploy starts them fresh.

Canceling doesn't undo a secret change. If the canceled deploy carried one, your app returns to the previous release with the values you saved. To undo a secret change, edit it again.

Rollback#

A rollback returns your environment to an earlier Rollout Succeeded deployment inside your plan's rollback history. Hit Roll back on it in the deployment history.

The deployment history list, each entry showing its commit message, status dot, build duration, SHA, author, and branch

A rollback creates a new deployment, skips the build, and runs the release and rollout again, including your release process if your Procfile declares one. If that process fails against the older code (a database already migrated forward, for example), the rollback fails and the current release stays live.

Redeploy#

Redeploy builds the same commit again from scratch. Use it when a build failed for a reason outside your code, like a package registry timing out or a secret you've since added. It's available on Build Failed, Release Failed, Rollout Failed, and Canceled deployments inside your plan's rollback history.

Deploy logs#

Each deployment's build and release logs stream live on its page and stay there afterward. See Logs.