Deploying Flowable process definitions from CI/CD

Deploying Flowable process definitions from CI/CD: what the pipeline must do

A team that keeps BPMN, CMMN and DMN models in Git needs a pipeline that moves each approved change into the production engine without manual uploads. In practice, the pipeline does three things: it packages the model files into a deployable unit, it deploys them to the Flowable engine through the engine's API, and it creates a new definition version each time, so running instances keep the version they started with while new instances pick up the change. Every deploy should produce a new version that traces back to one commit. Those three steps are the baseline. The design work sits in how the pipeline handles the Java code and rules that models depend on, and how it proves what is running.

Teams need this when models change often, when several environments such as test, staging and production must hold the same definitions, or when auditors expect a record of who changed a process and when it went live. Manual uploads through a modeling tool make those questions hard to answer. Flowable's engines are licensed under Apache 2.0 and expose both Java and REST APIs, according to the Flowable open source page, so a pipeline can call either interface. Confirm with your own engineers which interface your deploy step will use, and whether the engine version in each environment matches, because a model that deploys cleanly to one version may depend on features another version lacks.

Before you build the pipeline, decide four things: how the deploy step authenticates to the engine, which environment promotions require a human approval, how the pipeline records the Git commit and deployment ID together, and what the rollback path is. Rollback in a versioned engine usually means deploying or activating an earlier definition for new instances, not deleting a version that running instances still use, so the pipeline should not be designed to remove definitions. Ask your team to write down, for each model type, which Java classes, delegates or DMN inputs it needs at runtime, because a deploy that succeeds can still fail when a referenced class is missing from the target classpath.

Which deployment path fits your Flowable application

When Flowable runs as a Spring Boot starter inside your application, the engine can deploy model files automatically at startup. The Spring Boot documentation describes the starters for the all-engines, single-engine and REST cases, and the auto-deployment behavior follows from the resource locations the application is configured to scan. In this path, the pipeline usually packages BPMN, CMMN and DMN files into the same artifact as the application, so a model change becomes a new application build and a new release.

What the pipeline pushes: a versioned application artifact that contains the model files under the classpath resource folders the engine scans.
Where models are read from: the classpath of the running application, usually loaded at startup.
Who owns the step: the application team and its release pipeline, with the platform team owning the container or runtime.
Effect on versioning: each deploy registers new definition versions, and the engine keeps earlier versions for running instances.
Rollback: redeploying the previous application artifact restores the earlier models, but confirm how running instances on newer versions behave.

Confirm in the Spring Boot documentation which resource locations are scanned by default and how your build tool places model files there.

Deployment options and when each fits

This table compares the four ways BPMN, CMMN and DMN models reach a running Flowable engine: business archives, Spring Boot auto-deployment, the repository service and the REST API. Read each row against your pipeline's deployment step, because the artifact, the calls your pipeline makes and the versioning behavior differ. The main takeaway is that the mechanism you pick determines how rollback and audit trails work, so choose it before the pipeline is built.

Mechanism	Artifact produced and what the pipeline calls	Versioning behavior	Main risk
Business archive (BAR)	A packaged archive of model files built in CI, deployed through the engine's repository service or a deployment step that reads it	Each deployment creates a new version of each definition; earlier versions stay available for running instances	Archive contents drift from the Git commit if builds are not reproducible or artifacts are rebuilt by hand
Spring Boot auto-deployment	Model files placed in a resource location in the application jar, picked up when the application starts	New versions are created on startup when the file content changes, tied to the application release	A restart of several nodes can register the same change more than once, and rollback means redeploying an older application build
Repository service (programmatic)	Model files read from Git or a build output and passed to the repository API by code the team owns	The team controls when a deployment happens and can add deployment names and tenant IDs	Custom deployment code becomes a maintained component, and skipped checks can push unreviewed models to production
REST deployment	A model file uploaded over HTTP to the Flowable REST application from a pipeline step	Each upload creates a new definition version on the target engine	Credentials for the REST API and network reach to the engine must be managed, and failed uploads need explicit retry handling

Setting up a Git-to-engine deployment pipeline

The sequence moves a model change from a reviewed Git commit to a verified definition on a production Flowable engine, with a check at each stage so a broken model never reaches production unnoticed. Each stage produces an artifact or a result that the next stage depends on.

