Configure a release flow

Release flows consist of workflows that contain nodes that perform specific actions, such as triggering a build, backing up a database, or promoting a deployment.

To configure a release flow you need a pipeline with the services, jobs, and addons you want to manage with it. You can create a release flow for each stage of your pipeline. You can only manage resources that exist in the same pipeline stage as the release flow.

You can create a workflow using the visual editor or with the code editor. If you are familiar with Northflank templates or using the API to manage your Northflank resources, you may want to edit and manage your release flows as code. You can also create a release flow using the visual editor, and then view, copy, and edit the generated release flow code.

The documentation for each node contains an example of the release flow code, however some of these do not contain the full specification as there may be many possible configurations and optional fields.

You can also see examples for a simple release flow that deploys builds to deployment services, and a more complex example that performs a database migration before promoting deployments to the current stage.

You can use the visual editor by selecting visual when adding or editing a release flow.

The visual editor consists of an overview of the release flow, which you can navigate by clicking and dragging to move, and zooming in and out. There are controls in the bottom-right corner of the screen to zoom and centre the view.

You can click and drag the available types of workflow and node from the right side of the visual editor, and place them where you would like in the release flow. Nodes and workflows can be dropped into other workflows.

Nodes can be moved by clicking and dragging them to a new position, and the order the nodes will run in will be automatically updated.

Nodes can be configured by clicking on them to bring up a menu, which will also show a delete button to remove the node. Nodes can also be deleted using your keyboard's backspace or delete keys.

Below is a list of node types you can use in a release flow. The kind column gives the reference to use the node if you are editing the release flow as code.

Some nodes have a wait for completion option. You can enable this so that the next steps in the workflow will only run when the node has finished and was successful. This can be useful for ensuring, for example, a job run has completed a database migration before promoting a deployment with related changes.

Workflow nodes specify whether the nodes contained within them are executed sequentially, or in parallel.

Workflow nodes can be nested. You can, for example, run two sequential workflows simultaneously within a parallel workflow. You can drag nodes and other workflows into and out of workflows. If you delete a workflow node that contains other nodes, the nested nodes will also be removed.

If a node within a workflow fails, the workflow will be marked as failed. If a workflow fails, subsequent steps will not run.

{
  "kind": "Workflow",
  "spec": {
      "type": "sequential | parallel",
      "steps": [...]
  }
}

This node deploys images from the preceding stage to the stage that the release flow is in.

To configure the node select the source service or job from the previous stage which contains the deployed image you want to promote, then select the target service or job to promote the image to. Arrows will appear in the pipeline to indicate which deployments will be promoted when a release flow is run.

When the release flow is run, the current image deployed on the source will be deployed on the target. The image can either be built on Northflank, or deployed from a container registry.

{
  "kind": "Release",
  "spec": {
    "type": "deployment",
    "origin": {
      "id": "source",
      "type": "service | job"
    },
    "target": {
      "id": "target",
      "type": "service | job"
    }
  }
}

This node triggers a new build in a service, or a job that uses a git repository as a source.

To configure a build node, select the service or job to initiate a build in, and choose the branch to build. You can select a specific commit to build, or leave the commit selection blank to build the latest commit to the branch.

You can enable wait for completion to ensure the build completes successfully before running subsequent nodes.

{
  "kind": "Build",
  "spec": {
    "id": "builder",
    "type": "service",
    "branch": "master"
  },
  "condition": "success"
}

This node deploys an image from a build service to a target deployment service or job.

To configure the node, select the build service you want to deploy from. Open the build menu to select a branch or pull request. From here you can select a specific commit to deploy, or choose to always deploy the latest build. You can filter results for branches, pull requests, or commits by typing in the dropdown.

Finally, select a job or service from the pipeline stage to deploy the built image to.

When you run the release flow you can optionally change the branch, pull request, or select a specific commit to deploy instead of the configured option.

{
  "kind": "Release",
  "spec": {
    "type": "build",
    "origin": {
      "id": "my-build-service",
      "branch": "main",
      "build": "latest"
    },
    "target": {
      "id": "target",
      "type": "service | job"
    }
  }
}

This node deploys an image from an external container registry to a target deployment service or job.

To configure the node, enter the URL of the image you want to deploy. Northflank will try to confirm the image is accessible at the given path. If the image is private, select or create the relevant registry credentials.

Finally, select a job or service from the pipeline stage to deploy the built image to.

When you run the release flow you can optionally change the image to deploy (and associated credentials) instead of the configured option.

{
  "kind": "Release",
  "spec": {
    "type": "registry",
      "origin": {
      "imagePath": "docker.io/library/nginx:latest"
    },
    "target": {
      "id": "target-job",
      "type": "job"
    }
  }
}

