Set up environments

Before you can deploy code, you need a build service to compile your source code into images. This build service will be shared across your workflows and preview environments, ensuring consistent builds across all deployment stages.

1. Navigate to Services in your project

2. Click Create service → Build

3. Under Basic information enter a service name

4. Under Repository select your repository from the dropdown

   • Trigger mode: Select Build rules
   • Pull request build rules: Leave empty (configured later in preview blueprint)
   • Branch build rules: Leave empty (configured later in preview blueprint)

5. Under Build options select Dockerfile if you have a custom Dockerfile or Buildpack

   • If your Dockerfile is not in the root directory, specify the relative paths

6. Under Resources choose a compute plan appropriate for your build workload

7. Under Environment variables add build arguments or runtime variables if required

8. Click Create service

Preview blueprints automatically create isolated test environments when you open pull requests. Each preview environment gets its own services, databases, and unique URLs, allowing you to test changes before merging to your main branch.

1. Open Previews in your project sidebar.
2. Click New preview blueprint
3. Configure the blueprint:
   • Name: e.g. pr-previews
   • Naming convention: Select Pull request ID
   • Enable Suffix to append the pull request number to resource names
4. Click Add trigger
   • Kind: Select Git pull request or any option of your choice
   • Repository: Select the same repository used for the build service
5. Click Continue to open the visual editor

The visual editor lets you build the workflow that creates your preview environment. You'll connect nodes together to define what gets deployed: starting with building your code, then deploying it to services, and optionally adding databases or other resources.

1. On the Build on trigger node, click Deploy to service to create a Deployment service node
2. Select the Deployment service node and configure:
   • Basic information: Enter a service name
   • Environment variables: Add runtime variables if required
   • Networking: Expose public or private ports
   • Resources: Select a compute plan
3. Click Save preview blueprint

Additional nodes can be added to the workflow, including databases, jobs, and volumes.

Test your preview blueprint by running it manually before relying on automatic Git triggers. This lets you verify the workflow creates preview environments correctly.

1. Click Run in the header
2. Under Git trigger, select a commit
3. Click Create

After the workflow completes:

• On the Deployment service click View resource to access the deployed instance

Environments organize your workflows by deployment stage. Each environment represents a stage in your release process, such as development, staging, or production, and contains the workflows that deploy to that stage.

1. Open your project's Dashboard
2. Select Environment beside the plus icon
3. Enter an Environment name (e.g., development, staging, or production)
4. Click Create environment

The dashboard opens the new environment. You can create multiple environments to match your deployment stages.

Use the project environment selector to switch views. See All and Default views.

Workflows are automated release processes that execute when triggered manually or by Git events. Each workflow contains a series of steps (nodes) that build your code, deploy it to services, run database migrations, and perform other release tasks.

Create a workflow in an environment to automate deployments to that stage. For example, a production workflow might build from your main branch and deploy to production services, while a development workflow deploys feature branches to development services.

1. Open your project's Dashboard. Select an environment at the top of the dashboard.

2. Select Create... → Workflow

3. Enter a name (e.g., Deploy to prod)

4. Click Add trigger (optional):

   • Kind: Select Git push
   • Repository: Select your repository
   • Branch rules: Enter the branch name (e.g., main or develop) or * to trigger on every push to a branch

5. Click Continue to open the visual editor

Build your deployment workflow by connecting nodes together. Each node performs a specific action: building code, deploying to services, backing up databases, or running migrations. Connect them in sequence to create your complete release process.

1. Select the Start build node and configure:
   • Service / job: Select your build service
   • Branch: Enter the branch name (e.g., main)
   • Commit: Leave blank to build the latest commit
2. Click Save node
3. On the Start build node, click Deploy build
4. Select the Deploy build node and configure:
   • Target service/job: Select or create a deployment service
5. Click Save node
6. Click Save workflow

Additional nodes can be added to the workflow, including databases, jobs, and volumes.

After you configure the workflow, you can run it manually.

1. Click Run in the header.
2. To name the run, click Add run name. Enter a descriptive name.
3. To describe the run, click Add run description. Enter a description.
4. Click Run.

The workflow will execute and you can monitor its progress. If you configured Git triggers, the workflow will also run automatically when commits are pushed to the configured branch.

Workflows and preview blueprints can run automatically on a repeating schedule. This is useful for regular deployments (nightly builds), periodic maintenance tasks (database backups, cache warming), or refreshing test environments on a schedule.

To add a cron trigger:

1. Open your workflow or preview blueprint
2. Click the plus sign
3. Select Cron schedule from the Kind dropdown
4. Enter a cron expression in the Schedule field (times are UTC, minimum interval is 10 minutes)

Each workflow or preview blueprint can have one cron trigger.