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

next
md 193 lines 8.05 KB
Rendered Raw
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.changelog.yml` opens a changelog PR as the SDK release App after a successful promotion.
21 - `.changeset/config.json` ignores `@composio/cli`.
22
23 `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.
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 | Dispatch promotion at an existing tested beta tag | 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 private CLI `package.json` uses a development sentinel and never selects a
35 binary version. If a release owner needs an intentional minor or major version,
36 dispatch an explicitly versioned beta, verify it, and promote that exact beta.
37
38 ## Changeset Rule
39
40 Never create a `.changeset/*.md` entry for `@composio/cli` while it remains in `.changeset/config.json#ignore`.
41
42 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.
43
44 Add human-facing CLI notes as bullets under `## Unreleased` in
45 `ts/packages/cli/CHANGELOG.md`. The changelog workflow compares the changelog
46 snapshots at published stable tags and opens or updates a PR that moves shipped
47 notes into version sections. If that PR was missed, dispatch
48 `cli.changelog.yml` on `next` to regenerate it.
49
50 Run this guard before handoff:
51
52 ```bash
53 pnpm validate:changesets
54 ```
55
56 ## Inspect Candidates
57
58 Use live GitHub state. Do not select a beta from local tags or remembered versions.
59
60 ```bash
61 REPOSITORY=ComposioHQ/composio
62
63 gh release list \
64 --repo "$REPOSITORY" \
65 --limit 100 \
66 --json tagName,isPrerelease,isDraft,publishedAt \
67 --jq '.[] | select(.tagName | startswith("@composio/cli@")) | select(.isPrerelease and (.isDraft | not))'
68 ```
69
70 For the chosen candidate, require a published prerelease and inspect its commit and assets:
71
72 ```bash
73 BETA_TAG='@composio/cli@0.0.0-beta.000'
74
75 gh release view "$BETA_TAG" \
76 --repo "$REPOSITORY" \
77 --json tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets \
78 --jq '{tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets:[.assets[] | {name,state}]}'
79 ```
80
81 The beta must have `isDraft: false`, `isPrerelease: true`, and these seven assets in `uploaded` state:
82
83 - `composio-linux-x64.zip`
84 - `composio-linux-aarch64.zip`
85 - `composio-darwin-x64.zip`
86 - `composio-darwin-aarch64.zip`
87 - `composio-windows-x64.zip` (experimental: absent when the `Windows x64` job failed, which does not block the release)
88 - `composio-skill.zip`
89 - `checksums.txt`
90
91 Find the beta workflow run by its target commit and require it to be green, including the reusable installation-test jobs:
92
93 ```bash
94 TARGET_COMMIT='replace-with-targetCommitish'
95
96 gh run list \
97 --repo "$REPOSITORY" \
98 --workflow build-cli-binaries.yml \
99 --commit "$TARGET_COMMIT" \
100 --limit 10
101 ```
102
103 If the user asked for a stable release without naming a beta, show the candidate and stop for confirmation before dispatching.
104
105 ## Build A Manual Beta
106
107 Use this only when an explicit beta build is requested. The selected ref
108 supplies both the workflow definition and source commit. Omit `version` for the
109 normal next-patch beta, or provide an exact `major.minor.patch` base for an
110 intentional minor or major release.
111
112 ```bash
113 SOURCE_BRANCH='replace-with-branch'
114
115 gh workflow run build-cli-binaries.yml \
116 --repo "$REPOSITORY" \
117 --ref "$SOURCE_BRANCH" \
118 --raw-field action=build-beta
119 ```
120
121 For an intentional minor or major, add a version newer than the latest stable:
122
123 ```bash
124 gh workflow run build-cli-binaries.yml \
125 --repo "$REPOSITORY" \
126 --ref "$SOURCE_BRANCH" \
127 --raw-field action=build-beta \
128 --raw-field version=0.3.0
129 ```
130
131 Watch the returned run through publication and installation tests. A beta is not a stable release.
132
133 ## Promote A Beta To Stable
134
135 Derive the stable tag by removing the beta suffix, then ensure no published stable release already exists:
136
137 ```bash
138 STABLE_TAG="${BETA_TAG%%-beta.*}"
139
140 gh release view "$STABLE_TAG" --repo "$REPOSITORY" --json tagName,isDraft,isPrerelease,publishedAt
141 ```
142
143 - If the stable tag is absent, promotion may proceed.
144 - If it is a draft, the promotion can resume it.
145 - If it is already published, stop. Never overwrite a published release.
146
147 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:
148
149 ```bash
150 gh workflow run build-cli-binaries.yml \
151 --repo "$REPOSITORY" \
152 --ref "$BETA_TAG" \
153 --raw-field action=promote-stable
154 ```
155
156 Use the returned URL when available. Otherwise identify the new dispatch, verify its creation time and actor, then watch it:
157
158 ```bash
159 gh run list \
160 --repo "$REPOSITORY" \
161 --workflow build-cli-binaries.yml \
162 --event workflow_dispatch \
163 --commit "$TARGET_COMMIT" \
164 --limit 5
165
166 gh run watch RUN_ID --repo "$REPOSITORY" --compact --exit-status
167 ```
168
169 ## Verify Completion
170
171 Do not call the release complete until all of these are true:
172
173 1. `Build CLI Binaries` completed successfully.
174 2. The stable release is published with `isDraft: false` and `isPrerelease: false`.
175 3. All seven canonical assets are present and uploaded, or six when the experimental `Windows x64` job failed.
176 4. The workflow's installation-test matrix passed.
177
178 ```bash
179 gh release view "$STABLE_TAG" \
180 --repo "$REPOSITORY" \
181 --json tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets \
182 --jq '{tagName,isDraft,isPrerelease,publishedAt,targetCommitish,assets:[.assets[] | {name,state}]}'
183 ```
184
185 Report the stable tag, promoted beta, target commit, workflow URL, asset count and state, and installation result.
186
187 ## Failure Recovery
188
189 - **Build matrix failed:** no release should publish. Fix the source, produce a new beta, and promote that candidate.
190 - **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`.
191 - **Duplicate run says the release is already published:** this is an intentional safety failure. Verify the published release and stop the duplicate.
192 - **Installation failed after publication:** do not mutate the published tag. Fix forward through a new beta and the next stable patch.
193 - **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.