GitOps on Northflank

GitOps on Northflank allows you to manage infrastructure, run releases, update deployments, and automate complex tasks using JSON files in a Git repository.

You can store templates and release flows in JSON files in the same repository as your code, or in separate repositories.

If run automatically when updated is also enabled you can run releases, scale up deployments, run backups, and manage almost anything else on Northflank simply by pushing a commit to a Git repository.

You can use GitOps with Northflank templates, release flows, and preview environments. Enable GitOps from the settings page to begin syncing your release flow or template with a Git repository.

Release flow and template files can be stored in the same directory as your codebase, or you can store them in separate infrastructure repositories.

You can store multiple files in a single repository, and you can either manage your templates from separate repositories, or include them in the same repository as the application you want to deploy and manage on Northflank.

Northflank must have access to the repository to be able to create and update templates in it. If the repository is not accessible, navigate to Git integrations in your Northflank account and edit the installation for the Git account to enable access.

Save a new template in a repository

You can create a template file in the Northflank application and save it to a repository and branch of your choice. Select the repository and branch, and enter the path (relative to the repository root) you want to save the file to.

Click fetch to check the template does not already exist, and continue editing your template. When you save, Northflank will create the file in your repository, and link it with the template or release flow in the Northflank application.

Use an existing template

You can use a template or release flow that already exists in a Git repository on Northflank. Select the repository and branch that contains the template file you want to use in the GitOps section.

Enter the path to your file (relative to the repository root, e.g. /my-template.json or /release-flows/development-release-flow.json) and click fetch to retrieve the existing template or release flow.

Northflank will load the file into the editor, and the file in the repository will be linked with the template or release flow in the Northflank application.

GitOps template object

When you enable GitOps for a template a new top-level object will be created to store the GitOps data.

{
  "gitops": {
    "vcsService": "",
    "accountLogin": "",
    "repoUrl": "",
    "branch": "",
    "filePath": ""
  }
}

Any changes you make to a release flow or template with GitOps enabled in the Northflank application will be pushed to your linked repository on the configured branch on save.

Likewise, any commit pushed to the linked branch in your repository will update the template or release flow in Northflank.

Run a template on change

You can enable run automatically when the template is updated so that any changes to the template pushed to your repository will trigger a run of the template. You may want to configure your template's concurrency settings, so that multiple updates in a short time period are handled as desired.

Run a release flow on change

You can run a release flow when changes are pushed to your repository, by configuring Git triggers.

You can configure Git triggers to run a release only on commits to specific branches or pull requests with branch and pull request rules. You can also only run a release flow when either specific files or directories are changed, or ignore certain files or directories so releases are not triggered by, for example, documentation files.

You can also add commit message ignore flags, so that releases will not be triggered when commits with certain strings are pushed to your repository.

You can use a single template file in a Git repository as the source for multiple Northflank templates. To use the same template file for multiple Northflank templates you can use arguments, as well as references and functions to make it programmatic, and not tied to specific projects or regions.

You can then create multiple Northflank templates from the template file. Create a new template in Northflank, enable GitOps and enter the repository, branch, and path of your template. Give the template a distinct name and provide the necessary configuration values and secrets using argument overrides, which can be added in the template's settings. You can then repeat this process, adding different argument overrides for each template. Argument overrides are stored securely on Northflank, and not saved to your Git repository.

The example below shows a template that creates a new project with a combined service. Most of the configuration fields are given as arguments, some of which are set as defaults in the arguments object, which can be overridden. Other arguments have no defaults, and must be provided as overrides for a successful template run.

{
  "argumentOverrides": {
    "PROJECT_NAME": "Demo in Europe West",
    "PROJECT_REGION": "europe-west",
    "API_KEY": "123xyz"
  }
}

{
  "apiVersion": "v1.2",
  "arguments": {
    "PROJECT_NAME": "",
    "PROJECT_REGION": "",
    "SERVICE_INSTANCES": "1",
    "SERVICE_PLAN": "nf-compute-100-1",
    "GIT_ACCOUNT": "acme_corp",
    "GIT_REPO": "https://vcs.example.com/acme-corp/demo-service",
    "GIT_BRANCH": "main"
    "API_KEY": ""
  },
  "spec": {
    "kind": "Workflow",
    "spec": {
      "type": "sequential",
      "steps": [
        {
          "kind": "Project",
          "ref": "project",
          "spec": {
            "name": "${args.PROJECT_NAME}",
            "color": "#7FD1B9",
            "region": "${args.PROJECT_REGION}",
            "networking": {
              "allowedIngressProjects": []
            }
          }
        },
        {
          "kind": "Workflow",
          "spec": {
            "type": "sequential",
            "context": {
              "projectId": "${refs.project.id}"
            },
            "steps": [
              {
                "kind": "CombinedService",
                "spec": {
                  "deployment": {
                    "instances": "${args.SERVICE_INSTANCES}",
                    "storage": {
                      "ephemeralStorage": {
                        "storageSize": 1024
                      },
                      "shmSize": 64
                    },
                    "docker": {
                      "configType": "default"
                    }
                  },
                  "runtimeEnvironment": {
                    "API_KEY": "${args.API_KEY}"
                  },
                  "runtimeFiles": {},
                  "buildArguments": {},
                  "buildFiles": {},
                  "billing": {
                    "deploymentPlan": "${args.SERVICE_PLAN}",
                    "buildPlan": "nf-compute-400-16"
                  },
                  "name": "Demo",
                  "vcsData": {
                    "projectType": "github",
                    "accountLogin": "${args.GIT_ACCOUNT}",
                    "projectUrl": "${args.GIT_REPO}",
                    "projectBranch": "${args.GIT_BRANCH}"
                  },
                  "ports": [
                    {
                      "internalPort": 80,
                      "protocol": "HTTP",
                      "name": "web",
                      "public": true,
                      "domains": [
                        "${args.PROJECT_REGION}.example.com"
                      ],
                      "security": {
                        "policies": [],
                        "credentials": []
                      },
                      "disableNfDomain": true
                    }
                  ],
                  "buildSettings": {
                    "dockerfile": {
                      "buildEngine": "kaniko",
                      "useCache": false,
                      "dockerWorkDir": "/",
                      "dockerFilePath": "/Dockerfile"
                    }
                  },
                  "disabledCI": false,
                  "buildConfiguration": {
                    "pathIgnoreRules": [],
                    "isAllowList": false,
                    "ciIgnoreFlagsEnabled": false
                  }
                },
                "ref": "demo"
              }
            ]
          }
        }
      ]
    }
  }
}

In order to use GitOps securely with release flows and templates you should avoid including any sensitive data in the file committed to the repository, even if it is private.

You can save secrets for a template as argument overrides in the template settings, or pass them in using the API, CLI, or client when triggering a template run.

These arguments will be securely stored on the Northflank platform so you can save any sensitive information, or information you do not want to include in the template, as argument overrides. They can then be used in your template by referring to them using the format ${args.argumentName}, replacing argumentName with the key saved in argument overrides.

You can remove the integration with your infrastructure file by disabling GitOps for the template or release flow in the Northflank application.

This will leave the file in your repository, but changes pushed to the file in your repository will no longer update the relevant release flow or template on Northflank. Similarly, changes made on Northflank will not be pushed to the file in your repository.