Organize models in a repository by engine
Your platform or process engineering team creates one repository for process models with a folder for each engine: bpmn, cmmn and dmn, plus a folder for the Java classes that delegates and listeners depend on. Keep the model files in the format your modeling tool saves, and commit them with a reviewer's approval before any pipeline job runs against them. Each model file keeps its own process or decision key, so the engine can version the definition when it is deployed. Done when a merge request shows the changed model files under the correct engine folder and a reviewer has approved the change.
Validate each model in CI before packaging
On every merge request, the pipeline parses each BPMN, CMMN and DMN file with the Flowable engine's own parser or with a schema check your team agrees on, and fails the job on any parse error. Add a check that every process or decision key referenced by a call activity or decision task exists in the same change set or in the target environment. Your team should also confirm that every Java class named in a service task or listener is present on the classpath at build time. Done when a deliberately broken file fails the job with a message that names the file, and the unchanged models pass.
Build the deployment artifact
The build job packages the validated model files and any custom delegate classes into the deployment artifact your team chose, such as a business archive or a Spring Boot application image that includes the resources. Tag the artifact with the Git commit hash so every running definition can be traced to one revision. Store the artifact in your registry or artifact repository, not on a developer workstation. Done when the artifact exists in the repository under the commit tag and its contents list matches the models in the commit.
Deploy to a staging engine
The pipeline deploys the artifact to a staging Flowable engine that uses a database schema close to production, either by starting the Spring Boot application with auto-deployment enabled or by calling the REST deployment endpoint with the archive. Staging should run the same engine version and Spring Boot starters as production. Confirm the database credentials and schema settings come from the environment, not from the artifact. Done when the staging deployment job completes without errors in the engine logs.
Verify the new definition version and actuator endpoint
After staging starts, query the engine for the deployed process, case or decision definitions and confirm the new version appears with the expected key and an incremented version number. Then call the Spring Boot actuator endpoint at /actuator/flowable, which the Flowable Spring Boot docs describe for monitoring running processes, and confirm it returns a successful response. Run a smoke test that starts one instance of each changed process and checks that it reaches the first wait state. Done when the definition list shows the new version, the actuator endpoint responds, and the smoke test instance reaches its expected state.
Promote the same artifact to production
Promote the exact artifact that passed staging rather than rebuilding it, so production runs the commit that was tested. Require an approval gate before the production deployment job, and record who approved it and which commit was deployed. Run the same definition-list and actuator checks against production after the rollout, and confirm that existing running instances continue on their original versions unless you have chosen to migrate them. Done when production lists the new definition version, the actuator endpoint responds, and the deployment record links the approval to the commit.
Record the rollback path before release
Before each production release, the team confirms how to return to the previous state, because a new definition version does not replace running instances. Rollback usually means redeploying the previous artifact tag or deploying an earlier definition and directing new starts to it, and your team should test that path in staging. Confirm with your Flowable version and modeling conventions which rollback method fits your process design, since running instances on the new version may need separate handling. Done when the rollback procedure has been run once in staging and the steps are written into the release record.

How versioning on each deploy affects running instances

Every deployment of a changed BPMN, CMMN or DMN model creates a new definition version in the engine, and the version a pipeline publishes is not the version a running case or process will follow. Process instances that started on an earlier version keep executing that version until they complete or someone migrates them. For a pipeline, this means a successful deploy does not change behavior for work already in flight. A model that waits weeks on a human task or a timer can still be running on a definition your team considers retired. Before the first production rollout, ask the team to list which processes and cases are long-running, which ones they would need to move to a new version, and whether a version migration is a supported operation for that model. Confirm the exact redeployment and migration behavior for your Flowable version in the Flowable docs, since the rules for existing instances are version-specific.

The second risk sits outside the model file. Service tasks, execution listeners, task listeners and expressions in a model resolve Java classes and beans by name at runtime, so a new definition that references a delegate class the production classpath does not contain will fail when the engine reaches that step. The pipeline therefore has to release the model and the JAR or Spring beans it depends on as one unit, with the classes deployed before or with the definition that calls them. Old delegates must also stay available for instances still on earlier versions, which means removing a class is a separate change that waits until no running instance references it. Treat each model's class references as a manifest that the pipeline checks before publishing, and confirm how your chosen packaging, whether business archive or Spring Boot application, loads those classes.

Rollback options when a deployed model misbehaves

A bad process definition can be recovered in several ways, and each one handles running instances and data differently. Flowable does not offer a single rollback button, so the choice depends on whether the fault is in the model, the code or the data. The cards below set out the options side by side with what each costs in data terms.

