Set up environments

Environments on Northflank allow you to automate your release process and preview changes in isolated environments.

By creating workflows, you can automate building and deploying your code, backing up databases, running migrations, and promoting deployments from development through to production. By creating preview blueprints, you can automatically provision complete environments when you push commits or open pull requests.

This guide will walk you through creating a build service, setting up preview environments for pull requests, and creating workflows to automate deployments across development stages.

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. Navigate to Environments in your project
2. Click Create 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. Navigate to Environments in your project
2. Click Add environment
3. Enter a name (e.g., development, staging, or production)
4. Click Create

The new environment appears as a column in the environments board view. You can create multiple environments to match your deployment stages.

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. In the environment column, click Workflow

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

3. 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

4. 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 have configured the workflow, you can manually test run it and Northflank will execute the workflow as you have specified it.

1. Click Run in the header
2. Add a release name (optional):
   • Click Add release name
   • Enter a descriptive name for this release
3. Add a release description (optional):
   • Click Add release description
   • Enter details about what this release includes
4. Click Create

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.