Releasing

OpenCRVS follows a structured and coordinated release process to ensure stability and alignment between the core platform and country-specific configurations. Releases are versioned semantically (e.g., v1.4.0). Each release is accompanied by migration notes, upgrade instructions, and full changelogs to support system integrators and implementers.

Initializing a Release

Create the release pull request

The first step in launching a new release is to create the release pull request. To do so, execute the GitHub Action titled Release - Start a new release available in the opencrvs-core repository.

To trigger this action, you are required to provide only the release version.

⚠️ Caution

  • Ensure that the version number adheres to semantic versioning (e.g., 1.6.1).

  • For a minor release, the release branch will be created from develop branch.

  • For a hotfix release, make sure that the branch corresponding to the previous release exists in the core, countryconfig, and farajaland repositories. If it does not exist, create it first—otherwise, the workflow will fail. (e.g., If you are creating a hotfix release for version 1.6.2, ensure that the release/1.6.1 branch already exists.)

Once triggered, the action performs the following steps automatically:

  • Creates a release branch following the naming convention: release/{version_number} (e.g., release/1.6.1).

  • Opens a pull request to begin the release process.

  • Updates CHANGELOG.md heading with the specified version number.

  • Modifies all package.json files across the repository to reflect the new version.

  • Creates a draft release for core and countryconfig.

Deployment to a Release Environment

You can deploy a draft release to a dedicated release environment by running the Release - Create Environment workflow. This workflow requires two input parameters:

  • Select the branch from which you want to run the workflow.

  • Core image tag: The Docker image tag for, core that you want to deploy.

⚠️ Caution Make sure to run the workflow from the corresponding release branch.

Once triggered, this workflow will:

  • Create a server for the release environment

  • Provision the environment

  • Deploy the release environment

This provides a fully functional environment for validating and reviewing the release.

Publishing the Release

During this phase, it's common for issues to be discovered or additional pull requests to be merged into the release branch. Proceed carefully and ensure all necessary changes are included.

⚠️ Caution Before proceeding to the next steps, make sure there are no open pull requests that need to be included in the release—this applies to both the countryconfig and core repositories.

1. Publish Docker Images to Container Registry

You can publish all Docker images to our container registry by running the Publish Release workflow in the opencrvs-core repository. For opencrvs-countryconfig you can publish all Docker images through Publish image to Dockerhub workflow.

💡 This step ensures that all release-related images are built and made available in the appropriate container registry.

2. Tag the Release

Create a Git tag from the HEAD of the release branch. For example, to tag version 1.7.0, run:

git tag v1.7.0
git push origin tag v1.7.0

⚠️ Caution Before creating a new Git tag, confirm that a tag with the same version number does not already exist in either the countryconfig or core repositories.

3. Verify Docker Images

  • ✅ Verify that the Docker images have been published to the appropriate registry:

  • Compare the size of the new images with those from the previous release.

  • If there is a significant difference in size, report it to the maintainers for investigation.

⚠️ Caution Check Docker Hub (or the GitHub Container Registry for versions post 1.7.0 in core) to confirm that Docker images have been built and published using the correct release version name.

4. Finalize GitHub Release

  • Copy the content from CHANGELOG.md into the GitHub Release notes.

  • Paste any changed "Copy" items into the release notes. You can generate these with this tool.

  • Once finalized, publish the GitHub release.

5. Publish NPM Release

  • In the core repository, ensure that the corresponding NPM package is published to reflect the new version.

6. Version Control Management

  • In both the core and countryconfig repositories, merge the release branch into master. ⚠️ Do not squash merge — use a regular merge to preserve history.

  • Also merge the release branch back into the develop branch after the release is finalized to keep develop up to date with the latest changes.

7. Documentation Management

  • Add the new release notes to the official documentation.

  • Create a placeholder for the next version's documentation.

  • Update OpenAPI specification URLs to point to the new release branch.

  • Publish the updated documentation.

  • Merge any open pull requests in the documentation repository, if appropriate.

8. Environment Management

  • Merge the latest countryconfig updates into your country-specific repository.

  • For minor releases: Deploy the new version to production.

  • For hotfix releases: Deploy the new version to staging.

9. Team Communication

  • Announce the newly published version to your team and stakeholders, ensuring they are informed and aligned.

10. Post Verification Steps

  • Confirm GitHub release publication After publishing the GitHub release, open the repository’s Releases tab and verify that the release is publicly available and correctly labeled.

  • Verify NPM package publication (core only) For the core repository, ensure the NPM release has been published successfully. You can confirm this by checking for the presence of the corresponding version under the @opencrvs/toolkit package on NPM.

By following this structured checklist, you ensure a smooth, transparent, and high-quality release process.

PreviousWorkflows

Last updated