Request icon
ForEach icon
SyncFlows icon
SyncNamespaceFiles icon

Sync Flows, Files, and KV Stores from GitLab with GitOps Best Practices

Restore Kestra flows, namespace files, and key-value stores from a GitLab repo with a GitOps backup and recovery workflow driven by the GitLab API.

Categories
CoreInfrastructure

Treat GitLab as the single source of truth for your entire Kestra environment. This blueprint restores and synchronizes flows, namespace files, and key-value (KV) store entries directly from a GitLab repository, solving the problem of rebuilding a Kestra instance after a migration, outage, or environment reset. Instead of clicking through the UI to recreate workflows and configuration, you point this flow at a branch and let it pull everything back into the right namespaces, declaratively and repeatably.

How it works

  1. A branch_target input lets you pick which GitLab branch to restore from (main or kestra), so you can promote between environments safely.
  2. get_flows_targets and git_target call the GitLab REST API with io.kestra.plugin.core.http.Request to list the subfolders under _flows and _files, using {{ secret('GITLAB_API_TOKEN') }} for auth.
  3. for_each_flows_folder iterates those folders and runs io.kestra.plugin.git.SyncFlows, mapping each _flows/<name> directory into a matching targetNamespace.
  4. for_each_files_folder does the same with io.kestra.plugin.git.SyncNamespaceFiles, restoring namespace files from each _files/<name> directory.
  5. fetch_kv downloads _kv/kvStore.json, then nested for_each_namespace_store and for_each_key loops PUT each key back into the Kestra KV API, preserving STRING typing on the value.

What you get

  • One-command restore of flows, files, and KV pairs from version control.
  • Namespace structure inferred automatically from the Git directory layout.
  • Branch-based promotion between environments via a single input.
  • Idempotent re-runs that keep Kestra in sync with the repo.

Who it's for

  • Platform administrators bootstrapping or recovering a Kestra instance.
  • DevOps and infrastructure engineers running GitOps and disaster recovery.
  • Teams replicating one environment into another (staging to production).

Why orchestrate this with Kestra

GitLab can host the source of truth and trigger CI, but it cannot reconcile that state into a running Kestra instance, fan out across an unknown set of namespace folders, or retry a partial restore. Kestra adds event and schedule triggers, per-task retries, full execution lineage over every SyncFlows, SyncNamespaceFiles, and KV write, and a declarative YAML definition that is itself versioned in the same GitLab repo it restores.

Prerequisites

  • A GitLab repository laid out with _flows, _files, and _kv folders.
  • The GitLab project ID set in vars.your_project_id.
  • A reachable Kestra API at kv('kestra_local_uri') for KV writes.

Secrets

  • GITLAB_API_TOKEN: GitLab access token for the REST API and Git pulls.
  • KESTRA_API_TOKEN: authorization header for the Kestra KV API.

Quick start

  1. Add the GITLAB_API_TOKEN and KESTRA_API_TOKEN secrets.
  2. Set vars.your_git_repository and vars.your_project_id to your repo.
  3. Set the kestra_local_uri KV value to your Kestra API endpoint.
  4. Execute the flow and select the branch_target to restore from.

How to extend

  • Add a schedule trigger to run periodic environment reconciliation.
  • Add more branch options for additional environments.
  • Wrap the run in retries and a Slack alert on failure for safer restores.
  • Extend the KV loop to handle non-string types or selective namespaces.

Links

See How

New to Kestra?

Use blueprints to kickstart your first workflows.