# Configure workflows

Workflows on Northflank allow you to automate your release process for each environment, from development through to production.

You can create workflows to deploy and promote builds, back up databases, run migrations, and manage infrastructure. Workflows can be automatically run using Git or cron triggers, and work alongside CI/CD for individual services and jobs.

Each workflow is built in a visual editor by connecting nodes that perform specific actions. You can also edit workflows as JSON templates.

## Create a workflow

> [!note] 
> There are two ways to create a workflow. Click **(+ workflow)** in an environment column to create a workflow directly in that environment. Or click the **Create workflow** button to create an unassigned workflow, which you can then drag to the desired environment.

1. Navigate to **Environments** in your project

2. Click **(+ workflow)** in an environment column, or click **Create workflow** to create an unassigned workflow

3. Enter a name for the workflow

4. Click **Add trigger** (optional) to configure Git push, Git pull request, or cron schedule triggers

5. Click **Continue**

The visual editor opens with your workflow nodes.

![Creating a workflow in the Northflank application](https://assets.northflank.com/documentation/v1/application/getting-started/set-up-environments/create-workflow.png)

## Configure workflow nodes

Workflows are built from nodes connected together. Each node performs a specific action and executes in sequence based on connections.

1. Select a node to configure its settings

2. Enter the configuration details for that node type

3. Click **Save node**

4. On the node, click a connection point (e.g., **Deploy build**) to add the next node

5. Configure the new node and save it

6. Repeat to build your complete workflow

7. Click **Save workflow** when finished

![Configuring a workflow in the Northflank application](https://assets.northflank.com/documentation/v1/application/getting-started/set-up-environments/configure-workflow.png)

## Node types

See [template nodes](/v1/application/infrastructure-as-code/template-nodes) for detailed documentation on all available node types. Common workflow nodes include:

**Build nodes:** Start build, Build on trigger

**Deployment nodes:** Deploy build, Deploy service

**Action nodes:** Run job, Run backup, Import backup, Run action

**Control nodes:** Condition, Approval, Message

**Infrastructure nodes:** Create resource, OpenTofu

## Configure node settings

Each node type has specific settings. Click a node in the workflow editor to open its settings panel.

### Build nodes

**Service or repository**: The source to build from, either an existing build service or a repository directly

**Branch and commit**: Which branch or commit ref to build. Can use references like `${triggers.<name>.branch}` to build the branch that triggered the workflow

**Preview or override build configuration**: Expand to override build arguments and Docker configuration for this specific run

**Build rules**: Expand to configure commit message ignore flags, path rules and Build rule fall through handling.

**Reuse existing builds**: Whether to reuse an existing build if available

**Wait for completion**: Whether the workflow waits for the build to finish before proceeding to the next node

**Skip node execution**: Skip running this node

### Deployment nodes

**Target service or job**: The service or job to deploy to

**Wait for completion**: Whether the workflow waits for the deployment to finish before proceeding to the next node

**Skip node execution**: Skip running this node

**Timeout duration**: How long to wait before the deployment times out

### Action nodes

**Target resource**: The service, job, or addon to act on

**Action type**: The operation to perform (e.g. run job, run backup, import backup, restart service)

**Parameters**: Action-specific inputs, such as the job run arguments or backup source

**Retry settings**: Number of retries and delay between attempts if the action fails

### Condition nodes

**Condition expression**: A boolean expression that checks the state of other resources (e.g. addon or service readiness). The workflow waits until this condition evaluates to true before proceeding.

**Success and failure paths**: Connect different downstream nodes to each branch to define what happens in each case

### Approval nodes

**Approvers**: Team members who must approve before the workflow proceeds. Useful as a gate before deploying to production

**Timeout**: How long to wait for approval before the run fails

### Message nodes

Send a Slack, Discord, or webhook notification at a specific point in the workflow. Use message nodes to alert your team when a deployment to production is about to start or has completed, or once a preview environment has been provisioned.

## Use references in workflows

Workflows can reference values from triggers and other nodes. This makes workflows dynamic based on how they were triggered.

For detailed information on using references in your workflows, see [template nodes](https://northflank.com/docs/v1/application/infrastructure-as-code/template-nodes#environment-node) and [GitOps documentation](https://northflank.com/docs/v1/application/infrastructure-as-code/gitops-on-northflank).

### Git trigger references

If a workflow has a Git trigger, you can use these references:

`${triggers.<name>.branch}` - Branch name

`${triggers.<name>.sha}` - Commit SHA

`${triggers.<name>.pullRequestId}` - Pull request ID

`${triggers.<name>.repoUrl}` - Repository URL

### Node references

Reference outputs from other nodes:

`${refs.<node-ref>.nfObjectId}` - Access the ID of the service built by a build node

`${refs.<node-ref>.ports.0.dns}` - Access the generated URL of a deployment or combined service

Use these references in node settings to make workflows dynamic.

## Add triggers

Workflows can have multiple triggers to run automatically on different events.

### Git push trigger

1. Click the plus sign or **Add trigger**

2. Select **Git push** from the **Kind** dropdown

3. Configure:
  
  
  
  - **Repository**: Select your repository
  
  - **Branch rules**: Specify branches (e.g., `main`, `develop`, or `*` for all)
  
  - **Path rules** (optional): Only trigger on changes to specific files or directories
  
  - **Ignore rules** (optional): Skip runs for commits with specific message patterns

4. Click **Save**

The workflow runs automatically when commits are pushed to matching branches.

### Git pull request trigger

1. Click the plus sign or **Add trigger**

2. Select **Git pull request** from the **Kind** dropdown

3. Configure:
  
  
  
  - **Repository**: Select your repository
  
  - **Pull request rules**: Specify when to trigger

4. Click **Save**

The workflow runs when pull requests are opened or updated.

### Cron schedule trigger

1. Click the plus sign or **Add trigger**

2. Select **Cron schedule** from the **Kind** dropdown

3. Enter a cron expression in the **Schedule** field (times are UTC, minimum interval is 10 minutes)

4. Click **Save**

The workflow runs automatically on the configured schedule.

## Configure workflow settings

Click **Settings** in the workflow editor to configure workflow behavior:

### Basic information

**Template name**: Name of the workflow

**Description**: (Optional) Describe what this workflow does. Useful when you have multiple workflows in a project to distinguish their purpose.

### GitOps

Enable GitOps to sync workflow configuration with a Git repository. Changes to the workflow definition are committed to your repo, giving you version history, code review, and the ability to roll back to a previous state.

### Concurrency policy

Controls what happens when a new workflow run is triggered while a previous run is still in progress.

**Allow**: Multiple workflow runs can execute simultaneously without restriction. Suitable for workflows that act on independent resources and have no shared state, such as deploying to separate environments.

**Queue**: New runs wait for previous runs to complete before starting. Use this when runs must not overlap, for example a release workflow that runs database migrations before deploying, where two concurrent runs could apply migrations out of order.

**Cancel previous**: New runs cancel any in-progress runs and start immediately. Use this for workflows triggered by Git pushes where only the latest commit matters, such as building and deploying a staging environment on every push to `main`.

### Cross project access

Enable **Share workflow access to other projects** to allow other projects to trigger this workflow. This is useful for central workflows, for example a shared infrastructure provisioning workflow in a platform project that individual product projects can trigger as part of their own release process.

### Use branch contents

Enable **Enable using branch contents** to provision the preview environment according to the GitOps file in the repository branch. This means if a PR modifies the preview blueprint definition, the preview will be provisioned according to the updated definition from that branch.

### Argument overrides

Define default values that can be overridden when running the workflow manually. Arguments can be referenced in nodes using `${args.<name>}`.

For example, you could define `target_env` with a default of `staging`, then reference `${args.target_env}` in deployment nodes. When triggering manually, you can override this to deploy to a different environment without changing the workflow definition.

### Teardown

Add a teardown specification to define cleanup actions when the workflow is deleted. For example, you can use teardown to delete OpenTofu resources on external providers. Note that Northflank resources provisioned as part of a preview will already be auto-deleted, and in most cases workflows won't create resources.

## Save workflow

Click **Save workflow** to save your changes. The workflow is ready to run.

## Next steps

- [Run and manage workflows: Run and manage workflows for different environments.](/v1/application/release/run-and-manage-workflows)
- [Set up preview blueprints: Create preview blueprints to automatically create preview environments for your branches and pull requests.](/v1/application/release/set-up-preview-blueprints)
- [Manage preview blueprints: Manage active previews, manually create test environments, and configure automatic cleanup.](/v1/application/release/manage-preview-blueprints)
- [Run migrations: Run database migrations and update your deployments simultaneously when you update your schema.](/v1/application/release/run-migrations)