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.<argument-name>}, replacing <argument-name> with your key. Arguments are stored in the argument object at the top-level of the template as key-value pairs.

You can set argument values on the settings page of a release flow.

Templates automatically receive the branch, sha, and repoUrl arguments from a Git trigger. You can also pass arguments to a release flow using a webhook trigger's URL query parameters, for example:

https://webhooks.northflank.com/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, sha, and foo: https://webhooks.northflank.com/previews/<TOKEN>?branch=<BRANCH>&sha=<SHA>&foo=<FOO> will make the values accessible in your template as ${args.branch}, ${args.sha}, ${args.foo}.

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

You can add your own components to the release flow run UI to select specific branches, commits, or builds for all relevant template nodes when you run a release. This makes it possible to select a specific commit or build to deploy to multiple resources at once, instead of overriding each node individually.

Rich input components can be used to populate the values of argument overrides, and you can use these arguments to start and deploy builds. You can add these components to your release flow template, as an array of objects at the top level of the template object.

You can give each component a title and a description, which will be displayed when you run the release flow via the Northflank application.

Each component requires a source in the inputs object, which is the ID of the build service you want to select a commit or build from.

The outputs object maps your selection in the run modal to argument overrides. You can use these argument overrides in start build and/or deploy build nodes.

There are two available rich input components: BranchCommitSelector and BuildSelector.

Branch commit selector

The branch commit selector rich input allows you to select a branch or a specific commit to build and deploy. You can map the branch and buildSha outputs to arguments to start builds, and then deploy the resulting build to a deployment service or job.

{
  "apiVersion": "v1.2",
  "richInputs": [
    {
      "kind": "BranchCommitSelector",
      "spec": {
        "inputs": {
          "source": "build-service"
        },
        "outputs": {
          "branch": "RELEASE_BRANCH",
          "buildSha": "RELEASE_SHA"
        },
        "title": "Select branch & commit",
        "description": "Use this to set the branch and commit for all deployment and job nodes."
      }
    }
  ],
  "spec": {
    "kind": "Workflow",
    "spec": {
      "type": "sequential",
      "steps": [
        {
          "kind": "Build",
          "ref": "start-build",
          "spec": {
            "reuseExistingBuilds": true,
            "buildRuleFallThroughHandling": "fail",
            "buildOverrides": {
              "buildArguments": {}
            },
            "id": "build-service",
            "type": "service",
            "branch": "${args.RELEASE_BRANCH}",
            "sha": "${args.RELEASE_SHA}"
          },
          "condition": "success"
        },
        {
          "kind": "Release",
          "spec": {
            "type": "build",
            "origin": {
              "branch": "${refs.start-build.branch}",
              "build": "${refs.start-build.id}"
            },
            "target": {
              "id": "deployment-service",
              "type": "service"
            }
          }
        }
      ]
    }
  }
}

Build selector

The build selector rich input allows you to select a specific build from a build service to deploy in your release flow. You can map the branch and buildId outputs to arguments to deploy builds to deployment services and jobs.

{
  "apiVersion": "v1.2",
  "richInputs": [
    {
      "kind": "BuildSelector",
      "spec": {
        "inputs": {
          "source": "build-service"
        },
        "outputs": {
          "branch": "DEPLOY_BRANCH",
          "buildSha": "DEPLOY_SHA",
          "buildId": "DEPLOY_BUILD_ID"
        },
        "title": "Select build",
        "description": "Use this to select a build for all deployment and job nodes."
      }
    }
  ],
  "spec": {
    "kind": "Workflow",
    "spec": {
      "type": "sequential",
      "steps": [
        {
          "kind": "Release",
          "spec": {
            "type": "build",
            "origin": {
              "id": "build-service",
              "branch": "${args.DEPLOY_SHA}",
              "build": "${args.DEPLOY_BUILD_ID}"
            },
            "target": {
              "id": "deployment-service",
              "type": "service"
            }
          }
        }
      ]
    }
  }
}

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 build of the branch main from a build service to a deployment service and a job. This is executed in a parallel workflow, so both deployments roll out at the same time.

{
  "apiVersion": "v1.2",
  "spec": {
    "kind": "Workflow",
    "spec": {
      "type": "parallel",
      "steps": [
        {
          "kind": "Release",
          "spec": {
            "type": "build",
            "origin": {
              "id": "builder",
              "branch": "main",
              "build": "latest"
            },
            "target": {
              "id": "job-prod",
              "type": "job"
            }
          }
        },
        {
          "kind": "Release",
          "spec": {
            "type": "build",
            "origin": {
              "id": "builder",
              "branch": "main",
              "build": "latest"
            },
            "target": {
              "id": "deployment-prod",
              "type": "service"
            }
          }
        }
      ]
    }
  },
  "triggers": []
}

This is an example of a release flow that runs a database migration before promoting a deployment. The workflow is executed sequentially, as each node needs to complete successfully before the next node is executed.

The individual steps are:

1. Run backup: backs up a database and waits for this to be completed successfully
2. Promote deployment: promotes the image from the staging job to the production job
3. Run job: runs the production job and waits for it to complete successfully
4. Promote deployment: promotes the image from the staging deployment to the production deployment

{
  "apiVersion": "v1.2",
  "spec": {
    "kind": "Workflow",
    "spec": {
      "type": "sequential",
      "steps": [
        {
          "kind": "AddonBackup",
          "spec": {
            "addonId": "postgres-prod",
            "backupType": "snapshot"
          },
          "condition": "success"
        },
        {
          "kind": "Release",
          "spec": {
            "type": "deployment",
            "origin": {
              "id": "job-staging",
              "type": "job"
            },
            "target": {
              "id": "job-prod",
              "type": "job"
            }
          },
          "condition": "running"
        },
        {
          "kind": "JobRun",
          "spec": {
            "jobId": "job-prod"
          },
          "condition": "success"
        },
        {
          "kind": "Release",
          "spec": {
            "type": "deployment",
            "origin": {
              "id": "deployment-staging",
              "type": "service"
            },
            "target": {
              "id": "deployment-prod",
              "type": "service"
            }
          }
        }
      ]
    }
  },
  "triggers": []
}