Activiti: the BPMN engine where the documentation is mostly IDE settings

Two release trains shipping on the same afternoon

Activiti has 10538 stars, 6909 forks and 606 open issues, and the release list explains the shape of the project better than any documentation would. On September 21st, 2026 the repository published `9.1.0-alpha.76` at 05:19 UTC and then `7.21.0-rc.608` at 14:03 UTC and `7.21.0-rc.609` at 16:18 UTC. Three releases in a single day, on two version lines, is the single most informative fact in the release history.

The 7.x line is where the visible work is. The rc.608 notes list a bug fix for estimating the serialized JSON size of a Java object without allocating large string objects, a Dependabot bump of the github-actions group across 2 directories with 4 updates, an update of the Supply Chain Review GitHub App Workflow, adding actionlint to the pre-commit config, and implementing the preview propagation mechanism itself. That last one is worth reading twice, because it is infrastructure for the repository rather than for users.

The 9.1.0 alpha line publishes release notes that are empty bodies. So the honest reading is that 9.x is a moving target with no written change history in the releases list, while 7.x has a per-change narrative. If you are picking a version on the strength of documented behaviour alone, 7.21.0 is the line with a readable trail.

The preview propagation mechanism tests merges before they land

The most interesting feature in the README is not about BPMN at all. Activiti publishes an automated preview propagation mechanism for testing cross module integration with downstream repositories like activiti-cloud, and the workflow for a feature that spans multiple modules is four steps long.

1. Add labels `preview` + `preview-propagation` to your PR
2. The system automatically builds a preview version and creates a test PR in activiti-cloud
3. Test the integration in the downstream PR
4. When your source PR closes/merges, the test PR automatically closes

The stated benefit is that it eliminates manual version bumping and cleanup while ensuring integration changes are validated before merge. In practice this is a private dependency graph made visible: a pull request here does not finish its review here, it finishes when the downstream repository has compiled against it and the downstream pull request closes.

That is the clearest signal in the repository about how the project is actually organised. Activiti is not a standalone engine any more. It is the upstream half of a multi repository platform, with activiti-cloud consuming the artifacts, and the version alignment between the two is handled by automation rather than by a human bumping a property file.

Module layout tells you what is API and what is engine

The tree at the root is a Maven multi module project, and the directories split along a clean line. `activiti-api/` holds the interfaces, `activiti-core/` is the engine, `activiti-core-common/` is shared code between cores, `activiti-dependencies/` is the dependency management project, `activiti-dependency-check/` is the security scanning of those dependencies, and `activiti-examples/` holds runnable examples. Alongside them sit `checkstyle-rules.xml`, `settings.xml`, `.pre-commit-config.yaml`, `.semgrep.yaml`, `.prettierrc.cjs`, `.editorconfig` and an `ide-configuration/` directory that contains the IntelliJ settings the README spends most of its length telling you to import.

That ratio is worth pausing on. The engine source is spread across three modules and the contributor configuration is spread across seven files, and the README devotes most of its text to the second group. There is also `activiti7.png` at the root, an image that suggests this README was carried over from the 7.x era.

For someone deciding whether to adopt the project, the practical consequence is that the API surface is small and separate. If you only need to embed the engine, `activiti-api` is the module your code should compile against, and the coupling to the engine internals lives behind that boundary.

The README is a contributor onboarding checklist, not user documentation

Read the README as a whole and it becomes clear that its job is getting a contributor's IDE into compliance. The instructions are specific and, in places, opinionated to a degree that says something about the maintainers. Force language level 21 to fail fast when accidentally using features available only in newer Java versions. Change the Resource patterns field to `!?*.java` so resource changes are not ignored on the next run. Add `-J-Xss1024k` to avoid a `StackOverflowError` when building. Import the Google Java Style scheme, set tab size 4 and indent 4 for Java with continuation indent 8, tab size 2 and indent 2 for XML with continuation indent 4, and set the line separator for new files to `Unix`.

The file encoding rules are the part that trips people up. Global encoding should be `UTF-8`, but the default encoding for properties files should be `ISO-8859-1`, with the reason given inline: normal i18n properties files must be in `ISO-8859-1` as specified by the java `ResourceBundle` contract.

The file header rules are a culture statement. The instructions say to remove the line `@author Your Name` and to remove the entire javadoc as automatically templated data is meaningless, and the FAQ entry underneath explains why `@author` lines are not accepted in source files. The project's own argument is that authorship information in the repository makes the author tags in the source code pointless.

So if you are looking for deployment guidance, engine configuration, or how to wire a process into a Spring application, the README does not have it. It links out to a GitBook at activiti.gitbooks.io for the 7.x developers guide and to activiti.org as the homepage, and those two links are where the engine documentation actually lives.

BPMN 2, Apache licensed, and running on develop by default

The project's own description is a useful starting point and also a good example of marketing prose: Activiti calls itself a light-weight workflow and Business Process Management platform targeted at business people, developers and system admins, with a super-fast and rock-solid BPMN 2 process engine for Java at its core, distributed under the Apache license, running in any Java application on a server, on a cluster or in the cloud, and integrating perfectly with Spring. Every one of those claims is checkable in some form, and the ones that matter for an evaluation are the BPMN 2 conformance, the Apache 2.0 licence, and the Spring integration.

The default branch is `develop`, which tells you the intended workflow: develop is where the next major version is designed and coded, and there is a note in the README saying that the content of the development branch was moved to master, with 6.x contributions directed to the 6.x branch. The topics list adds `microservices` and `cloud` alongside the expected `bpm`, `bpmn`, `business-process` and `java`.

One repository detail deserves a mention because it is unusual. There is a `.jx/` directory at the root, along with `.pre-commit-config.yaml` and a `.prettierrc.cjs`, and release notes record that actionlint was added to the pre-commit configuration. A Java engine repository running prettier alongside checkstyle is a signal about how much frontend adjacent tooling the project has absorbed.

What the repository does not tell you

There are no code samples in the README, and there is no installation section, no engine API reference, and no migration guide between 7.x and 9.x. The examples directory exists in the tree but the release notes never mention it, so the only way to see a running process is to build `activiti-examples` yourself and read the source.

The 606 open issues against a 10538 star repository is also worth reading as a signal. For a project of that size and age, that is a moderate ratio rather than a sign of neglect, especially with release candidates being cut three times in a day. But there is no CHANGELOG file in the tree, only generated release bodies, which means the history you would want for a version decision lives in GitHub releases and in the 7.x developers guide rather than in the checkout.

What the repository does document well is how to work on it. Set the IntelliJ language level to 21 so newer language features fail fast, set tab size 4 and indent 4 for Java with continuation indent 8, set tab size 2 and indent 2 for XML with continuation indent 4, and import the Alfresco Software copyright profile from `ide-configuration/` so file headers match what checkstyle expects. That is a well maintained project. It just maintains its build environment with more care than its onboarding docs.

Editorial conclusion

Activiti is a mature engine with a live maintenance culture that shows up in the tooling rather than in the README narrative. The build enforces Google Java Style through checkstyle, prettier, editorconfig, semgrep and actionlint in pre-commit, and it refuses `@author` tags because the authorship lives in git history instead. For a new integration, the module split is the thing to understand, since `activiti-core` holds the engine while `activiti-api` holds the interfaces, and the 9.1.0 alpha train is where the next generation of that structure is landing while 7.21.0 release candidates keep shipping on the same day. Start with `activiti-examples`, then read the 7.x developers guide, because the repository itself documents almost nothing about deploying a process.

Frequently asked questions

Official sources

1. Activiti/Activiti on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases