From b58d820dab4d27108187a9dd2312783c26c3e72d Mon Sep 17 00:00:00 2001 From: "kiloconnect[bot]" <240665456+kiloconnect[bot]@users.noreply.github.com> Date: Tue, 3 Mar 2026 16:02:18 +0000 Subject: [PATCH 1/4] docs: add RELEASING.md documenting the release process --- README.md | 2 + RELEASING.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 116 insertions(+) create mode 100644 RELEASING.md diff --git a/README.md b/README.md index 30a45e50d16..dec1b4ce6a5 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,8 @@ kilo run --auto "run tests and fix any failures" We welcome contributions from developers, writers, and enthusiasts! To get started, please read our [Contributing Guide](/CONTRIBUTING.md). It includes details on setting up your environment, coding standards, types of contribution and how to submit pull requests. +See [RELEASING.md](RELEASING.md) for the release process. + ## Code of Conduct Our community is built on respect, inclusivity, and collaboration. Please review our [Code of Conduct](/CODE_OF_CONDUCT.md) to understand the expectations for all contributors and community members. diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 00000000000..1909396086a --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,114 @@ +# Releasing Kilocode + +Kilocode uses a fully automated CI pipeline triggered via GitHub Actions `workflow_dispatch`. A single workflow handles version bumping, building all artifacts, publishing to every distribution channel, and updating package registries. + +## How to Trigger a Release + +1. Go to the [`publish` workflow](https://github.com/Kilo-Org/kilocode/actions/workflows/publish.yml) in GitHub Actions. +2. Click **"Run workflow"**. +3. Select the branch (typically `main`). +4. Fill in the inputs: + - **`bump`** (choice): `patch`, `minor`, or `major`. Determines how the version number is incremented. + - **`version`** (string, optional): Override the version explicitly instead of using `bump`. Leave empty to use the bump-based calculation. +5. Click **"Run workflow"** to start the release. + +## What Happens During a Release + +The `publish.yml` workflow runs four jobs sequentially: + +### 1. Version (`version`) + +- Checks out the repo with full history (`fetch-depth: 0`). +- Runs `script/version.ts` to compute the next version based on the `bump` or `version` input. +- Generates release notes from the commit history since the last release. +- Creates a **draft** GitHub Release with the computed tag (e.g. `v1.2.3`) and release notes. +- Outputs the `version`, `release` (database ID), and `tag` for downstream jobs. + +### 2. Build CLI (`build-cli`) + +- Runs `packages/opencode/script/build.ts` to compile the Kilo CLI binary. +- Builds native binaries for **all supported platforms and architectures**: + - Linux: x64, arm64 (glibc and musl), plus baseline (non-AVX2) variants + - macOS: x64, arm64, plus baseline variants + - Windows: x64, plus baseline variant +- Patches ELF interpreters on Linux binaries for broad compatibility. +- Creates platform archives (`.tar.gz` for Linux, `.zip` for macOS/Windows) and uploads them to the draft GitHub Release. +- Uploads the `dist/` directory as a workflow artifact (`kilo-cli`) for subsequent jobs. + +### 3. Build VS Code Extension (`build-vscode`) + +- Downloads the CLI artifacts from the previous job. +- Runs `packages/kilo-vscode/script/build.ts` to build VSIX packages for all target platforms: + - `linux-x64`, `linux-arm64`, `alpine-x64`, `alpine-arm64`, `darwin-x64`, `darwin-arm64`, `win32-x64` +- Each VSIX bundles the platform-specific CLI binary. +- Uploads the VSIX files as a workflow artifact (`kilo-vscode`). + +### 4. Publish (`publish`) + +Downloads all build artifacts and publishes to every distribution channel: + +#### Version Commit and Tagging + +- Updates the `version` field in all `package.json` files across the monorepo. +- Updates the Zed extension manifest (`extension.toml`) with the new version. +- Rebuilds the TypeScript SDK (`packages/sdk/js`). +- Commits the version bump, tags the commit, and pushes to the repo. +- Promotes the draft GitHub Release to a published release. + +#### CLI (`@kilocode/cli`) + +- Publishes platform-specific binary packages to **npm** (e.g. `@kilocode/cli-linux-x64`, `@kilocode/cli-darwin-arm64`, etc.). +- Publishes the main `@kilocode/cli` package to **npm** with optional dependencies on the binary packages. +- Builds and pushes a multi-arch **Docker image** (`ghcr.io/kilo-org/kilo`) to GitHub Container Registry (linux/amd64 + linux/arm64). + +#### SDK (`@kilocode/sdk`) + +- Builds and publishes the TypeScript SDK to **npm**. + +#### Plugin (`@kilocode/plugin`) + +- Builds and publishes the plugin interface package to **npm**. + +#### VS Code Extension + +- Publishes platform-specific VSIX packages to the **VS Code Marketplace** via `vsce`. +- Uploads all VSIX files to the **GitHub Release** as assets. + +#### Package Registries (stable releases only) + +- **AUR (Arch Linux)**: Clones `kilo-bin` from the AUR, updates the `PKGBUILD` with new version and SHA256 checksums, and pushes. +- **Homebrew**: Clones `Kilo-Org/homebrew-tap`, updates the `kilo.rb` formula with new version, download URLs, and SHA256 checksums, and pushes. + +## Prerequisites and Permissions + +### Repository Access + +- The workflow only runs in the `Kilo-Org/kilocode` repository (guarded by `if: github.repository == 'Kilo-Org/kilocode'`). +- You must have **write access** to the repository to trigger a `workflow_dispatch` event. + +### Workflow Permissions + +The workflow requires these GitHub token permissions: + +- `id-token: write` -- for npm provenance attestation +- `contents: write` -- for creating releases, pushing tags, and uploading assets +- `packages: write` -- for publishing Docker images to GHCR + +### Required Secrets + +The following secrets must be configured in the repository: + +| Secret | Purpose | +| ---------------------------- | ---------------------------------------------------------------- | +| `KILO_API_KEY` | Kilo API key used during version computation | +| `KILO_ORG_ID` | Kilo organization ID | +| `KILO_MAINTAINER_APP_ID` | GitHub App ID for the kilo-maintainer bot (used for git commits) | +| `KILO_MAINTAINER_APP_SECRET` | GitHub App secret for the kilo-maintainer bot | +| `NPM_TOKEN` | npm authentication token for publishing packages | +| `VSCE_TOKEN` | VS Code Marketplace personal access token | +| `OVSX_TOKEN` | Open VSX Registry token (currently unused but configured) | +| `AUR_KEY` | SSH private key for pushing to the AUR | + +### Concurrency + +The workflow uses concurrency control (`workflow-ref-bump/version`) to prevent parallel releases from conflicting. From d0042bb24ec6a5d9e8fa1706f1a21d0110d5fb6d Mon Sep 17 00:00:00 2001 From: "kiloconnect[bot]" <240665456+kiloconnect[bot]@users.noreply.github.com> Date: Tue, 3 Mar 2026 16:04:42 +0000 Subject: [PATCH 2/4] docs: clarify that version input should be left empty by default --- RELEASING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/RELEASING.md b/RELEASING.md index 1909396086a..9686a1ee07e 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -10,6 +10,10 @@ Kilocode uses a fully automated CI pipeline triggered via GitHub Actions `workfl 4. Fill in the inputs: - **`bump`** (choice): `patch`, `minor`, or `major`. Determines how the version number is incremented. - **`version`** (string, optional): Override the version explicitly instead of using `bump`. Leave empty to use the bump-based calculation. + + > **⚠️ Do not fill in `version` unless you have a specific reason to.** + > The default behavior — leaving `version` empty and selecting a `bump` level — is almost always what you want. The automated bump logic computes the correct next version from the current state of the repo. Only use the `version` override for exceptional cases like skipping versions or publishing a pre-release (e.g. `1.5.0-beta.1`). + 5. Click **"Run workflow"** to start the release. ## What Happens During a Release From 9744384c634642645730bb41981db2e50018ee2e Mon Sep 17 00:00:00 2001 From: Mark IJbema Date: Tue, 3 Mar 2026 17:08:45 +0100 Subject: [PATCH 3/4] Update RELEASING.md Co-authored-by: kilo-code-bot[bot] <240665456+kilo-code-bot[bot]@users.noreply.github.com> --- RELEASING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RELEASING.md b/RELEASING.md index 9686a1ee07e..16b39fcf3e6 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,4 +1,4 @@ -# Releasing Kilocode +# Releasing Kilo Code Kilocode uses a fully automated CI pipeline triggered via GitHub Actions `workflow_dispatch`. A single workflow handles version bumping, building all artifacts, publishing to every distribution channel, and updating package registries. From 533a880bb32b435fb0809177f3228cc65c19feb6 Mon Sep 17 00:00:00 2001 From: Mark IJbema Date: Tue, 3 Mar 2026 17:08:52 +0100 Subject: [PATCH 4/4] Update RELEASING.md Co-authored-by: kilo-code-bot[bot] <240665456+kilo-code-bot[bot]@users.noreply.github.com> --- RELEASING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/RELEASING.md b/RELEASING.md index 16b39fcf3e6..ee2e8b465f8 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,6 +1,6 @@ # Releasing Kilo Code -Kilocode uses a fully automated CI pipeline triggered via GitHub Actions `workflow_dispatch`. A single workflow handles version bumping, building all artifacts, publishing to every distribution channel, and updating package registries. +Kilo Code uses a fully automated CI pipeline triggered via GitHub Actions `workflow_dispatch`. A single workflow handles version bumping, building all artifacts, publishing to every distribution channel, and updating package registries. ## How to Trigger a Release