Skip to content

upgrade.md

Latest commit

 

History

History
87 lines (56 loc) · 2.84 KB

upgrade.md

File metadata and controls

87 lines (56 loc) · 2.84 KB

Upgrade

The upgrade module adds a CLI command that updates the current binary from GitHub Releases.

Overview

This module provides in-place upgrades for applications that publish release assets to GitHub. It:

  • Resolves the target release (latest or --version)
  • Downloads the asset matching the current OS/architecture
  • Swaps the executable in-place using .new/.old files
  • Logs a no-op when the target version is equal or lower (unless --force)

Requirements

  • App source: util.AppSource must be a GitHub repository URL like https://github.com/{org}/{repo}.
  • Semver tags: Release tags must be semantic versions (for example v1.2.3).
  • Semver build: The current build version must also be semantic (used for comparisons).
  • Asset naming: Releases must include a zip asset named:
    • ${AppKey}_${version}_${GOOS}_${GOARCH}.zip
  • Zip contents: The zip file must contain a single binary (no nested folders or extra files).
  • Permissions: The process needs write access to the installed binary location.

Usage

CLI

# Upgrade to the latest release
./your-app upgrade

# Upgrade to a specific version (leading "v" is optional)
./your-app upgrade --version 1.2.3

# Force upgrade even if the target version is older or equal
./your-app upgrade --force

Flags

  • --version - Release tag or version number to upgrade to (for example 1.2.3 or v1.2.3)
  • --force, -f - Upgrade even if the target version is equal or lower than the current build

Examples

Targeting a Specific Release

./myapp upgrade --version v1.2.3

Configuration

Environment Variables

  • GITHUB_TOKEN (or github_token) - Optional GitHub token for authenticated API access and private repos

Application Metadata

The module relies on application constants generated by Project Forge:

  • AppSource - GitHub repository URL used to resolve releases
  • AppKey - Used to match release asset names

These are defined in app/util/keys.go in the generated application.

CLI and URLs

  • CLI: upgrade (available in the application command set)
  • GitHub Releases: https://github.com/{org}/{repo}/releases

Troubleshooting

  • 404 or "can't access repository": Confirm AppSource is a valid GitHub URL.
  • "no asset available": Ensure asset names match ${AppKey}_${version}_${GOOS}_${GOARCH}.zip.
  • Permission errors: Run the upgrade command with permissions to replace the binary.

Source Code

See Also