Keycloak is using GitHub Actions to automate the release of Keycloak. The release workflows do not live in the main repositories, but rather in a separate repository:
The reason for this is to be able to sandbox the release from the regular day to day development of Keycloak, including job queues and secrets.
In addition there is a fork of the above repository that is used for testing purposes:
The testing fork allows testing releases without affecting regular releases as it uses different credentials and repositories.
- Announce Release: Announces the release, which is currently limited to updating the website
- Branch - Create Release: Creates new release branches in all relevant repositories
- Branch - Delete Release: Deletes release branches when they are no longer needed
- Re-spin Containers: Used to re-spin containers to update the base images without an actual Keycloak release
- Release: Performs a regular Keycloak release
- Release Nightly: Performs a nightly scratch release
- Sync forks: Only used in testing fork to sync forked repositories
- X ...: Workflows prefixed with X are reusable workflows, called by other workflows and should not be executed directly
Nightly releases are scheduled to run every night, but can also be started manually.
To manually run a nightly release:
- Navigate to the
Release Nightlyworkflow - Click on
Run workflow - Use workflow from:
Branch: main - Click on
Run workflow
Regular releases are manually started, and should be done from release branches rather than from the main branches.
If you are releasing a new major/minor version (for example 19.0.0 and not 19.0.1) the first step is to create the release branches:
- Navigate to the
Branch - Create Releaseworkflow - Click on
Run workflow - Use workflow from:
Branch: main - Enter the major.minor version (for example if you are releasing
19.0.0enter19.0) - Click on
Run workflow
If you are doing a micro release (for example 19.0.1, and not 19.0.0) the above step is skipped as it has already been done previously for 19.0.
Next step is to do the actual release:
- Navigate to the
Releaseworkflow - Click on
Run workflow - Use workflow from:
Branch: <release branch>(for exampleBranch: 19.0) - branch:
<release branch> - version:
<full version>(for example19.0.0) - Click on
Run workflow
After the release has completed and it has been verified the release should be announced:
- Navigate to the
Announce Releaseworkflow - Click on
Run workflow - Use workflow from:
Branch: <release branch>(for exampleBranch: 19.0) - version:
<full version>(for example19.0.0) - Click on
Run workflow
Changes to the release process should not be sent directly to the main release repository, but rather to the testing fork first. This allows testing/verifying the changes prior to updating the actual release process.
First step to contributing to the release process is to get a branch created in the testing fork for your proposed changes. This allows testing your changes without affecting other changes.
After the branch is created you can send your PR to the branch, and both the Release and Release Nightly workflows should be executed against your branch to verify it.
Once the changes have been tested a PR can be opened against the main branch in the testing fork.
Final step is syncing changes from the testing fork to the main release repository through a PR. This is generally not a step that you need to perform as a contributor, but rather a maintainer of the release process will coordinate this last step.
Anyone that would like to make bigger changes to the release process, or are maintainers of certain parts of the release process get full access to the keycloak-rel-testing organization, but do not everyone gets access to the [main release organization](keycloak-rel-testing. The latter is intentionally very limited in the number of people that gets access to it.
Tag name is {version} (for example 19.0.0), or nightly for nightly releases.
| Repo | Main | Test |
|---|---|---|
| keycloak | https://github.com/keycloak/keycloak | https://github.com/keycloak-rel-testing/keycloak |
| keycloak-quickstarts | https://github.com/keycloak/keycloak-quickstarts | https://github.com/keycloak-rel-testing/keycloak-quickstarts |
Release name is {version} (for example 19.0.0), or nightly for nightly releases.
| Repo | Main | Test |
|---|---|---|
| keycloak | https://github.com/keycloak/keycloak/releases | https://github.com/keycloak-rel-testing/keycloak/releases |
Nightly releases uses 999.0.0-SNAPSHOT version. Maven artifacts are currently published to GitHub Packages for test releases, but plan is to stop doing this and only upload to GitHub releases.
NPM artifacts are uploaded to GitHub releases for the corresponding repository, and published to npm.js for non-test releases.
| Main | Test |
|---|---|
| https://www.npmjs.com/ | Not published |
Nightly release uses nightly tag.
| Main | Test |
|---|---|
| https://github.com/keycloak/keycloak-k8s-resources | https://github.com/keycloak-rel-testing/keycloak-k8s-resources |
Main releases are published to https//www.keycloak.org as repositories are updated. Nightly or test releases are not published anywhere.
| Repo | Main | Test |
|---|---|---|
| keycloak-web | https://github.com/keycloak/keycloak-web | https://github.com/keycloak-rel-testing/keycloak-web |
| keycloak.github.io | https://github.com/keycloak/keycloak.github.io | https://github.com/keycloak-rel-testing/keycloak.github.io |