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. If a workflow takes up the entire view of your editor, you can hold the spacebar while clicking and dragging to continue to navigate.

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": [...]
  }
}

Arguments

You can include arguments in your release flow, referenced in the format ${args.argumentName}.

Arguments can be passed to the release flow using a webhook trigger's URL query parameters, for example:

https://api-internal.northflank.com/webhooks/release-flows/<TOKEN>?name=example-run&description=Example%20description&ARG_1=value

References

You can add a reference (ref) property to nodes to refer to the output of a node. Add your ref as a string and it will return a promise, which resolves to the relevant response. References are accessed in the release flow using the refs object, in the format ${refs.<reference-name>.<property>}.

Check the response schemas in the API documentation.

This can be useful if you need to access details from resources created earlier, such as the status or commit SHA of a build.

Trigger references

You can refer to Git and webhook triggers in your release flow template.

Git trigger references take the format ${refs.<git-trigger-name>.<key>} and can return the following values:

Webhook trigger query parameters are passed directly to your template as arguments.

For example, triggering a webhook endpoint with the query parameters branch and sha

https://api-internal.northflank.com/webhooks/release-flows/<TOKEN>?branch=<BRANCH>&sha=<SHA>

will make the values accessible in your template as ${args.branch} and ${args.sha}.

The arguments name and description modify the run's name or description, rather than being passed as arguments into the template.

You can include template functions in your release flow, which will be evaluated when the release flow is run.

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": "sh -c \"echo ${MESSAGE}\""
      }
    }
  }
}

Commands in action nodes do not invoke a shell by default. Learn more about executing commands in action nodes.

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": "build",
              "branch": "master",
              "build": "latest"
            },
            "target": {
              "id": "deployment",
              "type": "service"
            }
          }
        },
        {
          "kind": "Release",
          "spec": {
            "type": "build",
            "origin": {
              "id": "build",
              "branch": "master",
              "build": "latest"
            },
            "target": {
              "id": "worker",
              "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": "staging-database",
            "backupType": "snapshot"
          },
          "condition": "success"
        },
        {
          "kind": "Release",
          "spec": {
            "type": "build",
            "origin": {
              "id": "build",
              "branch": "master",
              "build": "latest"
            },
            "target": {
              "id": "staging-migration",
              "type": "job"
            }
          },
          "condition": "running"
        },
        {
          "kind": "JobRun",
          "spec": {
            "jobId": "staging-migration"
          },
          "condition": "success"
        },
        {
          "kind": "Workflow",
          "spec": {
            "type": "parallel",
            "steps": [
              {
                "kind": "Release",
                "spec": {
                  "type": "deployment",
                  "origin": {
                    "id": "deployment",
                    "type": "service"
                  },
                  "target": {
                    "id": "staging",
                    "type": "service"
                  }
                }
              },
              {
                "kind": "Release",
                "spec": {
                  "type": "deployment",
                  "origin": {
                    "id": "worker",
                    "type": "service"
                  },
                  "target": {
                    "id": "staging-worker",
                    "type": "service"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  }
}