spring-kafka: Spring's wrapper around the Kafka clients

What the project is wrapping

The repository describes itself in one line, and the line is accurate: it provides familiar Spring abstractions for Apache Kafka. The distinction that matters is that Spring Kafka is not a Kafka implementation and not a broker. It is a layer that lets a Spring application treat Kafka topics and consumer groups the way it treats any other managed resource, with container startup, shutdown ordering and configuration handled by the framework.

The scale of the project is worth noting against that description. It has 2,512 stars and 1,764 forks, which is an unusually high fork count relative to stars and is consistent with a library that teams vendor, patch and track closely. There are 41 open issues at the moment of writing, and commits were landing as recently as September 2026, so this is active work rather than a maintained-but-frozen artifact.

The build is Gradle, and the checkout and build sequence is the one you would expect from a Spring project of this size:

git clone git://github.com/spring-projects/spring-kafka.git
cd spring-kafka
./gradlew build

The README states that Java 17 or later is recommended for building, and that is a recommendation about the build rather than about the runtime floor your application needs. There are separate targets for the things you normally want from a Spring project repository: ./gradlew install puts the jars in your local Maven cache, ./gradlew api generates API Javadoc into build/api, and ./gradlew antora builds the reference documentation into spring-kafka-docs/build/site.

Two build files at the repository root tell you more about the project's shape than the README does. publish-maven.gradle handles publication, and commercial-settings.gradle sits beside it, which is the build configuration that supports commercial offerings associated with the Spring ecosystem. The presence of a dedicated commercial settings file means the build is aware of more than one distribution channel.

Module layout for a multi-module Spring library

The repository root is a Gradle multi-project build, and the directory names are the clearest description of what the project ships.

spring-kafka/ is the library itself. spring-kafka-bom/ is a bill of materials module, which is the piece that lets a consumer import a single coordinate and get a consistent set of versions across the Spring Kafka modules rather than pinning each one. spring-kafka-test/ is the test support module, the part you use when you write tests that exercise Kafka consumers and producers. spring-kafka-docs/ holds the documentation build.

The samples/ directory is the part most worth reading first, and its numbering is deliberate. samples/README.adoc sits at the top and the tree shows sample-01/ through sample-08/ beneath it. Numbered and cumulative samples are how the Spring projects teach a feature incrementally, and the samples README is the index that tells you which numbered sample covers which capability.

The root also carries an AGENTS.md and a CLAUDE.md. Those two files are conventionally read by automated coding assistants during contribution, and their presence tells you the project has formalized how it wants machine-assisted contributions handled. That is unusual enough to be worth knowing before you open a pull request, because it is the project's own statement of the rules rather than something inferred from history.

The reference documentation is published separately at the Spring Kafka site, linked from the README as the reference manual, and the project metadata points its homepage at projects.spring.io/spring-kafka. Both are maintained outside this repository, which is the normal arrangement for a Spring project: this repository holds code, and the site holds the manual.

Milestones are the version markers here

The published releases tell you where the line is going. The three most recent are v4.2.0-M1 on 2026-08-20, v4.1.1 on the same day, and v4.2.0-M2 on 2026-09-24. Two of those three are milestones rather than general availability releases, and the naming is the standard Spring convention where an M suffix marks a pre-release of an upcoming minor version.

What that means in practice is that the highest tag in the repository is not the version most conservative users should adopt. v4.2.0-M2 is the leading edge of the 4.2 line. v4.1.1 is the last non-milestone tag in the visible history, and it is the safer choice if you want a maintenance release rather than a preview of the next minor version.

The milestone release notes are where the substance is. The v4.2.0-M2 notes list concrete changes rather than theme summaries: allowing KafkaAdmin to be configured on AbstractKafkaListenerContainerFactory, applying nullability annotations to Deserializer and Serializer subclasses, and an async annotation on listener containers. Nullability annotation work on serializer and deserializer subclasses is the kind of change that only matters to you if you have nullability enforcement enabled in your build, which is exactly the sort of thing milestone notes are for.

One limitation of what can be seen from outside: the release list available for this project is a sample of recent entries, so treat the three versions above as the recent tail rather than as the complete release history. For a definitive list of everything between your current version and the one you are considering, the changelog attached to each tag is the authoritative source, not the tag list.

The contributor guide has an ASF leftover in it

This is the most concrete inconsistency in the repository, and it is worth describing precisely rather than rounding off.

