hookdeck · leggetter · Nov 3, 2025 · Oct 21, 2025 · Oct 21, 2025 · Nov 3, 2025
diff --git a/.goreleaser/linux.yml b/.goreleaser/linux.yml
@@ -29,6 +29,9 @@ builds:
       - linux
     goarch:
       - arm64
+release:
+  prerelease: auto
+  mode: append
 changelog:
   sort: asc
   filters:
@@ -40,12 +43,15 @@ checksum:
 snapshot:
   name_template: "{{ .Tag }}-next"
 nfpms:
-  - builds:
+  - package_name: "{{ if .Prerelease }}hookdeck-beta{{ else }}hookdeck{{ end }}"
+    file_name_template: "{{ .PackageName }}_{{ .Version }}_{{ .Arch }}"
+    builds:
       - hookdeck-linux
     vendor: Hookdeck
     homepage: https://hookdeck.com
     maintainer: Hookdeck <[email protected]>
-    description: Hookdeck CLI utility
+    description: |-
+      Hookdeck CLI utility{{ if .Prerelease }} (Beta){{ end }}
     license: Apache 2.0
     formats:
       - deb

diff --git a/.goreleaser/mac.yml b/.goreleaser/mac.yml
@@ -28,6 +28,9 @@ builds:
       - darwin
     goarch:
       - arm64
+release:
+  prerelease: auto
+  mode: append
 changelog:
   sort: asc
   filters:
@@ -46,7 +49,7 @@ archives:
       - README*
       - CHANGELOG*
 brews:
-  - name: hookdeck
+  - name: "{{ if .Prerelease }}hookdeck-beta{{ else }}hookdeck{{ end }}"
     ids:
       - hookdeck
     repository:
@@ -65,6 +68,10 @@ brews:
 
     caveats: |
       ❤ Thanks for installing the Hookdeck CLI!
+      {{ if .Prerelease }}
+      ⚠️  You are using a BETA version. Report issues at:
+        https://github.com/hookdeck/hookdeck-cli/issues
+      {{ end }}
 
       If this is your first time using the CLI, run:
         hookdeck login

diff --git a/.goreleaser/windows.yml b/.goreleaser/windows.yml
@@ -24,6 +24,9 @@ builds:
 archives:
   - files:
       - none*
+release:
+  prerelease: auto
+  mode: append
 changelog:
   sort: asc
   filters:

diff --git a/README.md b/README.md
@@ -29,6 +29,12 @@ Hookdeck CLI is distributed as an NPM package:
 npm install hookdeck-cli -g
 ```
 
+To install a beta (pre-release) version:
+
+```sh
+npm install hookdeck-cli@beta -g
+```
+
 ### macOS
 
 Hookdeck CLI is available on macOS via [Homebrew](https://brew.sh/):
@@ -37,6 +43,12 @@ Hookdeck CLI is available on macOS via [Homebrew](https://brew.sh/):
 brew install hookdeck/hookdeck/hookdeck
 ```
 
+To install a beta (pre-release) version:
+
+```sh
+brew install hookdeck/hookdeck/hookdeck-beta
+```
+
 ### Windows
 
 Hookdeck CLI is available on Windows via the [Scoop](https://scoop.sh/) package manager:
@@ -46,6 +58,12 @@ scoop bucket add hookdeck https://github.com/hookdeck/scoop-hookdeck-cli.git
 scoop install hookdeck
 ```
 
+To install a beta (pre-release) version:
+
+```sh
+scoop install hookdeck-beta
+```
+
 ### Linux Or without package managers
 
 To install the Hookdeck CLI on Linux without a package manager:
@@ -54,6 +72,8 @@ To install the Hookdeck CLI on Linux without a package manager:
 2. Unzip the file: tar -xvf hookdeck_X.X.X_linux_amd64.tar.gz
 3. Run the executable: ./hookdeck
 
+For beta (pre-release) versions, download the `.deb` or `.rpm` packages from the [GitHub releases page](https://github.com/hookdeck/hookdeck-cli/releases) (look for releases marked as "Pre-release").
+
 ### Docker
 
 The CLI is also available as a Docker image: [`hookdeck/hookdeck-cli`](https://hub.docker.com/r/hookdeck/hookdeck-cli).
@@ -63,6 +83,14 @@ docker run --rm -it hookdeck/hookdeck-cli version
 hookdeck version x.y.z (beta)
 ```
 
+To use a specific version (including beta releases), specify the version tag:
+
+```sh
+docker run --rm -it hookdeck/hookdeck-cli:v1.2.3-beta.1 version
+```
+
+Note: Beta releases do not update the `latest` tag. Only stable releases update `latest`.
+
 If you want to login to your Hookdeck account with the CLI and persist
 credentials, you can bind mount the `~/.config/hookdeck` directory:
 
@@ -643,6 +671,90 @@ docker run --rm -it \
     http://host.docker.internal:1234
 ```
 
+## Releasing
+
+This section describes the branching strategy and release process for the Hookdeck CLI.
+
+### Branching Strategy
+
+The project uses two primary branches:
+
+- **`main`** - The stable, production-ready branch. All production releases are created from this branch.
+- **`next`** - The beta/pre-release branch. All new features are merged here first for testing before being promoted to `main`.
+
+### Beta Releases
+
+Beta releases allow you to publish pre-release versions for testing without blocking the `main` branch or affecting stable releases.
+
+**Process:**
+
+1. Ensure all desired features are merged into the `next` branch
+2. Pull the latest changes locally:
+   ```sh
+   git checkout next
+   git pull origin next
+   ```
+3. Create and push a beta tag with a pre-release identifier:
+   ```sh
+   git tag v1.2.3-beta.0
+   git push origin v1.2.3-beta.0
+   ```
+4. The GitHub Actions workflow will automatically:
+   - Build binaries for all platforms (macOS, Linux, Windows)
+   - Create a GitHub pre-release (marked as "Pre-release")
+   - Publish to NPM with the `beta` tag
+   - Create beta packages:
+     - Homebrew: `hookdeck-beta` formula
+     - Scoop: `hookdeck-beta` package
+     - Docker: Tagged with the version (e.g., `v1.2.3-beta.0`), but not `latest`
+
+**Installing beta releases:**
+
+```sh
+# NPM
+npm install hookdeck-cli@beta -g
+
+# Homebrew
+brew install hookdeck/hookdeck/hookdeck-beta
+
+# Scoop
+scoop install hookdeck-beta
+
+# Docker
+docker run hookdeck/hookdeck-cli:v1.2.3-beta.0 version
+```
+
+### Production Releases
+
+Production releases are created from the `main` branch using GitHub's release interface.
+
+**Process:**
+
+1. Merge the `next` branch into `main`:
+   ```sh
+   git checkout main
+   git pull origin main
+   git merge next
+   git push origin main
+   ```
+2. Go to the [GitHub Releases page](https://github.com/hookdeck/hookdeck-cli/releases)
+3. Click "Draft a new release"
+4. Create a new tag with a stable version (e.g., `v1.3.0`)
+5. Target the `main` branch
+6. Generate release notes or write them manually
+7. Publish the release
+
+The GitHub Actions workflow will automatically:
+- Build binaries for all platforms
+- Create a stable GitHub release
+- Publish to NPM with the `latest` tag
+- Update package managers:
+  - Homebrew: `hookdeck` formula
+  - Scoop: `hookdeck` package
+  - Docker: Updates both the version tag and `latest`
+
+**Note:** Only stable releases (without pre-release identifiers) will update the `latest` tags across all distribution channels.
+
 ## License
 
 Copyright (c) Hookdeck. All rights reserved.