CLI Release Workflow
Contents
- Sources Of Truth
- Choose The Path
- Changeset Rule
- Inspect Candidates
- Build A Manual Beta
- Promote A Beta To Stable
- Verify Completion
- Failure Recovery
Sources Of Truth
.github/workflows/build-cli-binaries.ymlowns beta and stable GitHub Releases..github/scripts/cli-release/resolve-release-target.shdecides the tag and source commit..github/scripts/cli-release/verify-assets.shdefines the required asset set..github/workflows/cli.test-installation.ymlvalidates installers after publication..changeset/config.jsonignores@composio/cli.
sdk.release.yml owns stable and beta Python/TypeScript publication from next; ts.release.yml retains the 1.0 prerelease train on main. CLI binary releases use their own workflow.
Choose The Path
| Goal | Path | Result |
|---|---|---|
| Ship an ordinary CLI change | Merge the reviewed PR to next |
The push builds a rolling beta automatically. |
| Build a beta from a branch | Dispatch build-beta at that branch |
A prerelease is built from the branch commit. |
| Publish a stable CLI | Dispatch promotion at an existing tested beta tag | The beta's source commit is rebuilt and published under the stable tag. |
| Resume a failed promotion | Re-run or re-dispatch the same beta after inspecting the draft | An unpublished draft can be resumed and its assets replaced. |
The private CLI package.json uses a development sentinel and never selects a
binary version. If a release owner needs an intentional minor or major version,
dispatch an explicitly versioned beta, verify it, and promote that exact beta.
Changeset Rule
Never create a .changeset/*.md entry for @composio/cli while it remains in .changeset/config.json#ignore.
An ignored-package changeset makes changesets/action enter version-PR mode, while changeset version emits no commit. The action then fails with No commits between next and changeset-release/next and blocks unrelated SDK publishing.
If a CLI change needs a human-facing note, update ts/packages/cli/CHANGELOG.md directly. Run this guard before handoff:
pnpm validate:changesetsInspect Candidates
Use live GitHub state. Do not select a beta from local tags or remembered versions.
REPOSITORY=ComposioHQ/composio
gh release list \
--repo "$REPOSITORY" \
--limit 100 \
--json tagName,isPrerelease,isDraft,publishedAt \
--jq '.[] | select(.tagName | startswith("@composio/cli@")) | select(.isPrerelease and (.isDraft | not))'For the chosen candidate, require a published prerelease and inspect its commit and assets:
BETA_TAG='@composio/cli@0.0.0-beta.000'
gh release view "$BETA_TAG" \
--repo "$REPOSITORY" \
--json tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets \
--jq '{tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets:[.assets[] | {name,state}]}'The beta must have isDraft: false, isPrerelease: true, and these seven assets in uploaded state:
composio-linux-x64.zipcomposio-linux-aarch64.zipcomposio-darwin-x64.zipcomposio-darwin-aarch64.zipcomposio-windows-x64.zip(experimental: absent when theWindows x64job failed, which does not block the release)composio-skill.zipchecksums.txt
Find the beta workflow run by its target commit and require it to be green, including the reusable installation-test jobs:
TARGET_COMMIT='replace-with-targetCommitish'
gh run list \
--repo "$REPOSITORY" \
--workflow build-cli-binaries.yml \
--commit "$TARGET_COMMIT" \
--limit 10If the user asked for a stable release without naming a beta, show the candidate and stop for confirmation before dispatching.
Build A Manual Beta
Use this only when an explicit beta build is requested. The selected ref
supplies both the workflow definition and source commit. Omit version for the
normal next-patch beta, or provide an exact major.minor.patch base for an
intentional minor or major release.
SOURCE_BRANCH='replace-with-branch'
gh workflow run build-cli-binaries.yml \
--repo "$REPOSITORY" \
--ref "$SOURCE_BRANCH" \
--raw-field action=build-betaFor an intentional minor or major, add a version newer than the latest stable:
gh workflow run build-cli-binaries.yml \
--repo "$REPOSITORY" \
--ref "$SOURCE_BRANCH" \
--raw-field action=build-beta \
--raw-field version=0.3.0Watch the returned run through publication and installation tests. A beta is not a stable release.
Promote A Beta To Stable
Derive the stable tag by removing the beta suffix, then ensure no published stable release already exists:
STABLE_TAG="${BETA_TAG%%-beta.*}"
gh release view "$STABLE_TAG" --repo "$REPOSITORY" --json tagName,isDraft,isPrerelease,publishedAt- If the stable tag is absent, promotion may proceed.
- If it is a draft, the promotion can resume it.
- If it is already published, stop. Never overwrite a published release.
Dispatch the workflow at the beta tag. The selected ref supplies the immutable source commit, and the workflow verifies that it matches the beta release before rebuilding:
gh workflow run build-cli-binaries.yml \
--repo "$REPOSITORY" \
--ref "$BETA_TAG" \
--raw-field action=promote-stableUse the returned URL when available. Otherwise identify the new dispatch, verify its creation time and actor, then watch it:
gh run list \
--repo "$REPOSITORY" \
--workflow build-cli-binaries.yml \
--event workflow_dispatch \
--commit "$TARGET_COMMIT" \
--limit 5
gh run watch RUN_ID --repo "$REPOSITORY" --compact --exit-statusVerify Completion
Do not call the release complete until all of these are true:
Build CLI Binariescompleted successfully.- The stable release is published with
isDraft: falseandisPrerelease: false. - All seven canonical assets are present and uploaded, or six when the experimental
Windows x64job failed. - The workflow's installation-test matrix passed.
gh release view "$STABLE_TAG" \
--repo "$REPOSITORY" \
--json tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets \
--jq '{tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets:[.assets[] | {name,state}]}'Report the stable tag, promoted beta, target commit, workflow URL, asset count and state, and installation result.
Failure Recovery
- Build matrix failed: no release should publish. Fix the source, produce a new beta, and promote that candidate.
- Draft exists, publish did not finish: inspect the failure, then re-run or re-dispatch the same beta. Draft assets are safely replaced with
--clobber. - Duplicate run says the release is already published: this is an intentional safety failure. Verify the published release and stop the duplicate.
- Installation failed after publication: do not mutate the published tag. Fix forward through a new beta and the next stable patch.
- TS release says there are no commits for the release PR: remove any pending Changeset that targets an ignored CLI package, preserve its note in the CLI changelog, run
pnpm validate:changesets, and let the next push retry the SDK release train.