Keycloak uses SemVer versioning (<major>.<minor>.<patch>) with an exception that important bug and security fixes might break backwards compatibility.
The latest release and links to archived releases are available at https://www.keycloak.org/downloads.
- Minor releases are released approximately 4 times per year. They include new features, enhancements, and bug fixes.
- Major releases occur every 2-3 years.
- Patch releases are made as needed to address critical bugs and security vulnerabilities.
For future release dates, refer to the milestones in the GitHub repository.
The project publishes nightly builds.
Refer to https://www.keycloak.org/nightly/ for downloads.
Keycloak aims to deliver new features and enhancements in a backwards compatible way, making it seamless and easy to upgrade. However, there are certain limitations:
- Important bug fixes and security fixes might introduce non-opt-in breaking changes in any release.
- The aim for minor releases is to allow a seamless upgrade by making breaking changes opt-in. This should allow gradual roll out of feature changes and breaking changes.
- Major releases may introduce breaking changes that are not opt-in, and remove previously deprecated features or API versions.
- Backwards compatibility guarantees apply to supported features and APIs only. Preview and experimental features, as well as non-public APIs, may change at any time. See the Feature Lifecycle section below.
As any release can contain breaking changes or change internal behavior or APIs, users should consult the upgrading guide and conduct testing in a test environment before upgrading to any release.
Security fixes are released as patch releases for the latest minor release. Security advisories are published in the release notes and GitHub issues of type CVE.
In the GitHub repository, the following branching and tagging strategy is used:
- Development happens on the
mainbranch. - Each minor release is tagged from
mainor from a release branch. - After a minor release, a
release/<major>.<minor>branch is created for subsequent patch releases. - Patch releases are tagged from the corresponding release branch.
- Tags use the format
<major>.<minor>.<patch>(novprefix).
The latest minor release receives patch releases for critical bugs and security vulnerabilities. When a new minor release is published, the previous minor release is no longer supported.
Once a new major release is published, the last minor release of the previous major version receives 6 months of patch releases.
Users are expected to upgrade to each new minor release to continue receiving support.
New capabilities in Keycloak follow a graduated lifecycle:
- Experimental - available for evaluation, not yet feature complete
- Preview - feature complete but not ready for production use yet. Seamless upgrades are not guaranteed
- Supported - fully supported with backwards compatibility and migration guarantees
For full details on expectations at each level see docs/features.md.
Client libraries (Admin Client, Authorization Client, JavaScript adapter) are released separately from the server. The latest client library release supports all currently supported Keycloak server releases.
Each Keycloak release publishes the following artifacts:
| Artifact | Repository / Registry |
|---|---|
| Server distribution (tar.gz, zip) | GitHub Releases, Downloads page |
| Container image | quay.io/keycloak/keycloak |
| Operator | quay.io/keycloak/keycloak-operator, OperatorHub |
| Kubernetes resources | keycloak/keycloak-k8s-resources |
| Maven artifacts (client libraries, SPIs) | Maven Central |
| Release notes | Keycloak website |
| Upgrade guide | Keycloak website |
The release is announced via the following channels: