An open-source, self-hostable PaaS alternative to Vercel, Heroku & Netlify that lets you easily deploy static sites, databases, full-stack applications and 360+ one-click services on your own servers.
PHP coolifydatabasesdeploymentdockerdocker-composeinertiajslaravelmariadbmysqlnextjsnodejsphppostgresredisself-hostedself-hostingserverstatic-sitesveltesvelte5
docs(release): document SHA image promotion workflow
Andras Bacsai24bc4b046218
diff --git a/RELEASE.md b/RELEASE.mdindex bc159b0409..1df585fc58 100644--- a/RELEASE.md+++ b/RELEASE.md@@ -15,20 +15,35 @@ This guide outlines the release process for Coolify, intended for developers and## Release Process-1. **Development on `next` or Feature Branches**- - Improvements, fixes, and new features are developed on the `next` branch or separate feature branches.--2. **Merging to `main`**- - Once ready, changes are merged from the `next` branch into the `main` branch (via a pull request).--3. **Building the Release**- - After merging to `main`, GitHub Actions automatically builds release images for all architectures and pushes them to the GitHub Container Registry and Docker Hub with the specific version tag and the `latest` tag.--4. **Creating a GitHub Release**- - A new GitHub release is manually created with details of the changes made in the version.--5. **Updating the CDN**- - To make a new version publicly available, the version information on the CDN needs to be updated manually. After that the new version number will be available at [https://cdn.coollabs.io/coolify/versions.json](https://cdn.coollabs.io/coolify/versions.json).+1. **Prepare the Release**+ - Develop changes on `next` or feature branches.+ - Set the release version in `config/constants.php` and `versions.json`. Both values must match the planned Git tag without the `v` prefix (for example, `4.2.0` for tag `v4.2.0`).+ - Verify the changelog and required tests before merging.++2. **Build the Release Commit**+ - Merge the release commit into `v4.x` through a pull request.+ - The `Production Build (v4)` workflow builds AMD64 and ARM64 images and publishes them to Docker Hub and GHCR using immutable architecture tags.+ - After both builds complete, the workflow creates the multi-architecture `sha-<commit-sha>` manifest in both registries.+ - This workflow does not update a semantic version tag or `latest`.++3. **Wait for the SHA Image**+ - Confirm the complete `Production Build (v4)` workflow, including its `merge-manifest` job, succeeded.+ - Do not publish the release before the multi-architecture SHA image exists in both registries.++4. **Create and Publish the GitHub Release**+ - Create a GitHub release with a semantic version tag such as `v4.2.0`, targeting the exact commit that produced the SHA image.+ - Mark beta or other test releases as prereleases. Publish production versions as stable releases.+ - Publishing the release starts the `Release Coolify` workflow. It verifies that the Git tag matches `config/constants.php`, then promotes the existing SHA image without rebuilding it.+ - The workflow assigns the semantic version tag in Docker Hub and GHCR. Stable releases also update `latest`; prereleases do not.++5. **Verify the Promotion**+ - Confirm the `Release Coolify` workflow succeeded.+ - Verify the semantic version image has the same manifest digest as `sha-<commit-sha>` in Docker Hub and GHCR.+ - For stable releases, also verify `latest` points to the promoted release manifest.++6. **Update the CDN**+ - To make a new version available to self-hosted instances, update the version information on the CDN manually.+ - Confirm the new version is available at [https://cdn.coollabs.io/coolify/versions.json](https://cdn.coollabs.io/coolify/versions.json).> [!NOTE]> The CDN update may not occur immediately after the GitHub release. It can take hours or even days due to additional testing, stability checks, or potential hotfixes. **The update becomes available only after the CDN is updated. After the CDN is updated, a discord announcement will be made in the Production Release channel.**@@ -36,7 +51,7 @@ This guide outlines the release process for Coolify, intended for developers and## Version Types<details>- <summary><strong>Stable (coming soon)</strong></summary>+ <summary><strong>Stable</strong></summary>- **Stable**- The production version suitable for stable, production environments (recommended).diff --git a/tests/Unit/ProductionImageWorkflowTest.php b/tests/Unit/ProductionImageWorkflowTest.phpindex 06085a33f4..557e86b64e 100644--- a/tests/Unit/ProductionImageWorkflowTest.php+++ b/tests/Unit/ProductionImageWorkflowTest.php@@ -32,3 +32,15 @@ it('only promotes stable releases to latest', function () {->toContain('if: ${{ ! github.event.release.prerelease }}')->toContain('--tag "${IMAGE}:latest"');});++it('documents the sha image release process', function () {+ $releaseGuide = file_get_contents(dirname(__DIR__, 2).'/RELEASE.md');++ expect($releaseGuide)+ ->toContain('Merge the release commit into `v4.x`')+ ->toContain('`sha-<commit-sha>`')+ ->toContain('targeting the exact commit that produced the SHA image')+ ->toContain('promotes the existing SHA image without rebuilding it')+ ->toContain('Update the CDN')+ ->not->toContain('Merging to `main`');+});