Redeploy the previous Git revision

Rebuild the archive from the last known good commit and deploy it. Flowable stores the result as a new version of the same key, so the old definition is not overwritten and running instances stay on the version they started with. New starts use the redeployed model unless the process is pinned to a version. Confirm in the target Flowable release how the deployment API selects the latest version when a process is started by key, and whether your pipeline records the commit that produced each deployment ID.

Route new starts to a prior version

Keep the faulty deployment in place but start new instances against an earlier version key, either through a start call that names the version or through a routing rule in the calling application. Nothing is deleted, so the data cost is low, but every caller must support the pinned version. Confirm that the earlier version still exists in the repository tables and that the start API in your Flowable release accepts a version parameter.

Pause new starts and fix forward

Stop the calling application or API route from creating instances of the faulty process while a corrected model is built and tested. Running instances continue, so this option protects data but leaves stuck work waiting. It needs a feature flag or gateway switch outside Flowable. Confirm which teams can flip the switch, how quickly it takes effect in each caller, and how queued requests are handled while starts are paused.

Move running instances to a new version

Migrate instances already in flight from the faulty version to a corrected one, mapping activity IDs where the structure changed. This is the only option that repairs work in progress, but it is the most sensitive to model changes: removed activities or changed variables can strand instances. Confirm in the Flowable documentation for your release how instance migration is performed, which mappings it supports, and how you test it against a copy of production data before running it.

Restore the database from backup

Return the engine tables to a point before the bad deployment. This removes every change made since that point, including completed work, audit records and history from real users, so it is the most expensive option in data terms and should be a last resort. Confirm your backup frequency and point-in-time recovery for the Flowable schema, whether the restore can be applied to only the affected tables, and how you would replay legitimate transactions made after the restore point.

Security controls for the deployment pipeline

A definition deployed to production changes how a process or case behaves for every running and future instance, so the path from Git to the engine needs the same scrutiny as application code. The cards below cover the risks that matter most when BPMN, CMMN and DMN models leave the repository. Work through them with your security team before the first production deployment, and treat each one as a control you can test.

Who can deploy to production

Decide which people and which pipeline identities may deploy definitions to production, and separate that right from the right to merge model changes. A model that routes approvals or payments is a control change, so require a named approver for production deployments. Check that branch protection and environment approvals in your CI system match this rule, and that service accounts cannot be used interactively.

Engine and API credentials in CI

The pipeline needs credentials for the engine database and for the Flowable REST API, and these are often stored as long-lived CI variables. Hold them in your secrets manager, scope each credential to deployment only, and rotate them on a schedule. Confirm that pipeline logs never print the request body or connection strings, and that the REST default accounts have been changed before any pipeline uses them.

Scripts and XML inside models

BPMN and CMMN files can carry script tasks, expressions and listeners, and a definition with unreviewed scripting can run code inside the engine. Treat every model change that adds scripts, expressions or custom XML elements as a code review item. Ask your Flowable team which scripting options are enabled in your engine and whether the pipeline can reject definitions that use them.

Integrity of deployment artifacts

Build the deployment bundle once, record its checksum, and deploy that exact artifact to staging and production instead of rebuilding it. If you ship Flowable container images, verify their signatures before they run, using the signing key the project publishes. Store the artifact and its hash with the commit it came from, so a reviewer can confirm that production matches the reviewed change.

Separation of staging and production

Give staging and production engines separate databases, separate credentials and separate network paths, so a test deployment cannot write to production tables. Identity sources should differ too, so that test users cannot approve production work. Confirm that promotion from staging is a documented step with the same artifact, not a second build with different settings.

Audit trail of each deployment

Record who deployed which definition version, when, from which commit and to which engine. Flowable keeps deployment and definition records in the engine, but the link to the person who approved the change lives in your pipeline, so keep both. Ask your auditors which evidence they will request, and test that you can produce it for any process version still running.

Questions teams ask before deploying Flowable models from CI/CD

How much effort does a Flowable model deployment pipeline take to build?

Effort depends mainly on how many engines you run, how many BPMN, CMMN and DMN models move through the pipeline, which approval rules apply before production, and how much control you need over database schema changes. A single engine with a handful of models and one environment is a small job. Several engines, separate staging and production databases, and a DBA who must review every schema change add design and testing work. Ask any partner to break the quote into pipeline design, model packaging and validation, environment setup, and handover, so you can see which drivers apply to your case.

