@devries-cameron20 / composio Mirror · read-only / commits / 94713219a
Fork 0

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

chore(release): move stable SDK releases to the unified workflow

Stable npm publishing on next and Python py@* tags give way to sdk.release.yml. ts.release.yml keeps the main beta lane, release PRs own the SDK reference docs, and the docs release pins replace the pin realignment in docs.sdk-change-sync.yml. Rewrite the release runbook and contributor guidance for the new process.

jkomyno committed Nov 5, 2026 at 17:48 UTC 94713219a41dfb8865ff6430a9f393cf2ee07527
15 files changed +95 -349
.agents/skills/cli-release/references/release-workflow.md
+1 -1
@@ -19,7 +19,7 @@
19 - `.github/workflows/cli.test-installation.yml` validates installers after publication.
20 - `.changeset/config.json` ignores `@composio/cli`.
21
22 -`ts.release.yml` is the TypeScript SDK/npm release train. It is not the normal CLI binary release path.
22 +`sdk.release.yml` owns stable Python/TypeScript publication; `ts.release.yml` retains the `main` SDK beta lane. CLI binary releases use their own workflow.
23
24 ## Choose The Path
25
.agents/skills/python-release/references/release-workflow.md
+5 -1
@@ -10,7 +10,11 @@ make build
10
11 `make build` cleans build outputs, builds the root package, then builds provider packages and collects distributions.
12
13 -`py.release.yml` does not run `make env`. It installs only the `release` dependency group from `uv.lock` with `uv sync --locked --only-group release` and builds with `BUILD_ARGS=--no-isolation`, so the release build fetches nothing unlocked. A separate `publish` job uploads to PyPI through trusted publishing (OIDC, `pypi` environment). Bump `build` or `setuptools` in that group, then run `uv lock`.
13 +Stable Python releases use the unified `sdk.release.yml` member request and one approved release PR. Author changesets for the private `@composio/python-sdk` marker; the release bot synchronizes core and all supported provider metadata. Read `ts/docs/internal/release.md` for request, approval, merge, recovery and owner setup steps.
14 +
15 +Recovery: re-run a failed tag run with `gh run rerun <tag-run-id> --failed`. When the approved candidate expired, add a changeset and request a new release. Agents stop at "release PR ready for approval" and never merge it.
16 +
17 +Candidate builds install only the `release` dependency group from `uv.lock` with `uv sync --locked --only-group release` and use `BUILD_ARGS=--no-isolation`. Bump `build` or `setuptools` in that group, then run `uv lock`. Stable publication uses the tag-only `pypi-release` OIDC environment. The legacy `py.release.yml` keeps build-only dispatch and core-prerelease publication through `pypi`.
18
19 ## Dependency Bounds
20
.agents/skills/repo-guidance/references/repository-workflow.md
+3 -2
@@ -47,9 +47,10 @@ make build
47
48 ## Changesets
49
50 -- Add a changeset for changes to published TypeScript packages.
50 +- Public SDK behavior changes need a Changesets note for each affected TypeScript package and/or the private `@composio/python-sdk` marker. Python core and supported providers share one stable release train.
51 - `@composio/cli` is ignored by Changesets. Never target it in a changeset while it remains ignored; use the `cli-release` skill for beta builds and stable promotion.
52 -- Do not add a changeset for repo guidance, docs-only, tests-only, or validation-only changes unless release metadata changes.
52 +- Repo guidance, docs-only, tests-only, internal validation and CLI-only changes do not require an SDK note. Explicit behavior exemptions need a meaningful `<!-- sdk-release-note-exempt: meaningful reason of at least 20 characters -->` comment in the PR body.
53 +- Stable SDKs use **SDK release** on protected `next`: a member issue request, one release PR that a non-requester approves and a person merges, and a tag run that publishes the PR-built candidates. Recover with **Re-run failed jobs**. Read `ts/docs/internal/release.md` before operating it.
54
55 ## Generated And Vendor Files
56
.changeset/README.md
+3
@@ -14,3 +14,6 @@ under SDK source has no public effect, explain it in the PR description:
14 <!-- sdk-release-note-exempt: Explain why this change has no published behavior. -->
15 ```
16
17 +The SDK release issue form prepares one release PR from protected `next`. A writer
18 +who did not request the release approves its final head after the candidate checks
19 +pass, and a person merges it. See `ts/docs/internal/release.md`.
.github/workflows/docs.sdk-change-sync.yml
+1 -54
@@ -80,58 +80,10 @@ jobs:
80 4. Update any docs that would be stale or incorrect after this SDK change — guides, FAQs, examples, quickstart, etc.
81 5. Do NOT touch docs/content/reference/ (those are auto-generated separately)
82 6. Do NOT touch docs/content/changelog/ (changelogs are written separately)
83 - 7. Do NOT edit docs/package.json or docs/bun.lock — the `@composio/*` version pins are managed automatically by the dependency-realignment step below, which runs after you and overwrites any changes you make to them
83 + 7. Do NOT edit docs/package.json or docs/bun.lock — the SDK release workflow pins the `@composio/*` versions after each release
84 8. If no docs changes are needed, make no file changes
85 9. Do NOT add type assertions or casts to force a snippet to compile against an API that is missing from the published `@composio/*` package. If a feature isn't released yet, document the released behavior and let the Twoslash build flag the gap.
86
87 - - name: Setup Node.js, pnpm, Bun
88 - if: steps.diff.outputs.has_changes == 'true'
89 - uses: ./.github/actions/setup-node-pnpm-bun
90 -
91 - - name: Align docs SDK deps with latest published releases
92 - if: steps.diff.outputs.has_changes == 'true'
93 - working-directory: ./docs
94 - run: |
95 - # Docs is a standalone Bun app outside the pnpm workspace: it pins
96 - # published @composio/* versions instead of linking workspace source,
97 - # so its Twoslash snippets and example apps only ever demonstrate APIs
98 - # that users can actually install. Realign those pins to the latest
99 - # released versions on every sync so they never drift behind the SDK
100 - # (the drift that previously forced workaround casts into snippets).
101 - # This runs AFTER the content pass so the committed pins are always
102 - # authoritative — even if that pass edited package.json/bun.lock, this
103 - # step resets the @composio/* pins and regenerates the lockfile.
104 - # The PR's Twoslash build (docs-typescript-check.yml) gates the result:
105 - # if a documented feature isn't published yet, the build fails loudly
106 - # instead of the gap being papered over.
107 - set -euo pipefail
108 - # Discard any edits the content pass made to these managed files so the
109 - # realignment is the sole source of truth for the dependency pins.
110 - git checkout -- package.json bun.lock
111 - changed=0
112 - for section in dependencies devDependencies; do
113 - pkgs=$(jq -r --arg s "$section" '.[$s] // {} | keys[] | select(startswith("@composio/"))' package.json)
114 - for pkg in $pkgs; do
115 - latest=$(npm view "$pkg" version 2>/dev/null || true)
116 - if [ -z "$latest" ]; then
117 - echo "::warning::could not resolve a published version for $pkg; leaving its pin unchanged"
118 - continue
119 - fi
120 - current=$(jq -r --arg s "$section" --arg p "$pkg" '.[$s][$p]' package.json)
121 - want="^$latest"
122 - if [ "$current" != "$want" ]; then
123 - echo "$section.$pkg: $current -> $want"
124 - npm pkg set "$section.$pkg=$want"
125 - changed=1
126 - fi
127 - done
128 - done
129 - if [ "$changed" -eq 1 ]; then
130 - bun install
131 - else
132 - echo "All @composio/* pins already match the latest published releases."
133 - fi
134 -
87 - name: Create PR if changed
88 id: create-pr
89 if: steps.diff.outputs.has_changes == 'true'
@@ -146,9 +98,6 @@ jobs:
98
99 - Claude reviewed the SDK diff and updated guides, FAQs, or examples
100 that reference changed APIs or features.
149 - - The docs `@composio/*` dependencies were realigned to their latest
150 - published releases so Twoslash snippets and example apps validate
151 - against versions users can actually install.
101
102 ## Review checklist
103 - [ ] Changes accurately reflect the new SDK behavior
@@ -162,8 +111,6 @@ jobs:
111 base: next
112 add-paths: |
113 docs/content/docs/
165 - docs/package.json
166 - docs/bun.lock
114
115 - name: Request review from pusher
116 if: steps.create-pr.outputs.pull-request-number
.github/workflows/generate-sdk-docs.yml deleted
-118
@@ -1,118 +0,0 @@
1 -name: Generate SDK Docs
2 -
3 -on:
4 - push:
5 - branches: [next]
6 - paths:
7 - - 'ts/packages/core/src/**'
8 - - 'ts/packages/core/scripts/generate-docs.ts'
9 - - 'python/composio/**'
10 - - 'python/scripts/generate-docs.py'
11 - - '.github/actions/setup-node-pnpm-bun/action.yml'
12 - - '.github/actions/setup-python-uv/action.yml'
13 - - '.github/workflows/generate-sdk-docs.yml'
14 - - 'mise.toml'
15 - - 'mise.lock'
16 - workflow_dispatch:
17 -
18 -permissions:
19 - contents: read
20 -
21 -jobs:
22 - generate-ts-docs:
23 - runs-on: ubuntu-latest
24 - permissions:
25 - contents: write
26 - pull-requests: write
27 -
28 - steps:
29 - - name: Generate GitHub App token
30 - id: app-token
31 - uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
32 - with:
33 - client-id: ${{ vars.RELEASE_BOT_CLIENT_ID }}
34 - private-key: ${{ secrets.RELEASE_BOT_APP_PRIVATE_KEY }}
35 -
36 - - name: Checkout Code
37 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
38 - with:
39 - token: ${{ steps.app-token.outputs.token }}
40 -
41 - - name: Setup Node.js, pnpm, Bun
42 - uses: ./.github/actions/setup-node-pnpm-bun
43 -
44 - - run: pnpm install --frozen-lockfile
45 -
46 - - run: pnpm --filter @composio/core generate:docs
47 -
48 - - name: Create Pull Request
49 - id: create-pr
50 - uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
51 - with:
52 - token: ${{ steps.app-token.outputs.token }}
53 - commit-message: 'docs: auto-generate TypeScript SDK reference'
54 - title: 'docs: update TypeScript SDK reference from source'
55 - body: |
56 - ## Summary
57 - Auto-generated TypeScript SDK reference docs from `ts/packages/core/src/`.
58 -
59 - Regenerates pages at `docs/content/reference/sdk-reference/typescript/` to reflect changes in the core package's public API (new methods, updated signatures, changed types).
60 - branch: docs/auto-update-ts-sdk-reference
61 - base: next
62 - add-paths: docs/content/reference/sdk-reference/typescript/
63 -
64 - - name: Request review from pusher
65 - if: steps.create-pr.outputs.pull-request-number
66 - env:
67 - GH_TOKEN: ${{ steps.app-token.outputs.token }}
68 - PR_NUMBER: ${{ steps.create-pr.outputs.pull-request-number }}
69 - AUTHOR: ${{ github.actor }}
70 - run: gh pr edit "$PR_NUMBER" --add-reviewer "$AUTHOR"
71 -
72 - generate-python-docs:
73 - runs-on: ubuntu-latest
74 - permissions:
75 - contents: write
76 - pull-requests: write
77 -
78 - steps:
79 - - name: Generate GitHub App token
80 - id: app-token
81 - uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
82 - with:
83 - client-id: ${{ vars.RELEASE_BOT_CLIENT_ID }}
84 - private-key: ${{ secrets.RELEASE_BOT_APP_PRIVATE_KEY }}
85 -
86 - - name: Checkout Code
87 - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
88 - with:
89 - token: ${{ steps.app-token.outputs.token }}
90 -
91 - - name: Setup Python with UV
92 - uses: ./.github/actions/setup-python-uv
93 -
94 - - run: cd python && uv run --with griffe python scripts/generate-docs.py
95 -
96 - - name: Create Pull Request
97 - id: create-pr
98 - uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
99 - with:
100 - token: ${{ steps.app-token.outputs.token }}
101 - commit-message: 'docs: auto-generate Python SDK reference'
102 - title: 'docs: update Python SDK reference from source'
103 - body: |
104 - ## Summary
105 - Auto-generated Python SDK reference docs from `python/composio/`.
106 -
107 - Regenerates pages at `docs/content/reference/sdk-reference/python/` to reflect changes in the Python package's public API (new methods, updated signatures, changed types).
108 - branch: docs/auto-update-python-sdk-reference
109 - base: next
110 - add-paths: docs/content/reference/sdk-reference/python/
111 -
112 - - name: Request review from pusher
113 - if: steps.create-pr.outputs.pull-request-number
114 - env:
115 - GH_TOKEN: ${{ steps.app-token.outputs.token }}
116 - PR_NUMBER: ${{ steps.create-pr.outputs.pull-request-number }}
117 - AUTHOR: ${{ github.actor }}
118 - run: gh pr edit "$PR_NUMBER" --add-reviewer "$AUTHOR"
.github/workflows/py.release.yml
+3 -1
@@ -17,6 +17,8 @@ permissions:
17 jobs:
18 build:
19 name: Build SDK packages
20 + outputs:
21 + core_only: ${{ steps.release_mode.outputs.core_only }}
22 defaults:
23 run:
24 working-directory: ./python
@@ -91,7 +93,7 @@ jobs:
93 publish:
94 name: Publish to PyPI
95 needs: build
94 - if: github.event_name == 'push'
96 + if: github.event_name == 'push' && needs.build.outputs.core_only == 'true'
97 runs-on: ubuntu-latest
98 environment:
99 name: pypi
.github/workflows/ts.release.yml
+3 -2
@@ -1,9 +1,10 @@
1 -name: TS SDK Release
1 +name: TS SDK beta release
2
3 on:
4 workflow_dispatch:
5 push:
6 - branches: [next, main]
6 + # Stable releases use sdk.release.yml; this keeps the main beta lane.
7 + branches: [main]
8
9 permissions:
10 contents: read
AGENTS.md
+1 -1
@@ -101,7 +101,7 @@ make build
101
102 ## Release And Package Notes
103
104 -- TypeScript package releases use Changesets. Add a changeset only when published TypeScript packages change.
104 +- Stable Python and TypeScript SDK releases share Changesets. Public SDK behavior changes need a note for each affected package/language; Python uses the private `@composio/python-sdk` marker. See `ts/docs/internal/release.md` for the shared request/approval/retry process.
105 - `@composio/cli` is excluded from Changesets; use `cli-release` for CLI binaries and never target that package in a changeset while it remains ignored.
106 - Documentation-only and agent-guidance-only changes do not need a changeset.
107 - Python release metadata lives in `python/pyproject.toml`, `python/setup.py`, and `uv.lock`.
CONTRIBUTING.md
+2 -2
@@ -225,7 +225,7 @@ Docs changes follow the [third-party links policy](#third-party-links-in-docs).
225
226 4. Add or update tests for behavior changes, and update docs for user-facing changes.
227
228 -5. Add a changeset for changes that affect published TypeScript packages:
228 +5. Add a changeset for public Python or TypeScript SDK behavior changes. Select each affected TypeScript package and/or the private `@composio/python-sdk` marker:
229
230 ```bash
231 pnpm changeset
@@ -307,7 +307,7 @@ bun run lint:links
307
308 ## Release Process
309
310 -Only maintainers publish releases.
310 +Any active ComposioHQ member can request a stable SDK release through the SDK release issue form. Repository writers can also run **SDK release** on `next`. A repository writer who did not request the release approves the final release PR, a person merges it, and automation publishes the candidates the PR built and checked. See the shared runbook below. CLI binaries and `main` beta releases keep their separate workflows.
311
312 - TypeScript packages and the CLI: [`ts/docs/internal/release.md`](ts/docs/internal/release.md)
313 - Python packages: [`python/docs/release.md`](python/docs/release.md)
docs/agent-guidance/context/sdk-reference.md
+1 -1
@@ -22,4 +22,4 @@ Auto-generated SDK documentation from source code.
22
23 ## CI Integration
24
25 -CI auto-generates on changes to `ts/packages/core/src/**` or `python/composio/**` via `.github/workflows/generate-sdk-docs.yml`.
25 +The SDK release workflow (`.github/workflows/sdk.release.yml`) regenerates both references in each release PR, so the published reference always matches the released packages.
python/AGENTS.md
+2
@@ -36,6 +36,8 @@ make build
36
37 ## Rules
38
39 +- Public Python SDK/provider behavior changes need a Changesets note targeting the private `@composio/python-sdk` marker. Stable core and providers release together through the unified SDK request workflow.
40 +
41 - Use Ruff for formatting/linting and mypy for type checks.
42 - Add pytest coverage for behavior changes.
43 - Keep provider-specific changes under the relevant `python/providers/<provider>/` package.
python/docs/release.md
+14 -9
@@ -1,12 +1,17 @@
1 -# Creating python package release
1 +# Release the Python SDK
2
3 -1. Decide which packages you want to publish
4 -2. Run `python scripts/bump.py`
5 -3. This will prompt you with the different packages and the next version, select next version or skip for given package
6 -4. Create a release PR
7 -5. Merge and publish a github release
3 +Request a stable Python release through the shared [SDK release procedure](../../ts/docs/internal/release.md). Every active ComposioHQ member can use the release issue form. Leave Python at `auto` to follow the changesets, or select a patch, minor, or major override. Set TypeScript to `skip` for a Python-only release.
4
9 -**NOTES**
5 +Public Python SDK/provider changes include a changeset targeting the private `@composio/python-sdk` marker. Core and supported providers form one stable train. The bot updates the version mirrors and `uv.lock` and opens one release PR. Its `SDK candidate (python)` check builds the wheels and sdists; `SDK candidate smoke (python)` installs them in a clean venv and tests the new core with the latest published providers. A repository writer who did not request the release approves the head, and a person merges it. The tag run publishes those exact files through the tag-only `pypi-release` identity.
6
11 -* Since the development is active on `next` branch, only select this branch when creating github release
12 -* While the development is active, only create release-candidate by selecting `pre` when prompted for next version in `bump.py`
\ No newline at end of file
7 +If publishing fails, choose **Re-run failed jobs** on the tag run within 30 days of the candidate build. After that, add a changeset for `@composio/python-sdk` and request a new release; the train moves to the next version.
8 +
9 +For local packaging checks, run from `python/`:
10 +
11 +```bash
12 +make build
13 +```
14 +
15 +The release pipeline installs locked build tools from the root workspace's `release` dependency group and builds with `BUILD_ARGS=--no-isolation`. Update generated-client pins only after verifying that the client version exists, and regenerate `uv.lock` with uv.
16 +
17 +The legacy `py.release.yml` keeps build-only dispatch and core-prerelease publishing. Stable releases use the shared workflow rather than manual version bumps or `py@` tags.
ts/AGENTS.md
+1 -1
@@ -32,7 +32,7 @@ pnpm test:e2e:cli
32
33 - Do not edit `ts/vendor/`; those submodules are read-only references.
34 - Keep generated outputs owned by their generator.
35 -- Add changesets only for changes to published TypeScript packages.
35 +- Add a Changesets note for each affected published TypeScript package; cross-language changes also target the private `@composio/python-sdk` marker. Stable SDK publication uses the unified request workflow.
36 - Never add changesets for `@composio/cli` while `.changeset/config.json` ignores it; record CLI notes in `ts/packages/cli/CHANGELOG.md` instead.
37 - Prefer focused package tests before broad workspace tests.
38 - Parse untyped or external data (API payloads, JSON, `unknown`) at the boundary with schemas and let inferred types flow downstream: zod in SDK packages (`@composio/core`, providers, shared packages), `effect/Schema` in `ts/packages/cli/`. Never hand-roll structural guards (`'x' in obj` / `typeof` chains) or cast parsed JSON with `as`.
ts/docs/internal/release.md
+55 -156
@@ -1,189 +1,88 @@
1 -# Release Process
1 +# Stable SDK releases
2
3 -This document outlines the release processes for the Composio SDK. We support both automated releases through GitHub Actions and manual releases when needed.
3 +One workflow, `sdk.release.yml`, releases the TypeScript SDK, the Python SDK, or both. A member requests the release, the bot opens one release PR, a reviewer approves it, and a person merges it. The workflow then publishes the files the PR checked and opens a docs PR that pins the released versions.
4
5 -## CLI Binary Release Process
5 +```text
6 +request (issue or dispatch) → release PR (bot) → candidate checks → approve → merge
7 + → tag sdk-release/<id> → publish npm + PyPI → docs pin PR
8 +```
9
7 -The CLI binary release process is separate from npm publishing.
10 +## Request
11
9 -- `@composio/cli` is marked private and is not published to npm via Changesets.
10 -- CLI binaries are built and published as GitHub Release assets by `.github/workflows/build-cli-binaries.yml`.
11 -- Install and upgrade flows (`install.sh` and `composio upgrade`) download binaries from GitHub Releases.
12 -- `composio upgrade --beta` resolves the newest CLI prerelease from GitHub Releases.
12 +1. Open a GitHub issue with the **SDK release** form. Every active ComposioHQ member can use it, including members with repository Read access. Repository writers can instead run **SDK release** on `next` in Actions.
13 +2. Leave each language at `auto` to follow its changesets, or choose `patch`, `minor`, `major`, or `skip`. An explicit bump with no changesets creates a maintenance release; `auto` with no changesets replies "Nothing to release."
14
14 -### Triggers
15 +The bot plans versions on the current `next`, regenerates the SDK reference docs, writes the package changelogs and one docs changelog entry, and opens the release PR. Later `next` commits wait for the next release. Only one release PR is open at a time.
16
16 -The CLI binary workflow supports two entry points:
17 +## Review and approve
18
18 -- Beta release: the auto-generated Changesets release PR titled `Release: update version`
19 -- Stable release: manual `workflow_dispatch`, but only from an existing beta release tag
19 +The release PR description lists each package's old and new version, the changesets it consumes or leaves for later, and links to the changelogs and regenerated references. It names the requester, who may not approve.
20
21 -### Beta CLI Release
21 +1. Wait for the `SDK candidate (<language>)` and `SDK candidate smoke (<language>)` checks. The first builds the exact files that will be published. The second installs them in a clean project like a user would; for Python it also tests the new core with the latest published providers.
22 +2. A repository writer who did not request the release approves the head.
23
23 -When the Changesets release PR is opened or updated, the workflow:
24 +Do not push to the release branch. The tag step accepts only the bot's commit, so a pushed commit (including **Update branch**) makes the merge fail the gate. To change the notes, fix the changesets on `next`, close the release PR, and request a new release.
25
25 -1. Reads the bumped CLI version from `ts/packages/cli/package.json`
26 -2. Publishes a prerelease tag in the form `@composio/cli@<version>-beta.<pr-number>`
27 -3. Attaches the built binaries to that prerelease
26 +## Merge and publish
27
29 -### Stable CLI Release
28 +A person merges the approved, green release PR under normal `next` protection. On merge, the `tag` job checks that the head is the bot's commit, the approval, and the candidate and docs checks, then tags the head `sdk-release/<id>`. If the gate fails it creates no tag and comments the fix on the PR: revert the release PR on `next`, then request the release again.
29
31 -When running **Build CLI Binaries** manually:
30 +The tag run then:
31
33 -1. Enter an existing beta tag (for example `@composio/cli@1.2.3-beta.456`)
34 -2. The workflow verifies that the beta release already exists and is marked as a prerelease
35 -3. The workflow checks out the exact commit associated with that beta release
36 -4. The workflow rebuilds the binaries and publishes the stable release under `@composio/cli@<version>`
32 +1. Pins the candidate artifacts built on the release PR by ID and digest. It never rebuilds.
33 +2. Uploads only the files npm and PyPI are missing. An existing file with identical bytes is accepted; different bytes stop the run with a conflict. npm versions are uploaded under a release-only dist-tag, and `latest` moves once every upload is visible.
34 +3. Comments the published versions on the request issue and opens a docs PR that pins the released npm versions in `docs/package.json` and `docs/bun.lock`. Merging that PR after its checks pass is what makes twoslash type-check the docs against the released types.
35
38 -### What the workflow does
36 +If any job fails, the run comments the failed jobs and the run link on the request issue.
37
40 -1. Builds CLI binaries for Linux/macOS (x64 + arm64)
41 -2. Creates platform zip archives (`composio-<platform>.zip`)
42 -3. Publishes assets to the beta or stable GitHub Release
43 -4. Runs `.github/workflows/cli.test-installation.yml` to validate installation paths and shell integration
38 +## Recover a failed release
39
45 -### Notes
40 +Open the tag run and choose **Re-run failed jobs**. A re-run publishes the same pinned files, skips files already published, and uploads the rest. This works while the candidate artifacts exist, 30 days from the candidate build.
41
47 -- Stable promotion is intentionally gated on an existing beta release so the shipped stable binaries always correspond to a tested beta artifact.
42 +If the artifacts expired, or a registry already serves different bytes, add changesets for the affected packages on `next` and request a new release. It plans from the versions in `next`, so the unpublished versions are skipped and the packages move to the next version.
43
49 -## Automated Release Process
44 +## Add a release note
45
51 -The automated release process is triggered when code is merged into the `main` branch or manually through GitHub Actions.
46 +Run from the repository root:
47
53 -### Requirements
48 +```bash
49 +pnpm changeset
50 +```
51
55 -- `NPM_TOKEN` secret must be configured in GitHub repository settings
56 -- `CI_BOT_TOKEN` secret for GitHub authentication
57 -- All changes must be documented using Changesets
58 -- All quality checks must pass
52 +Select every affected published TypeScript package and/or the private `@composio/python-sdk` marker. The marker versions the Python core and all supported providers together; it is never published to npm. TypeScript core and slim move together, while providers keep independent versions.
53
60 -### Using Automated Release
54 +One changeset can cover both languages:
55
62 -1. **For Regular Releases (via main branch)**
63 - - Make sure your changeset is added to the PR you are merging to main. Run `pnpm changeset` on your branch before submiting the PR
64 - - Get your PR merged to main
65 - - The workflow will automatically:
66 - - Create a release PR
67 - - Publish packages when the release PR is merged
56 +```markdown
57 +---
58 +'@composio/core': minor
59 +'@composio/python-sdk': patch
60 +---
61
69 -2. **For Manual Triggers**
70 - - Go to GitHub Actions
71 - - Select "TS SDK Release" workflow
72 - - Click "Run workflow" on main branch
73 - - Monitor the workflow progress
62 +Describe the public behavior and any migration steps.
63 +```
64
75 -## Manual Release Process
65 +Put prose types such as `Array<Tool>` in code spans because summaries become MDX. Docs-only, tests-only, internal tooling, and CLI-only changes need no SDK note. If a source change doesn't affect public behavior, add `<!-- sdk-release-note-exempt: explain why public SDK behavior is unchanged -->` (at least 20 characters in the reason) to the PR description.
66
77 -The manual release process is available for cases where direct control over the release process is needed.
67 +## Documentation
68
79 -### Prerequisites
69 +- The release PR commits the SDK reference docs, generated from the released source, and the docs changelog entry. Changelog snippets are not type-checked, because they may describe APIs released after the docs pins.
70 +- The docs pin PR moves the docs to the released npm versions. Twoslash then checks every guide snippet against those types.
71 +- `docs.sdk-change-sync.yml` keeps updating guides for SDK source changes; it no longer touches the version pins.
72
81 -- Node.js, Bun, Python, uv, and pnpm from `mise.toml`
82 -- Access to npm registry
83 -- Write access to the repository
73 +## Owner setup
74
85 -### Steps
75 +Complete these hosted prerequisites before the first release.
76
87 -1. **Prepare for Release**
77 +1. Install a dedicated SDK release App with repository Contents, Pull requests, and Issues write, Actions read, and organization Members read. It needs no protection bypass on `next`. Set the `SDK_RELEASE_APP_SLUG` and `SDK_RELEASE_APP_CLIENT_ID` variables. Put `SDK_RELEASE_APP_PRIVATE_KEY` only in the `sdk-release-control` environment, restricted to `next`.
78 +2. Protect `sdk-release/*` tags against creation, update, and deletion, with only this App allowed to bypass. Publishing trusts these tags, so check that an ordinary writer cannot create or move one.
79 +3. Create `npm-release` and `pypi-release` environments that deploy only from `sdk-release/*` tags.
80 +4. Register trusted publishers for `.github/workflows/sdk.release.yml` with the `npm-release` environment on every npm package, and with `pypi-release` on every PyPI package. npm allows one trusted publisher per package, so this replaces the `ts.release.yml` identity the `main` beta lane uses: decide how betas publish (an npm token in `ts.release.yml`, or a beta mode in `sdk.release.yml`) before switching. PyPI accepts several publishers.
81 +5. Restrict pushes to `sdk-release/batch-*` branches to the App. The tag step refuses heads the App did not commit, so this only prevents confusion.
82 +6. Keep Actions artifact retention at 30 days or more.
83
89 - ```bash
90 - # Ensure you're on the latest main
91 - git checkout main
92 - git pull origin main
84 +## CLI binaries and beta SDKs
85
94 - # Install dependencies
95 - mise install
96 - pnpm install
86 +CLI binaries keep **Build CLI Binaries** and GitHub Releases. `@composio/cli` stays excluded from changesets. Follow the [CLI release skill](../../../.agents/skills/cli-release/references/release-workflow.md).
87
98 - # Run quality checks
99 - pnpm build
100 - pnpm check:peer-deps
101 - ```
102 -
103 -2. **Create Changeset**
104 -
105 - ```bash
106 - pnpm changeset
107 - ```
108 -
109 - - Select affected packages
110 - - Choose version bump type (major/minor/patch)
111 - - Write a detailed change description
112 - - Commit the generated changeset file
113 -
114 - For pre-releases:
115 -
116 - ```bash
117 - pnpm changeset:pre-enter
118 - pnpm changeset
119 - ```
120 -
121 -3. **Version Packages**
122 -
123 - ```bash
124 - pnpm changeset:version
125 - ```
126 -
127 - - Review the version changes
128 - - Commit the package bumps
129 -
130 -4. **Publish Packages**
131 -
132 - ```bash
133 - # Ensure you're logged in to npm
134 - npm login
135 -
136 - # Publish
137 - pnpm changeset:release
138 - ```
139 -
140 -### Troubleshooting
141 -
142 -1. **Authentication Issues**
143 - - Ensure you're logged in to npm (`npm login`)
144 - - Check npm token validity
145 - - Verify registry settings in `.npmrc`
146 -
147 -2. **Build Failures**
148 - - Clear node_modules: `pnpm clean`
149 - - Reinstall dependencies: `pnpm install`
150 - - Check for peer dependency issues
151 -
152 -3. **Version Conflicts**
153 - - Check package.json versions
154 - - Verify changeset entries
155 - - Review git tags
156 -
157 -## Best Practices
158 -
159 -1. **Changesets**
160 - - Write clear, descriptive changeset messages
161 - - Include breaking changes prominently
162 - - Reference relevant issues/PRs
163 -
164 -2. **Version Management**
165 - - Follow semver strictly
166 - - Document breaking changes
167 - - Update peer dependencies appropriately
168 -
169 -3. **Quality Assurance**
170 - - Run all tests before release
171 - - Check bundle sizes
172 - - Verify documentation updates
173 -
174 -## Post-Release
175 -
176 -1. **Verification**
177 - - Check npm registry for new versions
178 - - Verify package installations
179 - - Test example projects
180 -
181 -2. **Documentation**
182 - - Update changelog if needed
183 - - Update version numbers in docs
184 - - Announce breaking changes
185 -
186 -3. **Cleanup**
187 - - Remove pre-release branches if any
188 - - Update release tickets/issues
189 - - Archive release artifacts
88 +The `main` SDK beta lane keeps `ts.release.yml`, its prerelease state and its trusted identity. `py.release.yml` keeps build-only dispatch and core prereleases.