This node performs a backup of an addon that exists in the pipeline stage. Select the addon to back up and choose the type of backup, snapshot or dump.

You can enable wait for completion to ensure the backup completes successfully before running subsequent nodes.

{
  "kind": "AddonBackup",
    "spec": {
      "addonId": "my-database",
    "backupType": "snapshot | dump"
  },
  "condition": "success"
}

This node triggers a job run. Configure the node by selecting a job in the pipeline stage.

You can optionally override the existing job configuration by expanding settings: add environment variables, change the startup command, or run the job with more resources if required.

You can also enable wait for completion to ensure the job completes successfully before running subsequent nodes.

{
  "kind": "JobRun",
  "spec": {
    "jobId": "my-job",
    "deployment": {...}
  },
  "condition": "success"
}

This node performs an action such as running a command within a service or job, or restoring a database with a backup. Unlike other nodes, actions can be performed on resources in any of the pipeline stages.

To configure it, select the type of resource, then select the specific resource from the drop-down menu. Next, configure the specific action, for example selecting the backup to restore or the command to execute.

Execute a command in a service

{
  "kind": "Action",
  "spec": {
    "kind": "Service",
    "spec": {
      "type": "execute",
      "data": {
        "serviceId": "my-service",
        "command": "echo hello"
      }
    }
  }
}

Restore database with a backup

{
  "kind": "Action",
  "spec": {
    "kind": "AddonBackup",
    "spec": {
      "type": "restore",
      "data": {
        "addonId": "my-database",
        "backupId": "22-11-30-211324-backup"
      }
    }
  }
}

This node checks a condition has been met before running any subsequent nodes, for example whether a service or addon is running.

Services and addons from the previous pipeline stage can be checked, as well as in the same stage as the release flow.

{
  "kind": "Condition",
  "spec": {
    "kind": "Addon | Service",
    "spec": {
      "type": "running",
      "data": {
        "addonId | serviceId": "my-database | my-service"
      }
    }
  }
}

This is an example of a release flow that deploys the latest builds for the branches master and test-branch from a build service to two deployment services. This is executed in a parallel workflow, so both deployments roll out at the same time.

{
  "apiVersion": "v1",
  "spec": {
    "kind": "Workflow",
    "spec": {
      "type": "parallel",
      "steps": [
        {
          "kind": "Release",
          "spec": {
            "type": "build",
            "origin": {
              "id": "builder",
              "branch": "master",
              "build": "latest"
            },
            "target": {
              "id": "dep-1",
              "type": "service"
            }
          }
        },
        {
          "kind": "Release",
          "spec": {
            "type": "build",
            "origin": {
              "id": "my-application",
              "branch": "test-branch",
              "build": "latest"
            },
            "target": {
              "id": "dep-2",
              "type": "service"
            }
          }
        }
      ]
    }
  }
}

This is an example of a release flow that manages a database migration before promoting deployments. The workflow is executed in a sequential workflow, as nodes need to complete successfully before the next node is executed. The final promotion of two services should be done at the same time, so the promotion nodes are contained within a parallel workflow.

The individual steps are:

1. Run backup: backs up a database and waits for this to be completed successfully
2. Deploy build: deploys the latest built image from a build service to a job
3. Run job: runs the job and waits for it to complete successfully
4. In a parallel workflow: two promote deployment nodes: promote the current images from two services in the previous stage to deployments in the current stage

{
  "apiVersion": "v1",
  "spec": {
    "kind": "Workflow",
    "spec": {
      "type": "sequential",
      "steps": [
        {
          "kind": "AddonBackup",
          "spec": {
            "addonId": "mongo-prod",
            "backupType": "snapshot"
          },
          "condition": "success"
        },
        {
          "kind": "Release",
          "spec": {
            "type": "build",
            "origin": {
              "id": "my-application",
              "branch": "master",
              "build": "latest"
            },
            "target": {
              "id": "db-schema-migration",
              "type": "job"
            }
          }
        },
        {
          "kind": "JobRun",
          "spec": {
            "jobId": "db-schema-migration",
            "deployment": {
              "docker": {
                "configType": "default"
              }
            }
          },
          "condition": "success"
        },
        {
          "kind": "Workflow",
          "spec": {
            "type": "parallel",
            "steps": [
              {
                "kind": "Release",
                "spec": {
                  "type": "deployment",
                  "origin": {
                    "id": "dep-4",
                    "type": "service"
                  },
                  "target": {
                    "id": "dep-6",
                    "type": "service"
                  }
                }
              },
              {
                "kind": "Release",
                "spec": {
                  "type": "deployment",
                  "origin": {
                    "id": "dep-3",
                    "type": "service"
                  },
                  "target": {
                    "id": "dep-5",
                    "type": "service"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  }
}