The code conventions section instructs contributors to add the ASF license header comment to all new .java files, and to copy it from existing files in the project. ASF is the Apache Software Foundation, the organization behind the Apache Kafka project itself. Spring Kafka is a Spring project hosted in the spring-projects organisation, not an Apache Software Foundation project, and no ASF header appears in the files the README points you to.

Both facts are current and they are not compatible as instructions. The instruction is a leftover from a template shared across projects, and it will not produce a correct header if followed literally. The rule that actually governs the code is the License section at the end of the README, which states that Spring Kafka is released under the terms of the Apache Software License Version 2.0.

There is a second small discrepancy in the same area, and it is the kind that makes people doubt themselves rather than the repository. The License section links to the license text with link text reading LICENSE.txt, and the actual file in the repository root is LICENCE.txt, with the British spelling. On a case-insensitive filesystem this is invisible, which is probably why it survived. On Linux and in raw repository browsing the two names differ, and the link text is the one that is wrong.

Neither of these affects the code you run. Both affect how much you should trust the surrounding prose, and the practical response is the same one to apply to any contributor document: when the prose and the repository disagree, the repository is the fact.

Contribution rules that are stricter than they look

Beyond the conventions, the README states two contribution requirements that determine whether a pull request can be merged at all.

The first is the Developer Certificate of Origin. Every commit must carry a Signed-off-by trailer, and the README links a blog post explaining the change from a CLA to the DCO. The distinction matters in practice: a DCO does not grant commit rights, but signing it means the project can accept the contribution and give you author credit. Projects that run a CLA require a separate legal agreement before a single line can be merged, and this one does not.

The second is how the project describes its own workflow. It says GitHub is for social coding, meaning issues, discussion and votes, and that code should arrive as pull requests from forks. Active contributors may be invited to join the core team and given merge rights. That is the standard shape for a project at this maturity level: open contribution with a small group holding merge permission.

The remaining conventions are advisory and the README says so directly, noting that none of them is essential but that all of them help. Use the Spring Framework code format, with an eclipse-code-formatter.xml at the repository root if you are working in Eclipse. Give new .java files a Javadoc class comment with an @author tag. Add yourself as an @author to files you change substantially, where substantially means more than cosmetic. Add Javadoc, and if you change the namespace, XSD doc elements as well. And the one most often skipped: a few unit tests, with the README's own acknowledgement that someone has to do it.

For support rather than contribution, the README points at the spring-kafka tag on Stack Overflow and asks for a minimal reproducible example, and it notes that commercial support is available through Spring.

Metadata that is thinner than the project

A few repository metadata details are worth knowing because tooling reads them and humans assume them.

The repository carries no topics at all. For a project with this many stars, topics are how GitHub surfaces related projects, and their absence means search-based discovery depends on the name matching. It also means topic-driven feeds and dashboards see nothing here, which is a small disadvantage for anyone tracking the Spring ecosystem by topic rather than by watching list.

The description is a single short sentence, and it is a good one, but it does not mention that the project ships a bill of materials, a test support module or a documentation module. If you are searching for a Kafka integration for Spring and comparing candidates by their descriptions, this one undersells itself relative to what the module layout delivers.

The build badge tells you the project publishes scans through Develocity, the Gradle Enterprise product, and the badge links to a scans page. For a library this widely depended on, that is useful rather than promotional, because scan results across a build give maintainers a view of which configurations are actually exercised.

The continuity of the repository itself is the strongest signal available. The licence is Apache 2.0, consistent with what the README states, and the code of conduct, security policy and contribution guide are all linked to the shared spring-projects organisation rather than duplicated locally. That is deliberate: the policies live in one place and this repository points at them.

Editorial conclusion

Spring Kafka earns its place when your application is already a Spring application, because the value it adds is not Kafka functionality but Spring integration: listener containers that participate in the application context, configuration properties that bind with the same mechanism as everything else, and an administration surface that fits into an existing Spring deployment. Read it with two facts in hand. The public version markers in this repository are milestones, so v4.2.0-M2 tells you the 4.2 line is in progress while v4.1.1 is what a conservative adopter would take, and the changelog for each milestone is where you look for behaviour changes. And the contributor guide contains an instruction to add an ASF license header, which is the wrong foundation for a Spring project and is a leftover you should ignore; the Apache 2.0 grant itself is stated correctly and is what actually governs the code. If you are outside Spring, the abstraction buys you less, and the raw clients are a smaller thing to learn.

Frequently asked questions

Official sources

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