Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

ci: simplify CLI binary release workflow (#3121)

Rahul Tarak12ef3d3a5051
diff --git a/.claude/skills/cli-release/SKILL.md b/.claude/skills/cli-release/SKILL.md
index 261dd244d..67ff541ee 100644
--- a/.claude/skills/cli-release/SKILL.md
+++ b/.claude/skills/cli-release/SKILL.md
@@ -6,6 +6,15 @@ description: Release the CLI — diff features since last release, run /full-cli
Orchestrates a CLI release by identifying what changed since the last release, testing those changes via `/full-cli-test`, and creating a changeset PR with a patch version bump.
+## Background: Release Flow
+
+The CLI uses a two-channel release system:
+
+- **Beta (automatic):** Every push to `next` touching `ts/packages/cli/**` auto-builds binaries and creates a `@composio/[email protected].<run>` prerelease. Also triggerable on any branch via `workflow_dispatch` → `build-beta`.
+- **Stable (via changeset):** Merge a changeset PR → changeset bot creates "Release: update version" PR → merge that → `package.json` version changes → workflow detects the change and creates a stable release.
+
+This skill handles the **changeset PR** side: identifying changes, testing, and opening the PR that kicks off the stable release pipeline.
+
## Overview
Two workstreams run **in parallel**:
@@ -17,19 +26,18 @@ Once testing completes, update the PR description with test results.
## Step 1: Identify Changes Since Last Release
-Find the last release tag or version bump commit for `@composio/cli`:
+Find the last stable release tag for `@composio/cli`:
```bash
-# Find the last release commit (look for "Release: update version" commits that touched the CLI)
-git log --oneline --all -- ts/packages/cli/package.json | head -20
+# Find the latest stable CLI release
+gh release list --json tagName,isPrerelease --jq '[.[] | select(.tagName | startswith("@composio/cli@")) | select(.isPrerelease == false)] | last | .tagName'
```
-Look for the most recent commit where the CLI version was bumped (typically a "Release: update version" commit). Use that as the base.
-
-Then collect all commits between that base and HEAD that touch the CLI:
+Find the commit for that tag, then collect all commits between it and HEAD that touch the CLI:
```bash
-git log <base_commit>..HEAD --oneline -- ts/packages/cli/
+git log --oneline -1 <tag> # get the base commit
+git log <base>..HEAD --oneline -- ts/packages/cli/
```
For each commit, read the commit message and understand what it does. Categorize changes as:
@@ -51,6 +59,14 @@ Run the `/full-cli-test` skill. This executes:
2. **Phase 2:** Local binary build and test (including Slack integration test)
3. **Phase 3:** Bundled binary build and test via CI (including Slack integration test)
+For Phase 3, trigger a beta build via `workflow_dispatch` → `build-beta` on the current branch:
+
+```bash
+gh workflow run build-cli-binaries.yml --ref <branch> -f action=build-beta
+```
+
+Then monitor the run, download the built binary artifact, and test it.
+
Track the results of each phase — you'll need them for the PR description.
## Step 3: Create Changeset PR (Parallel Track 2)
@@ -183,6 +199,7 @@ gh pr ready <PR_NUMBER> --undo # Convert to draft
- **The changeset file format is strict:** YAML frontmatter with package name in quotes and bump type, then a blank line, then the description.
- **Feature-specific testing:** When identifying changes in Step 1, note any new commands or flags. During testing (Step 2), explicitly test those new features with the built binary beyond the standard test suite.
- **The PR targets `next`** — this is the main development branch.
+- **Beta builds are automatic.** Every push to `next` touching CLI files creates a beta. The changeset PR is only needed to trigger the stable release pipeline.
## Reference Files
@@ -190,5 +207,6 @@ gh pr ready <PR_NUMBER> --undo # Convert to draft
|---|---|
| `ts/packages/cli/package.json` | Current CLI version |
| `.changeset/config.json` | Changeset configuration |
-| `.github/workflows/build-cli-binaries.yml` | CI binary build workflow |
+| `.github/workflows/build-cli-binaries.yml` | CI binary build + release workflow |
+| `.github/workflows/ts.release.yml` | Changeset bot + npm publish |
| `ts/packages/cli/src/commands/` | CLI command implementations |
diff --git a/.github/workflows/build-cli-binaries.yml b/.github/workflows/build-cli-binaries.yml
index eaf14ca77..126c37c94 100644
--- a/.github/workflows/build-cli-binaries.yml
+++ b/.github/workflows/build-cli-binaries.yml
@@ -1,14 +1,22 @@
name: Build CLI Binaries
on:
- pull_request:
+ push:
branches: [next]
- types: [opened, synchronize, reopened]
+ paths:
+ - 'ts/packages/cli/**'
workflow_dispatch:
inputs:
+ action:
+ description: 'What to do'
+ type: choice
+ options:
+ - build-beta
+ - promote-stable
+ default: build-beta
beta_tag:
- description: 'Existing beta release tag to promote (e.g., @composio/[email protected])'
- required: true
+ description: 'Existing beta release tag to promote (only for promote-stable, e.g. @composio/[email protected])'
+ required: false
permissions:
contents: write
@@ -16,7 +24,6 @@ permissions:
jobs:
prepare:
name: Resolve Release Metadata
- if: "${{ github.event_name == 'workflow_dispatch' || github.event.pull_request.title == 'Release: update version' }}"
runs-on: ubuntu-latest
outputs:
checkout_ref: ${{ steps.resolve.outputs.checkout_ref }}
@@ -27,44 +34,115 @@ jobs:
make_latest: ${{ steps.resolve.outputs.make_latest }}
steps:
- - name: Checkout release PR head
- if: github.event_name == 'pull_request'
+ - name: Checkout
uses: actions/checkout@v6
with:
- ref: ${{ github.event.pull_request.head.sha }}
+ ref: ${{ github.sha }}
- - name: Resolve beta or stable release target
+ - name: Resolve release target
id: resolve
env:
EVENT_NAME: ${{ github.event_name }}
- PR_NUMBER: ${{ github.event.pull_request.number }}
- PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+ ACTION_INPUT: ${{ inputs.action }}
BETA_TAG_INPUT: ${{ inputs.beta_tag }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
REPOSITORY: ${{ github.repository }}
+ RUN_NUMBER: ${{ github.run_number }}
+ COMMIT_SHA: ${{ github.sha }}
run: |
set -euo pipefail
- if [[ "$EVENT_NAME" == "pull_request" ]]; then
- version=$(node -p "require('./ts/packages/cli/package.json').version")
- if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
- echo "Expected ts/packages/cli/package.json version to be a stable semver on the release PR, got: $version"
- exit 1
+ # ── Push to next ──
+ if [[ "$EVENT_NAME" == "push" ]]; then
+ # Check if ts/packages/cli/package.json version changed → stable release
+ current_version=$(node -p "require('./ts/packages/cli/package.json').version")
+ previous_version=$(git show HEAD^:ts/packages/cli/package.json 2>/dev/null | node -p "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).version" 2>/dev/null || echo "")
+
+ if [[ -n "$previous_version" && "$current_version" != "$previous_version" ]]; then
+ release_tag="@composio/cli@${current_version}"
+ release_name="CLI ${release_tag}"
+ {
+ echo "checkout_ref=${COMMIT_SHA}"
+ echo "release_name=${release_name}"
+ echo "release_tag=${release_tag}"
+ echo "release_version=${current_version}"
+ echo "prerelease=false"
+ echo "make_latest=true"
+ } >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
+
+ # Otherwise → beta release
+ # Find the latest stable CLI release to determine next version
+ latest_stable_tag=$(gh release list \
+ --repo "$REPOSITORY" \
+ --json tagName,isPrerelease \
+ --jq '[.[] | select(.tagName | startswith("@composio/cli@")) | select(.isPrerelease == false)] | sort_by(.tagName) | last | .tagName // empty')
+
+ if [[ -z "$latest_stable_tag" ]]; then
+ echo "No stable @composio/cli release found, falling back to package.json"
+ current_version=$(node -p "require('./ts/packages/cli/package.json').version")
+ else
+ current_version=$(echo "$latest_stable_tag" | sed 's/@composio\/cli@//')
fi
- release_tag="@composio/cli@${version}-beta.${PR_NUMBER}"
+ # Bump patch version for the beta
+ IFS='.' read -r major minor patch <<< "$current_version"
+ next_version="${major}.${minor}.$((patch + 1))"
+
+ release_tag="@composio/cli@${next_version}-beta.${RUN_NUMBER}"
release_name="CLI Beta ${release_tag}"
{
- echo "checkout_ref=${PR_HEAD_SHA}"
+ echo "checkout_ref=${COMMIT_SHA}"
echo "release_name=${release_name}"
echo "release_tag=${release_tag}"
- echo "release_version=${version}"
+ echo "release_version=${next_version}"
echo "prerelease=true"
echo "make_latest=false"
} >> "$GITHUB_OUTPUT"
exit 0
fi
+ # ── workflow_dispatch: build-beta ──
+ if [[ "$EVENT_NAME" == "workflow_dispatch" ]] && [[ "$ACTION_INPUT" == "build-beta" ]]; then
+ latest_stable_tag=$(gh release list \
+ --repo "$REPOSITORY" \
+ --json tagName,isPrerelease \
+ --jq '[.[] | select(.tagName | startswith("@composio/cli@")) | select(.isPrerelease == false)] | sort_by(.tagName) | last | .tagName // empty')
+
+ if [[ -z "$latest_stable_tag" ]]; then
+ current_version=$(node -p "require('./ts/packages/cli/package.json').version")
+ else
+ current_version=$(echo "$latest_stable_tag" | sed 's/@composio\/cli@//')
+ fi
+
+ IFS='.' read -r major minor patch <<< "$current_version"
+ next_version="${major}.${minor}.$((patch + 1))"
+
+ release_tag="@composio/cli@${next_version}-beta.${RUN_NUMBER}"
+ release_name="CLI Beta ${release_tag}"
+ {
+ echo "checkout_ref=${COMMIT_SHA}"
+ echo "release_name=${release_name}"
+ echo "release_tag=${release_tag}"
+ echo "release_version=${next_version}"
+ echo "prerelease=true"
+ echo "make_latest=false"
+ } >> "$GITHUB_OUTPUT"
+ exit 0
+ fi
+
+ # ── Promote stable (workflow_dispatch with promote-stable) ──
+ if [[ "$ACTION_INPUT" != "promote-stable" ]]; then
+ echo "Unknown action: $ACTION_INPUT"
+ exit 1
+ fi
+
+ if [[ -z "$BETA_TAG_INPUT" ]]; then
+ echo "beta_tag input is required for promote-stable"
+ exit 1
+ fi
+
encoded_beta_tag=$(python3 -c 'import os, urllib.parse; print(urllib.parse.quote(os.environ["BETA_TAG_INPUT"], safe=""))')
release_json=$(curl -fsSL \
@@ -79,7 +157,7 @@ jobs:
fi
if [[ ! "$BETA_TAG_INPUT" =~ ^@composio/cli@([0-9]+\.[0-9]+\.[0-9]+)-beta\.[0-9]+$ ]]; then
- echo "Beta tag must match @composio/cli@<version>-beta.<pr-number>"
+ echo "Beta tag must match @composio/cli@<version>-beta.<number>"
exit 1
fi
diff --git a/ts/packages/cli/AGENTS.md b/ts/packages/cli/AGENTS.md
index 8c8f384e2..a842947ff 100644
--- a/ts/packages/cli/AGENTS.md
+++ b/ts/packages/cli/AGENTS.md
@@ -27,16 +27,16 @@ Errors are captured via the custom `effect-errors/` module, which provides sourc
Each command is declared with `@effect/cli`'s `Command.make()` pattern:
-| Command | Description |
-| -------------------------------------------------------- | ---------------------------------------------------------- |
-| `composio version` | Display CLI version |
-| `composio whoami` | Show logged-in user's API key |
-| `composio login [--no-browser] [--no-wait] [--key text]` | Login with browser redirect |
-| `composio logout` | Clear stored API key |
-| `composio upgrade` | Self-update binary from GitHub releases |
-| `composio generate` | Auto-detect project language, delegate to `ts` or `py` |
-| `composio generate ts` | Generate TypeScript type stubs for toolkits/tools/triggers |
-| `composio generate py` | Generate Python type stubs |
+| Command | Description |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `composio version` | Display CLI version |
+| `composio whoami` | Show logged-in user's API key |
+| `composio login [--no-browser] [--no-wait] [--key text]` | Login with browser redirect |
+| `composio logout` | Clear stored API key |
+| `composio upgrade` | Self-update binary from GitHub releases |
+| `composio generate` | Auto-detect project language, delegate to `ts` or `py` |
+| `composio generate ts` | Generate TypeScript type stubs for toolkits/tools/triggers |
+| `composio generate py` | Generate Python type stubs |
| `composio manage <command>` | Manage Composio resources (toolkits, tools, accounts, triggers, logs, orgs, projects) |
Options use `Options.text()`, `Options.boolean()`, `Options.choice()`, `Options.directory()` with Effect Schema validation.
@@ -335,3 +335,45 @@ recordings/
- **Config**: `recordings/recordings.yaml`
- **Script**: `scripts/record.ts` — Bun + Effect.ts, parallel VHS execution
- **Shared tape**: `recordings/tapes/shared-config.tape` — common VHS settings (auto-generated)
+
+---
+
+## Release Workflow
+
+CLI releases use a two-channel system: **beta** (automatic) and **stable** (manual promotion).
+
+### Beta Releases (automatic)
+
+Every push to `next` that touches `ts/packages/cli/**` automatically triggers `.github/workflows/build-cli-binaries.yml`, which:
+
+1. Finds the latest stable `@composio/[email protected]` release
+2. Computes the next patch version (`X.Y.Z+1`)
+3. Builds cross-platform binaries (linux-x64, linux-aarch64, darwin-x64, darwin-aarch64)
+4. Creates a GitHub prerelease tagged `@composio/[email protected].(Z+1)-beta.<run_number>`
+
+You can also trigger a beta build from **any branch** via `workflow_dispatch` → `build-beta`.
+
+Users install beta releases with `composio upgrade --beta`.
+
+### Stable Releases (via changeset)
+
+To promote to a stable release:
+
+1. Create a changeset PR (`.changeset/<name>.md` with `"@composio/cli": patch`)
+2. Merge it into `next`
+3. The changeset bot creates a "Release: update version" PR that bumps `package.json`
+4. Merge that PR → the push to `next` detects the `package.json` version changed → builds a **stable** release (`@composio/[email protected]`, marked as `latest`)
+5. `ts.release.yml` also publishes to npm
+
+### Manual Promotion
+
+You can also promote an existing beta to stable via `workflow_dispatch` → `promote-stable` with the beta tag (e.g. `@composio/[email protected]`).
+
+### Key Files
+
+| File | Purpose |
+| --------------------------------------------- | -------------------------------- |
+| `.github/workflows/build-cli-binaries.yml` | Binary build + release workflow |
+| `.github/workflows/ts.release.yml` | Changeset bot + npm publish |
+| `.github/workflows/cli.test-installation.yml` | Post-release install smoke tests |
+| `.changeset/config.json` | Changeset configuration |