Skip to content

HOW-TO-RELEASE.md

Latest commit

 

History

History
124 lines (95 loc) · 5.49 KB

HOW-TO-RELEASE.md

File metadata and controls

124 lines (95 loc) · 5.49 KB
Raw

How to Release Coolify CLI

This guide explains the release process for the Coolify CLI.

Prerequisites

  • Write access to the coollabsio/coolify-cli repository
  • All changes merged to the target branch (main)
  • All tests passing (go test ./internal/...)

Release Process

1. Create a GitHub Release

  1. Go to https://github.com/coollabsio/coolify-cli/releases/new
  2. Click "Choose a tag" and create a new tag:
    • Tag name: v1.x.x (must start with v, e.g., v1.2.3)
    • Target: main (or your target branch)
  3. Release title: v1.x.x (same as tag name)
  4. Description: Write release notes describing:
    • New features
    • Bug fixes
    • Breaking changes (if any)
    • Example: 
      ## What's New
- Added support for database management
- Improved error messages for API failures

## Bug Fixes
- Fixed panic when config file is missing

## Breaking Changes
- None
  5. Click "Publish release"

2. Automated Build Process

Once you publish the release:

  1. GitHub Actions automatically triggers the release-cli.yml workflow
  2. GoReleaser builds binaries for:
    • Linux: amd64, arm64
    • macOS (Darwin): amd64, arm64
    • Windows: amd64, arm64
  3. Goreleaser injects the version from the tag into the binaries via ldflags (into internal/version.version)
  4. Binaries are automatically uploaded to the release
  5. A follow-up update-version job then:
    • Updates the version constant in internal/version/checker.go to the new tag
    • Commits the bump to main as chore: bump version to vX.Y.Z
    • Force-moves the release tag to point at that new commit
  6. GoReleaser also publishes a Homebrew formula to the tap at coollabsio/homebrew-coolify-cli (under Formula/coolify-cli.rb), using the HOMEBREW_TAP_GITHUB_TOKEN secret
  7. The release becomes available at:
    • GitHub: https://github.com/coollabsio/coolify-cli/releases/tag/v1.x.x
    • Install script: curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
    • Homebrew: brew install coollabsio/coolify-cli/coolify-cli
    • go install: go install github.com/coollabsio/coolify-cli/coolify@v1.x.x

3. Verify the Release

After the workflow completes (usually 2-5 minutes), verify without touching your local install:

  1. Check the release page has all platform binaries (Linux/macOS/Windows × amd64/arm64)
  2. Confirm the update-version job committed the bump on main (look for chore: bump version to vX.Y.Z) and that the tag now points at that commit
  3. Confirm internal/version/checker.go on main has the new version
  4. Confirm the Homebrew tap has a new Formula/coolify-cli.rb commit for this version at https://github.com/coollabsio/homebrew-coolify-cli

Troubleshooting

Build Failed

Version Not Updating

  • The version is injected at build time via ldflags into internal/version.version — you do not need to edit it manually before releasing. The post-release update-version job also rewrites internal/version/checker.go on main.
  • If the hardcoded fallback in internal/version/checker.go is stale, check that the update-version job ran successfully after the release.
  • The tag must start with v (e.g., v1.2.3, not 1.2.3)
  • Check that the workflow has write permissions (contents: write in release-cli.yml)

Install Script Not Finding New Version

  • Wait a few minutes for GitHub's CDN to update
  • Check that binaries were uploaded to the release
  • Verify the tag format is correct (v1.x.x)

Release Checklist

Before creating a release:

  • All tests pass: go test ./internal/...
  • Code is formatted: go fmt ./...
  • Changes merged to main branch
  • Release notes prepared

Note: You do not need to bump the version manually. GoReleaser injects the tag version via ldflags, and the update-version CI job commits the bump to internal/version/checker.go after the release.

After creating a release:

  • GitHub Actions workflow completed successfully (both release-cli and update-version jobs)
  • All platform binaries are present on the release page
  • internal/version/checker.go on main shows the new version
  • Homebrew tap has a fresh Formula/coolify-cli.rb commit

Configuration Files

The release process uses these configuration files:

  • .goreleaser.yml - GoReleaser configuration (build matrix, archives, Homebrew tap) - entry point is ./coolify/main.go
  • .github/workflows/release-cli.yml - GitHub Actions workflow
  • scripts/install.sh - User-facing install script
  • internal/version/checker.go - Contains GetVersion() function that returns the current version
  • coolify/main.go - Binary entry point for go install support
  • coollabsio/homebrew-coolify-cli - External Homebrew tap updated automatically on each release

Notes

  • The CLI has auto-update checking built-in (checks every 10 minutes)
  • Users can manually update with coolify update
  • Install script supports version pinning: bash install.sh v1.2.3
  • Homebrew users can install via brew install coollabsio/coolify-cli/coolify-cli (the tap at https://github.com/coollabsio/homebrew-coolify-cli is auto-updated by GoReleaser)
  • Releases are immutable - if you need to fix something, create a new patch version