Can our internal team build a Flowable deployment pipeline on its own?

Often yes, if the team already runs Java services and CI/CD for them. The work needs someone who understands Flowable's deployment model, how a deployment creates a new process definition version, and how Spring Boot auto-deployment or a business archive reaches the engine. Teams without Flowable experience usually need time to learn the engine's APIs and test behavior. Check whether your engineers can cover the build, the test suite for process models, the database change process and the on-call work after go-live. A partner can fill gaps in any of these, under a written scope.

What does our organization need to provide for the engagement?

Plan to provide four things. First, a Git layout for models, delegates and configuration that your team agrees to keep. Second, access to the target environments, including the database, the CI runner and the deployment target, with the permissions your security policy allows. Third, a named owner for each BPMN, CMMN and DMN model who can approve changes and answer questions about business behavior. Fourth, a decision on who runs schema changes, because some teams require a DBA to apply DDL scripts instead of letting the engine update tables at startup. Write these inputs into the scope before work starts.

How long does a first Flowable deployment pipeline usually take?

A first pipeline usually takes longer than teams expect because it forces decisions about versioning, environment promotion, schema control and testing of models that were previously deployed by hand. The duration depends on the number of engines and environments, the state of your existing models and the approval steps your organization requires. Ask for a timeline tied to milestones in the written scope, such as a working pipeline in one non-production environment, then a production promotion with a rollback procedure tested. Avoid any estimate that is not tied to those inputs.

What happens to running process instances when we deploy a new model version?

In Flowable, a deployment creates a new definition version, and instances already running stay on the version they started with unless you migrate them. New instances start on the latest version. This is why the pipeline should record the version each deployment creates, and why teams need a plan for long-running cases and processes. Check with your Flowable version and your own design whether instances can move to a newer version, and test that move with realistic data before production. Your model owners should decide how in-flight work continues, and that decision belongs in the release process, not in the deployment script.

What rollback options exist if a Flowable model deployment fails?

The main options are redeploying the previous model version from Git, keeping the old definition active for new starts while you fix the new one, and restoring the database from a tested backup if a schema change or data change went wrong. Which option works depends on whether the deployment changed the database schema, which is harder to reverse than a model change. Confirm with your team how rollback is tested, who can trigger it, and how running instances are handled during it. Rollback should be rehearsed before the first production release, not designed during an incident.

Does DeployOpen publish a price for this work?

No. DeployOpen does not publish a price list. A quote follows from a written scope that lists the engines, models, environments, approval rules, schema control and handover you need. Most engagements are fixed-scope, so scope, deliverables and timelines are agreed in writing before work starts. Ongoing support and upgrades can be arranged as a retainer. Ask for a quote that separates one-time pipeline build work from any recurring support you decide to keep.

How DeployOpen scopes and delivers Flowable deployment pipelines

DeployOpen is a Chainscore Labs company that plans, implements, integrates and supports self-hosted open-source platforms inside the client's own infrastructure, including Flowable engines deployed from Git into your cloud accounts, data centers or air-gapped networks. For a CI/CD pipeline that moves BPMN, CMMN and DMN models into production, the work usually covers the Git layout for models, the build step that packages them, the promotion path between environments, the credentials the pipeline uses to reach each engine, and the rollback procedure. Most engagements are fixed-scope, with the models in scope, the pipeline stages, the target environments and the acceptance checks agreed in writing before any work starts.

A written scope is also where the decisions that drive cost get settled. Ask the partner to state which deployment style is in scope (business archives, Spring Boot auto-deployment or the REST application), how many engines and databases the pipeline must reach, whether the pipeline may run DDL against production schemas, and who holds the production credentials. Confirm which versions of Flowable, Java and Spring the work targets, because the Flowable 8.0.0 release notes describe a move to Spring Boot 4 with no backward compatibility for Spring Boot 3. Ask for the acceptance criteria in writing, including how a failed deployment is detected and how a rollback is tested before go-live.

Ongoing support, upgrades and continuous testing are available as retainers, which suits pipelines that will keep changing after the first release. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications; independent auditors and certification bodies do that work. DeployOpen is also not an official partner, reseller or certified provider of Flowable or any vendor. Request a written quote that follows from the agreed scope, and check that it names what is delivered, what the client must provide, and what remains with your own team.

Deploying Flowable process definitions from CI/CD