Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 06:00 UTC
| 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. |