Why moving from NiFi Registry to Git-based flow registry clients is the next step
Your flows are versioned in NiFi Registry, and the NiFi project has deprecated that registry for removal in NiFi 3.0. NiFi 2.12.0, released on September 13, 2026, includes flow registry clients for GitHub, GitLab, Bitbucket and Azure DevOps, so the next step is to plan a move of your version history and flow storage onto one of those Git hosts. This is a data migration, not an in-place upgrade. Your NiFi instances keep running, but the place where flow versions live, who can review them and how they are promoted all change. Treat the move as its own project with its own cutover date.
No removal date for NiFi 3.0 was supplied for this page, so confirm timing with the Apache NiFi project before you set your deadline, through its download and release information. A deprecation notice tells you the direction of travel, not when your registry will stop working. Plan against the earliest date your change calendar can accept, and ask the project to confirm the removal plan for the release line you intend to run. Also confirm which registry client each of your buckets will map to, since the GitHub and GitLab clients are documented in the NiFi component index and the Bitbucket and Azure DevOps clients should be checked against their own component pages before you commit.
Keep the existing NiFi Registry available as a fallback until the cutover is verified. Do not decommission it when the first Git-backed version commits. Before retiring it, confirm that every bucket and version you need has been exported, that a sample of exported versions re-imports cleanly into a test NiFi, and that a restored process group can be started and compared against the registry copy. Once those checks pass, record the retirement decision, the owner who signs it off and the date the registry becomes read-only. Until then, the registry is your rollback path if a Git-backed flow fails to load.
What changes when versioned flows leave NiFi Registry for Git
This table compares what changes in each area of flow versioning when a team moves from NiFi Registry to a Git-based flow registry client. Read each row as a question to answer for your own flows before you retire the registry. The main takeaway is that the move is a change to version history, import practice and team workflow, not only a change of storage location.
| Change | Impact | Action needed |
|---|---|---|
| NiFi Registry is deprecated and planned for removal in NiFi 3.0 | Registry-backed flows have no supported long-term home in the NiFi line. Existing buckets keep working until the registry is retired, but new work should not depend on it. | Inventory every bucket and flow that depends on the registry, and set a retirement date with the owners of each flow. |
| Git flow registry clients are available in NiFi 2.12.0 | NiFi 2.12.0 includes clients for GitHub, GitLab, Bitbucket and Azure DevOps. Each client writes flow versions to a repository instead of a registry bucket. | Confirm the client that matches your code host and the NiFi version you run before you configure any production instance. |
| GitHub client uses the REST API | Every save, list and read goes through GitHub's API, so token scope, rate limits and network egress from NiFi nodes affect day-to-day versioning. | Confirm token permissions and API access from each NiFi node, including any proxy or air-gapped path your network requires. |
| GitHub client retrieves at most the last 10 commits per flow | Version history visible in NiFi may not show older commits for a flow. Long-lived flows can lose easy access to earlier versions in the client, even though the repository keeps them. | Use Git tools for full history and audits, and record in your runbook where older versions are read from. |
| Toolkit export-all-flows lists and exports every version | The command lists every bucket, flow and version in a registry and writes each version to a directory. This gives you a complete copy to convert into a repository layout. | Run the export against a test copy first, check the directory count against the registry, and keep the output under change control. |
| Imports into NiFi 2 instances need a deliberate path | Flows versioned in a registry are imported through the registry, while Git-backed flows are imported through the client. Flow identifiers and bucket references may not match after migration. | Test importing a sample flow into a NiFi 2 instance, confirm versions and parameter contexts resolve, and document the import steps. |
| Team workflow shifts to branches and pull requests | Versioning moves into the code host's review and merge process. Who may commit, approve and tag releases becomes a repository policy rather than a registry permission. | Agree a branch strategy, review rules and naming for production flows before the first commit to the new repository. |
Choosing a Git host for flow versions
NiFi 2.12.0 includes a GitHub flow registry client that versions flows in a GitHub repository through the GitHub REST API. The client's documentation notes that it retrieves at most the last 10 commits for a given flow to limit API calls, which affects how you read history for a busy flow. Confirm how your organization issues credentials for that API access before you configure the client, because the token scope and who owns it will shape your audit trail.
- Client: the GitHubFlowRegistryClient, available in NiFi 2.12.0 alongside the other Git clients.
- Access model: confirm which token type your organization permits, its scope, its owner and its rotation schedule.
- Identity fit: check whether your GitHub organization federates with your identity provider and whether service accounts are allowed for flow commits.
- Approvals: map required reviews and branch protection rules to the flow change process you already run.
- Hosting and offline needs: confirm whether your GitHub organization is cloud-hosted and reachable from every NiFi node, since the client depends on API connectivity.
Confirm the API history limit and the token policy with your GitHub administrators before you design the branch strategy.
NiFi 2.12.0 includes a GitLab flow registry client, so flows can be versioned in a GitLab project. GitLab can also be self-managed, which matters if your flows and their history must stay inside your own network. The GitLab documentation covers offline and air-gapped operation, but whether your version and license tier support the approval and access features you need must be confirmed against the current GitLab pricing and feature pages. Treat the hosting choice as a decision made before the NiFi side of the design.
- Client: the GitLabFlowRegistryClient, included in NiFi 2.12.0.
- Hosting: decide between GitLab.com and a self-managed instance, and confirm whether the instance will run in a network NiFi can reach without an external proxy.
- Access model: confirm the token type, its scope and the project role that the NiFi service account will hold.
- Identity fit: check whether your GitLab instance is connected to your identity provider and whether the service account follows your joiner and leaver process.
- Branch protection: confirm which protected branch settings and approval rules your edition provides for flow repositories.
Verify the license tier and the self-managed upgrade path with GitLab before you commit to a self-hosted design, since both affect long-term operation.
NiFi 2.12.0 includes a Bitbucket flow registry client. Because Bitbucket is offered in cloud and self-managed forms, the first question is which one your organization already runs and whether NiFi nodes can reach it. The client's configuration, required scopes and any API limits should be read from the component documentation for your NiFi version rather than from assumptions made about other clients. Plan the credentials and repository ownership before you configure a single flow version.
- Client: the Bitbucket flow registry client, included in NiFi 2.12.0.
- Hosting: confirm whether you use Bitbucket Cloud or a self-managed Bitbucket Data Center or Server instance, and whether NiFi nodes can reach it.
- Access model: confirm the app password or token type, its permissions and the account that owns it.
- Identity fit: check whether your Atlassian identity setup covers service accounts and whether access reviews include them.
- Approvals and branch rules: confirm which branch permissions and required reviewers apply to the flow repository.
Ask your Bitbucket administrators to confirm the exact client settings and access model for your deployment before the design is final.
NiFi 2.12.0 includes an Azure DevOps flow registry client. Teams that already manage source, pipelines and approvals in Azure DevOps often prefer to keep flow versions in the same organization, which can simplify audit and access reviews. Confirm your Azure DevOps organization, the project that will hold flows and how Microsoft Entra ID groups map to project permissions before the NiFi side is configured. Check the client's documentation for the authentication method it supports in your version.
- Client: the Azure DevOps flow registry client, included in NiFi 2.12.0.
- Access model: confirm the authentication method the client supports, the scope of the credential and the identity that owns it.
- Identity fit: check whether Microsoft Entra ID groups govern repository permissions and whether the NiFi service identity is covered by your access reviews.
- Approvals: map pull request policies and required reviewers to the flow promotion process.
- Hosting and network: confirm whether your organization uses the cloud service or a self-managed Azure DevOps Server, and whether NiFi nodes can reach it.
Confirm the supported authentication method and network path with your Azure DevOps administrators before you finalize the access design.
What to inventory and back up before the first export
These six items come before the first export and protect different failure points: knowing what exists, keeping a way back, knowing what flows depend on, testing the import, reaching the Git host, and deciding in advance how to undo the move. Skipping any one of them tends to turn a routine export into an incident that is hard to reverse.
Inventory of buckets, flows and versions
List every bucket, flow and version in the NiFi Registry instance before exporting anything. The export-all-flows command in the NiFi Toolkit lists every bucket, flow and version and writes each version to a directory, so the inventory and the export can share one run. Record version counts per flow and flag flows with no recent versions, since those may be stale or abandoned. This inventory is the baseline you check the Git repository against after migration.
Backup of NiFi Registry storage
Take a full backup of the Registry metadata and flow storage before any command touches it. Export is a read operation, but a backup is the only way to restore the original state if a later step changes or removes data. Confirm the backup can be restored on a separate host, and store it under the same retention and access rules as the source. Keep it until the Git-based registry has been verified and the old instance is retired.
Flow dependencies and parameter contexts
List what each versioned flow needs to run: parameter contexts, controller services, referenced Registry buckets, and any external resources such as databases or certificates. A flow that exports cleanly can still fail on import if a controller service or parameter context it references does not exist in the target. Check which parameter contexts hold sensitive values, because those values do not travel with the flow definition and must be supplied again at the destination.
NiFi 2 test environment for import
Stand up a NiFi 2 test instance that matches production in version, Java runtime and component set, and import the exported flows there first. The test environment shows whether flows import, bind to the right controller services and start without errors. Use it to confirm the Git-based registry client settings before any production flow depends on them. Keep the test instance separate from production so that a failed import never affects running dataflows.
Access and identity for the Git host
Decide which Git host the flows will live on, then set up the identity and access that NiFi uses to reach it. The GitHub and GitLab flow registry clients are configured with credentials for the repository, so confirm whether the service account, token type and repository permissions meet your access policy. Limit write access to the flow repository to the NiFi service identity and the people who approve flow changes. Verify that the host is reachable from every NiFi node that will run the client.
Written rollback runbook
Write a rollback runbook before the cutover, naming who decides to roll back, the conditions that trigger it, and the exact steps to restore the Registry and point NiFi back at it. Include how to reconnect process groups that were bound to the Git-based client, and how to restore the Registry backup on the same host or a replacement. Rehearse the runbook in the test environment. A runbook that has never been run tends to fail at the point where a team needs it most.
How exported versions become a Git repository layout and branch strategy
The export-all-flows output is not a repository. It is a directory of versions, one set per bucket, that the team must map into a layout Git can hold and review. Decide that layout before the first commit. A common option is one repository per bucket or one repository for all flows with a folder per bucket. Either way, settle how flow names become file names, since NiFi flow names may contain spaces or characters that are awkward in paths, and record the mapping from registry bucket and flow identifiers to repository paths so that a later reader can trace any Git file back to the original registry object. Confirm how each exported version file is named and whether the version number is kept in the commit message, the file name or both.
The branch strategy is a decision the team makes and then tests, not a default. One pattern is a protected main branch that holds reviewed flow versions, with promotion branches or environment-specific tags that move a version toward production. Test the strategy by running it on a copy of a real flow: create a change, promote it, roll it back and confirm that the NiFi flow registry client in each environment points at the expected branch or tag. Check how the GitHub client and the GitLab client expose branch selection in their component documentation before you commit to a pattern, and confirm that your Git provider can enforce protected branches and required reviews on the paths you choose.
Plan for the audit trail before you retire the registry. The GitHub flow registry client retrieves at most the last 10 commits for a given flow, so Git history alone may not cover every version an auditor asks about. Confirm with your compliance owner which history must be available online, then keep the complete export-all-flows output as archived evidence in a controlled location with its own retention rule. Record the export date, the NiFi and Toolkit versions used and a checksum for each archive. That archive, not the live Git history, is the record of what the registry held when it was retired.
How to cut over from NiFi Registry without losing version history
This sequence moves every bucket, flow and version out of NiFi Registry into a Git repository that a Git-based flow registry client reads, and keeps the original registry intact as a read-only rollback point. Each step closes with a check, so the team can confirm parity before any environment depends on the new source.
Inventory buckets, flows and client usage
Record every bucket, flow and version in the NiFi Registry, and list every NiFi 1.x or 2.x instance and process group that points to it through a registry client. Note which environments (development, test, production) use which bucket, and which flows are versioned but not currently running. The owning team signs off on this list. Done means every consuming instance and process group is named, so no dependency on the registry is left unrecorded before the cutover begins.
Back up the registry and its storage
Take a full backup of the NiFi Registry persistence directory and its metadata database, and store it outside the registry host. Confirm the backup can be read by restoring it to a scratch location and checking that bucket and version counts match the inventory. Rollback point: the untouched backup allows the registry to be restored exactly as it was, if any later step fails.
Export all buckets and versions
Run the NiFi Toolkit CLI export-all-flows command against the registry so that it lists every bucket, flow and version and writes each version to a directory. Keep the export output in a staging location, not in the live repository. Check that the number of exported versions matches the count from the inventory, and that each exported file opens and parses as a flow definition. Rollback point: the export is a copy, so the registry remains the source of truth until a later step freezes it.
Design and review the repository layout
Decide how buckets map to directories, how flow names map to file names, and whether one repository serves all buckets or each bucket gets its own. Choose a branch strategy, for example one branch per environment or one main branch with tags for releases, and agree who may merge to each branch. Review the layout with the platform and security leads and record the decision in the repository README. Done means the layout is approved and documented, and a sample flow can be placed by the process without manual renaming.
Import a sample flow into a NiFi 2 test instance
Configure the chosen Git-based flow registry client on a NiFi 2 test instance, such as the GitHub, GitLab, Bitbucket or Azure DevOps client, using a dedicated access token with the narrowest repository permissions that work. Commit one exported flow with the new layout, then import it into a process group and start a version. Check that the client can read and commit to the repository and that the flow appears with its expected name. Rollback point: the test instance is disposable, so nothing in production depends on this step.
Verify version and content parity
Compare each migrated flow in the Git repository with its source version in the registry, checking version count, comments, and the flow content itself after import. Confirm that parameter references, controller service references and the version history order are preserved, and record any differences in a defect list. Note that the GitHub client retrieves at most the last 10 commits for a flow, so review the history access model before relying on long histories inside the client. Done means every discrepancy is either fixed or accepted in writing.
Switch development, test and production in order
Point the development instance at the Git-based client first, run it for a defined review period agreed by the team, then move test and production in the same order. Each environment changes its registry client configuration and re-links its process groups to the migrated flows. Check after each switch that the process groups show the expected version and that a change committed to the repository can be pulled into the environment. Rollback point: until production switches, reverting an environment means pointing it back to the NiFi Registry client.
Freeze writes and keep the registry read-only
Once every environment runs on the Git-based client, stop all new commits to NiFi Registry, remove or disable write permissions for users and automation, and keep the service running in read-only mode. Retain the backup and the export for the agreed retention period. Confirm that no instance still references the registry and that a read attempt returns the expected history. Rollback point: a read-only registry with its data intact allows the team to recover earlier versions if a problem surfaces after cutover, and it remains the reference until the decommission decision is made.
What makes a registry retirement take longer
This table lists the factors that stretch a NiFi Registry retirement and what each one means for planning. Read each row as a question to answer about your own estate before you estimate scope. The main takeaway is that bucket count and version history matter less than how many flows depend on parameter contexts, controller services and live environments.
| Driver | Why it matters | What to ask |
|---|---|---|
| Number of buckets and versions | Each bucket and version must be listed, exported and checked, and stale or duplicate versions add review work. | How many buckets, flows and saved versions exist, and which ones are still deployed? |
| Flows referencing parameter contexts | Flows tied to parameter contexts need those contexts recreated or mapped in the target layout before re-import. | Which flows bind to parameter contexts, and do any contexts hold sensitive values? |
| Flows referencing controller services | Controller service references and their property values must match in each environment, or flows will fail to start after re-pointing. | Which versioned flows depend on shared controller services, and where are those services defined? |
| Depth of version history to keep | Keeping every historical version preserves audit trails but increases export volume and the number of commits to recreate. | What history do auditors, change records or rollback plans require, and for how long? |
| Git host identity and approval model | Access to the repository, branch protection and pull request approvals define who can publish flow changes and must be set up before cutover. | Which identity provider signs users in, who approves merges, and are branch protections in place? |
| Number of NiFi environments to re-point | Each cluster or standalone instance needs its registry client configured, tested and, where required, reconnected to flows. | How many environments exist (development, test, production), and in what order will they change? |
| Testing required by change management | Change control often requires proof that re-imported flows run the same way, which adds test cycles and sign-off steps. | What test evidence and approvals does your change process require before a registry client change is accepted? |
What teams ask before retiring NiFi Registry
How much does moving from NiFi Registry to Git-based registry clients cost?
The cost is set by the written scope, and there is no published price list, so a quote follows from the plan agreed in writing before work starts. The main cost components are the inventory of buckets and versions, the export and conversion of flows into a repository layout, the setup of the Git hosting and access model, the cutover testing, and the handover. Costs go up with the number of buckets, the number of versions you need to keep, the number of flows that reference parameter contexts or controller services, and the number of environments that must be verified. Ask for a quote that lists each deliverable, who performs each step, and what is one-time versus ongoing. Ongoing support or upgrades are separate retainers.
How long does a NiFi Registry to Git migration take?
Duration depends mainly on how many buckets, flows and versions exist, how many environments need verification, and how quickly the client's owners approve the repository layout and branch strategy. Teams with a small, well-documented registry usually move faster than teams whose flows have no clear owner or whose versions were never reviewed. Ask for a timeline in the written plan with milestones for inventory, export, a test instance, cutover and read-only period. Confirm the specific durations with DeployOpen during scoping, since no fixed timeline is published here.
What does the client's team need to provide for this work?
The work needs access to the existing NiFi Registry and its storage, a test NiFi instance, and access to the target Git hosting such as GitHub, GitLab, Bitbucket or Azure DevOps. It also needs a named owner for each bucket who can confirm which versions are current, which are obsolete and which must be kept. Someone with authority must approve the branch strategy, the repository layout and the naming of process groups. Finally, the team should designate a contact for testing the promoted flows in each environment and for signing off the cutover.
Can our team retire NiFi Registry without a partner?
Yes, a capable team can do the work alone using the NiFi Toolkit and a test instance. The export-all-flows command lists every bucket, flow and version and exports each version to a directory, which covers the mechanical part. The harder decisions are the repository layout, which versions to keep, how branches map to environments, and how to verify that a flow imported from Git behaves the same as the registry copy. Those decisions need owners who understand the flows, so teams without that capacity often bring in a partner for the design and verification steps.
Does version history carry over completely to a Git flow registry?
Not automatically, and you should confirm the limits before relying on it. The GitHub flow registry client retrieves at most the last 10 commits for a given flow to limit API calls, so older history may not be visible through the client. Other clients have their own behavior, which you should check in the component documentation for your NiFi 2 release. For that reason, keep a full export of every NiFi Registry version from the Toolkit as an archive, store it in a location with its own retention policy, and treat Git as the working history rather than the only record.
Can we keep NiFi Registry running after cutover?
Yes, keeping the registry available in a read-only state until the cutover has been verified is a sensible transition step. Read-only access lets teams check old versions, compare exports against the Git repository and recover a flow if a problem appears in testing. Plan a defined date for decommissioning, record who approves it, and make sure the registry's backups are retained for the period your records policy requires. NiFi Registry is deprecated and planned for removal in NiFi 3.0, so the retirement date should be set before that release arrives.
How DeployOpen works on this
DeployOpen plans and implements the move from NiFi Registry to a Git-based flow registry client inside your own infrastructure. We start with a written scope that inventories your buckets, flows and versions, then build, test, document and hand over the new repository layout and branch strategy.
How we scope
- We inventory every NiFi Registry bucket, flow and version that must be preserved before work starts.
- The written scope names the Git provider, repository layout, branch strategy and who approves changes to flows.
- Engagements are fixed-scope, so deliverables and timelines are agreed in writing before any migration work begins.
- We confirm which NiFi version and flow registry clients your environment runs before choosing the target design.
How we build
- We export versions with the NiFi Toolkit and check each exported flow against the source registry.
- We commit flows to the agreed repository layout and test that each NiFi instance can import and run them.
- We connect registry clients to your Git provider inside your network, including access tokens and credential handling.
- We test rollback, version switching and deployment across environments before the old registry is retired.
How we hand over
- You receive the repository structure, branch rules and naming conventions as written documentation.
- Runbooks cover adding a flow, promoting a version, resolving a conflict and restoring from the repository.
- We walk your platform and flow teams through the new process and record the decisions taken during the move.
- The handover includes a retirement checklist for the NiFi Registry instance and its stored data.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- A retainer can cover NiFi version changes that affect registry clients, such as moves toward NiFi 3.0 planning.
- Ask any partner to confirm how support requests, response expectations and change control are written into the agreement.
