Configure workflows

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 to configure an optional automatic trigger

5. Click Continue

The visual editor opens with your 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

Workflows support a subset of template nodes. The editor shows nodes available to your account.

Run a template

Use Run template to start an existing template or workflow. In the node form, select Template type. Select the target template or workflow. Expand Arguments to supply values for the child run.

In JSON, set spec.templateType to template or workflow. Set the target identifier in spec.templateId.

For a workflow in another project, use project-id/workflow-id as its identifier. The target workflow must allow access from the calling project.

Enable Wait for completion to wait for the child run. In JSON, set condition: "success" beside the node's kind and spec. Without this condition, the node continues after starting the child run.

For example, this node starts example-workflow in the current project and waits for it to succeed:

{
  "kind": "RunTemplate",
  "condition": "success",
  "spec": {
    "templateType": "workflow",
    "templateId": "example-workflow"
  }
}

Open a node in the workflow editor to configure it. The available controls depend on the node type.

Build nodes

Select the source service or job and the branch or commit to build. You can use references such as ${triggers.<name>.branch} for a branch supplied by a trigger.

Use the build controls to override build arguments or Docker configuration for this run.

The fall-through choices are Fail, Skip the build node, and Use last build. The last choice selects the latest running or successful build for the branch or pull request. The node fails if no matching build exists.

See build nodes for supported sources.

Deployment nodes

Select the image source and target service or job. For a service target, enable Wait for completion to wait until the service runs. Set the timeout to limit that wait.

Deploying an image to a job does not wait for a job run. To run the job, add a Run job node. Enable Wait for completion on that node before later steps depend on its result.

Action nodes

Select the operation and its target resource. Supply the fields required for that operation, such as job arguments or an addon import URL. See action nodes for supported operations and completion controls.

Condition nodes

Select a resource and the condition to wait for. Later nodes in a sequential workflow wait until the condition succeeds. A failed condition or timeout fails the node. See condition nodes for supported conditions.

Approval nodes

Set Number of approvals required to a positive integer. Approve the node from the run page to continue. See approval nodes for the JSON field.

Message nodes

Choose Slack, a webhook, or a comment on a pull request in a linked repository. The message can include template arguments, functions, and references. See message nodes for supported destinations.

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 and GitOps documentation.

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.

Workflows can run automatically from Git events, webhook requests, or a schedule. Preview blueprints support the same trigger types. The form offers the providers and controls available to your account.

To add a trigger:

1. Open the editor.
2. Click Add trigger.
3. Select a Kind.
4. Configure the trigger with the fields below.
5. Save the trigger.
6. Save the workflow or preview blueprint.

Git push trigger

Select Git push and a repository. Add at least one Branch trigger rules pattern, such as main or *. Matching pushes start a run.

Use Path rules to filter changes by file or directory. Use Commit message ignore flags to skip commits with matching text. See Git build rules for pattern examples.

Git pull request trigger

Select Git pull request and a repository. Configure Branch trigger rules for the pull request's source branch. Matching pull requests start runs when opened or updated. Path rules and commit message ignore flags can further restrict runs.

Tagged release trigger

Select Tagged release and a GitHub or GitLab repository. This trigger responds to release events from the provider. On GitHub, it runs when Northflank receives a release-created event. Pushing a Git tag alone does not start this trigger.

Git check suite trigger

Select Git check suite and a supported repository. Configure Branch trigger rules for the pull request's source branch. Path rules and commit message ignore flags also apply.

On GitHub, a completed, successful check suite associated with a pull request starts a run. A check suite groups checks from one GitHub app. This trigger does not wait for every other check suite on the commit. GitHub pull requests from forks do not start this trigger.

GitHub PR label trigger

Select GitHub PR label and a GitHub repository. Add the labels to match under Label trigger rules. Matching labels can start a run when applied and on later pull request updates.

To restrict source branches, expand Branch rules. Enable Enable branch trigger rules. Add the branch patterns to match. Path rules and commit message ignore flags can further restrict runs.

Adding another matching label does not start another run if the pull request already matched the label rules.

Cron schedule trigger

Select Cron schedule and enter a cron expression. Schedules use UTC and must run no more frequently than every 10 minutes. Each workflow or preview blueprint accepts one cron trigger.

See run workflows on a schedule for an example.

Webhook trigger

Select Webhook. Copy the Webhook URL. Save the trigger and its workflow or preview blueprint before using the URL.

The URL accepts GET or POST requests. Pass arguments as URL query parameters. See workflow webhook requests for supported parameters.

Enable or pause triggers

To pause one trigger, open its form. Turn off Enable trigger. Save the trigger and its workflow or preview blueprint. Turn the control on again to resume it.

Pausing triggers does not cancel runs or delete preview environments. Manual runs remain available. Skipped trigger events are not replayed when you resume.

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.

For preview blueprints, you can use the GitOps file from the preview branch.

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.

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, such as running a cleanup job or removing external infrastructure. Run the teardown explicitly before deleting the workflow. Deleting a workflow does not run its teardown automatically. See run teardown workflows.

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