API Releases

This document outlines the standard process for releasing Unkey's main artifact (the API) as binaries and containers.

Overview

At Unkey, we use Git tags to trigger our release process. When a tag is pushed to the main branch, a GitHub Action automatically builds the binary and Docker image, pushes the Docker image to GitHub Container Registry (ghcr.io), and creates a GitHub release.

It's important to note that creating a release does not automatically deploy code. Deployments are handled manually as a separate process.

Release Process

Prerequisites

• Ensure all changes you want to include in the release are merged into the main branch
• Verify that all automated tests have passed on the PRs that were merged

Creating a Release

1. Determine the appropriate version number following Semantic Versioning principles:

   • Major version (X.0.0): Incompatible API changes
   • Minor version (X.Y.0): Backwards-compatible functionality additions
   • Patch version (X.Y.Z): Backwards-compatible bug fixes

2. Create and push a Git tag:

   git checkout main
   git pull
   git tag vX.Y.Z  # Example: v2.0.1
   git push --tags

3. The GitHub Action workflow will automatically trigger when the tag is pushed to main

4. Once completed, a GitHub release will be created with automatically generated release notes and a message will be posted to #releases in slack.

Creating a Prerelease

For testing changes before an official release, you can create a prerelease using a canary tag:

1. Follow the same process as a standard release, but use a prerelease tag format:

   git checkout main
   git pull
   git tag vX.Y.Z-canary.N  # Example: v2.0.1-canary.0
   git push --tags

2. The GitHub Action workflow will recognize this as a prerelease and mark it accordingly on GitHub

3. Prereleases are useful for testing changes in a production-like environment without affecting stable releases

Release Artifacts

Each release produces:

• Binary files for multiple platforms
• Docker image pushed to GitHub Container Registry (ghcr.io)
• GitHub release with automatically generated release notes

Deploying a Release

Deployment is currently a manual process separate from the release workflow. Please refer to the deployment documentation for details on how to deploy a released version.

Emergency Fixes

We currently don't have a formalized process for emergency fixes or hotfixes. When critical issues are discovered in production, coordinate with the team to determine the best approach for addressing the issue.

Responsibilities

All team members share responsibility in the release process and can create releases when necessary.

Best Practices

1. Communicate releases to the team before creating a new tag
2. Review changes included in the release before tagging
3. Monitor systems after deployment to catch any issues early
4. Document significant changes in PR descriptions to ensure clear release notes