1
+# CLI Release Workflow
2
+
3
+## Contents
4
+
5
+- [Sources Of Truth](#sources-of-truth)
6
+- [Choose The Path](#choose-the-path)
7
+- [Changeset Rule](#changeset-rule)
8
+- [Inspect Candidates](#inspect-candidates)
9
+- [Build A Manual Beta](#build-a-manual-beta)
10
+- [Promote A Beta To Stable](#promote-a-beta-to-stable)
11
+- [Verify Completion](#verify-completion)
12
+- [Failure Recovery](#failure-recovery)
13
+
14
+## Sources Of Truth
15
+
16
+- `.github/workflows/build-cli-binaries.yml` owns beta and stable GitHub Releases.
17
+- `.github/scripts/cli-release/resolve-release-target.sh` decides the tag and source commit.
18
+- `.github/scripts/cli-release/verify-assets.sh` defines the required asset set.
19
+- `.github/workflows/cli.test-installation.yml` validates installers after publication.
20
+- `.github/workflows/cli.bump-homebrew-tap.yml` updates Homebrew for stable releases.
21
+- `.changeset/config.json` ignores `@composio/cli` and `@composio/cli-local-tools`.
22
+
23
+`ts.release.yml` is the TypeScript SDK/npm release train. It is not the normal CLI binary release path.
24
+
25
+## Choose The Path
26
+
27
+| Goal | Path | Result |
28
+| --- | --- | --- |
29
+| Ship an ordinary CLI change | Merge the reviewed PR to `next` | The push builds a rolling beta automatically. |
30
+| Build a beta from a branch | Dispatch `build-beta` at that branch | A prerelease is built from the branch commit. |
31
+| Publish a stable CLI | Promote an existing tested beta | The beta's source commit is rebuilt and published under the stable tag. |
32
+| 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. |
33
+
34
+The resolver also treats a CLI `package.json` version change pushed to `next` as a stable release. Do not use that as the normal contributor procedure. It bypasses beta selection and is reserved for explicit release-owner recovery or migration work.
35
+
36
+## Changeset Rule
37
+
38
+Never create a `.changeset/*.md` entry for `@composio/cli` or `@composio/cli-local-tools` while those packages remain in `.changeset/config.json#ignore`.
39
+
40
+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.
41
+
42
+If a CLI change needs a human-facing note, update `ts/packages/cli/CHANGELOG.md` directly. Run this guard before handoff:
43
+
44
+```bash
45
+pnpm validate:changesets
46
+```
47
+
48
+## Inspect Candidates
49
+
50
+Use live GitHub state. Do not select a beta from local tags or remembered versions.
51
+
52
+```bash
53
+REPOSITORY=ComposioHQ/composio
54
+
55
+gh release list \
56
+ --repo "$REPOSITORY" \
57
+ --limit 100 \
58
+ --json tagName,isPrerelease,isDraft,publishedAt \
59
+ --jq '.[] | select(.tagName | startswith("@composio/cli@")) | select(.isPrerelease and (.isDraft | not))'
60
+```
61
+
62
+For the chosen candidate, require a published prerelease and inspect its commit and assets:
63
+
64
+```bash
65
+BETA_TAG='@composio/cli@0.0.0-beta.000'
66
+
67
+gh release view "$BETA_TAG" \
68
+ --repo "$REPOSITORY" \
69
+ --json tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets \
70
+ --jq '{tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets:[.assets[] | {name,state}]}'
71
+```
72
+
73
+The beta must have `isDraft: false`, `isPrerelease: true`, and these six assets in `uploaded` state:
74
+
75
+- `composio-linux-x64.zip`
76
+- `composio-linux-aarch64.zip`
77
+- `composio-darwin-x64.zip`
78
+- `composio-darwin-aarch64.zip`
79
+- `composio-skill.zip`
80
+- `checksums.txt`
81
+
82
+Find the beta workflow run by its target commit and require it to be green, including the reusable installation-test jobs:
83
+
84
+```bash
85
+TARGET_COMMIT='replace-with-targetCommitish'
86
+
87
+gh run list \
88
+ --repo "$REPOSITORY" \
89
+ --workflow build-cli-binaries.yml \
90
+ --commit "$TARGET_COMMIT" \
91
+ --limit 10
92
+```
93
+
94
+If the user asked for a stable release without naming a beta, show the candidate and stop for confirmation before dispatching.
95
+
96
+## Build A Manual Beta
97
+
98
+Use this only when an explicit beta build is requested. The selected ref supplies both the workflow definition and source commit.
99
+
100
+```bash
101
+SOURCE_BRANCH='replace-with-branch'
102
+
103
+gh workflow run build-cli-binaries.yml \
104
+ --repo "$REPOSITORY" \
105
+ --ref "$SOURCE_BRANCH" \
106
+ --raw-field action=build-beta
107
+```
108
+
109
+Watch the returned run through publication and installation tests. A beta is not a stable release and does not update Homebrew.
110
+
111
+## Promote A Beta To Stable
112
+
113
+Derive the stable tag by removing the beta suffix, then ensure no published stable release already exists:
114
+
115
+```bash
116
+STABLE_TAG="${BETA_TAG%%-beta.*}"
117
+
118
+gh release view "$STABLE_TAG" --repo "$REPOSITORY" --json tagName,isDraft,isPrerelease,publishedAt
119
+```
120
+
121
+- If the stable tag is absent, promotion may proceed.
122
+- If it is a draft, the promotion can resume it.
123
+- If it is already published, stop. Never overwrite a published release.
124
+
125
+Dispatch the current workflow from `next`; `promote-stable` resolves the source commit from the beta release itself:
126
+
127
+```bash
128
+gh workflow run build-cli-binaries.yml \
129
+ --repo "$REPOSITORY" \
130
+ --ref next \
131
+ --raw-field action=promote-stable \
132
+ --raw-field beta_tag="$BETA_TAG"
133
+```
134
+
135
+Use the returned URL when available. Otherwise identify the new dispatch, verify its creation time and actor, then watch it:
136
+
137
+```bash
138
+gh run list \
139
+ --repo "$REPOSITORY" \
140
+ --workflow build-cli-binaries.yml \
141
+ --event workflow_dispatch \
142
+ --branch next \
143
+ --limit 5
144
+
145
+gh run watch RUN_ID --repo "$REPOSITORY" --compact --exit-status
146
+```
147
+
148
+## Verify Completion
149
+
150
+Do not call the release complete until all of these are true:
151
+
152
+1. `Build CLI Binaries` completed successfully.
153
+2. The stable release is published with `isDraft: false` and `isPrerelease: false`.
154
+3. All six canonical assets are present and uploaded.
155
+4. The workflow's installation-test matrix passed.
156
+5. `Bump Homebrew Tap` succeeded or reported that the formula was already current.
157
+
158
+```bash
159
+gh release view "$STABLE_TAG" \
160
+ --repo "$REPOSITORY" \
161
+ --json tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets \
162
+ --jq '{tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets:[.assets[] | {name,state}]}'
163
+
164
+gh run list \
165
+ --repo "$REPOSITORY" \
166
+ --workflow cli.bump-homebrew-tap.yml \
167
+ --event release \
168
+ --limit 5
169
+```
170
+
171
+Report the stable tag, promoted beta, target commit, workflow URL, asset count and state, installation result, and Homebrew result.
172
+
173
+## Failure Recovery
174
+
175
+- **Build matrix failed:** no release should publish. Fix the source, produce a new beta, and promote that candidate.
176
+- **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`.
177
+- **Duplicate run says the release is already published:** this is an intentional safety failure. Verify the published release and stop the duplicate.
178
+- **Installation failed after publication:** do not mutate the published tag. Fix forward through a new beta and the next stable patch.
179
+- **Homebrew update failed:** keep the GitHub Release intact, fix the tap credential or workflow issue, then dispatch `cli.bump-homebrew-tap.yml` with the exact stable tag.
180
+- **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.