feat: adopt changesets for automated versioning and publishing (#6)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: alerizzo

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

.changeset/config.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.3/schema.json",
+  "changelog": [
+    "@changesets/changelog-github",
+    { "repo": "codacy/codacy-cloud-cli" }
+  ],
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.changeset/fresh-spoons-build.md

@@ -0,0 +1,2 @@
+---
+---

.github/workflows/ci.yml

@@ -37,3 +37,25 @@ jobs:
 
       - name: Test
         run: npm test
+
+  changeset-check:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+
+      - name: Check for changesets
+        run: |
+          # Count .changeset/*.md files added/modified in this PR compared to the base branch
+          CHANGESETS=$(git diff --name-only origin/${{ github.base_ref }}...HEAD -- '.changeset/*.md' ':!.changeset/README.md' | wc -l)
+          if [ "$CHANGESETS" -eq 0 ]; then
+            echo "::error::No changeset found for this PR. Run 'npx changeset' to describe your changes."
+            echo ""
+            echo "If this PR does not require a version bump (e.g., docs-only or CI changes),"
+            echo "add an empty changeset with: npx changeset --empty"
+            exit 1
+          fi
+          echo "Found $CHANGESETS changeset file(s) changed in this PR."

.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+          cache: npm
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate API client
+        run: npm run update-api
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Create Release PR or Publish
+        uses: changesets/action@6a0a831ff30acef54f2c6aa1cbbc1096b066edaf # v1
+        with:
+          publish: npm run release
+          title: "chore: version packages"
+          commit: "chore: version packages"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_CONFIG_PROVENANCE: true

.github/workflows/release.yml

@@ -24,6 +24,7 @@ This CLI wraps the [Codacy Cloud API v3](https://api.codacy.com/api/api-docs) us
 
 ```
 codacy-cloud-cli/
+├── .changeset/                  # Changesets config and pending changeset files
 ├── src/
 │   ├── index.ts                 # CLI entry point (Commander.js setup)
 │   ├── api/
@@ -173,6 +174,35 @@ The `SPECS/` folder at the project root is the single source of truth for specs
 4. Update `SPECS/README.md` (mark tasks done, add changelog entry) when completing work
 5. Add new tasks to `SPECS/README.md` pending table when discovered during work
 
+## Versioning & Releasing
+
+This project uses [changesets](https://github.com/changesets/changesets) for versioning and npm publishing.
+
+### How it works
+
+1. Every PR must include a changeset file (CI enforces this via the `changeset-check` job)
+2. Run `npx changeset` to create one — select the bump type (`patch`, `minor`, `major`) and describe the change
+3. For PRs that don't need a version bump (docs, CI, refactors), use `npx changeset --empty`
+4. On merge to `main`, the `release.yml` workflow creates a "chore: version packages" PR that bumps the version and updates `CHANGELOG.md`
+5. Merging that PR triggers the actual npm publish with provenance
+
+### Agent responsibilities for changesets
+
+When completing work that changes user-facing behavior or adds features, agents **must**:
+1. Run `npx changeset` and create an appropriate changeset file before committing
+2. Use `patch` for bug fixes, `minor` for new features or commands, `major` for breaking changes
+3. Write a clear, user-facing summary in the changeset (this becomes the CHANGELOG entry)
+
+For internal-only changes (refactors, docs, CI, test-only changes), use `npx changeset --empty`.
+
+### Agent responsibilities for self-documenting changes
+
+When completing work, agents **must** update relevant documentation:
+1. **`SPECS/README.md`** — mark tasks as done in the pending table, add a changelog entry
+2. **`README.md`** — if a new command was added or renamed, update the commands summary table (one row per command, no detailed args/options)
+3. **`AGENTS.md`** — if a new convention, pattern, or workflow was introduced that affects how agents work, add it to the relevant section
+4. **`SPECS/deployment.md`** — if CI/CD or publishing workflows changed, update this spec to match
+
 ## Environment Variables
 
 | Variable | Required | Description |

AGENTS.md

@@ -89,14 +89,17 @@ npm run update-api       # Update the auto-generated API client
 ### CI/CD
 
 - **CI**: Runs on every push to `main` and on PRs. Builds and tests across Node.js 18, 20, and 22.
-- **Publish**: Triggered on GitHub release creation. Builds, tests, and publishes to npm with provenance.
+- **Release**: Uses [changesets](https://github.com/changesets/changesets) for automated versioning and npm publishing.
 
-To publish a new version:
-1. Update the version in `package.json`
-2. Create a GitHub release with a tag matching the version (e.g. `v1.1.0`)
-3. The publish workflow will automatically build and push to npm
+#### Publishing a new version
 
-**Prerequisite**: Add an `NPM_TOKEN` secret to your GitHub repository settings.
+1. When making changes, run `npx changeset` and describe your change (select `patch`, `minor`, or `major`)
+2. Include the generated `.changeset/*.md` file in your PR
+3. CI enforces that every PR includes a changeset (use `npx changeset --empty` for changes that don't need a version bump, like docs or CI)
+4. When PRs are merged to `main`, the release workflow automatically creates a **"chore: version packages"** PR that bumps the version and updates `CHANGELOG.md`
+5. Merging that PR publishes to npm with provenance
+
+**Prerequisite**: An `NPM_TOKEN` secret must be configured in the GitHub repository settings.
 
 ## License
 

README.md

@@ -1,13 +1,13 @@
 # Deployment & CI Spec
 
-**Status:** ✅ Done (2026-02-18)
+**Status:** ✅ Done (updated 2026-05-08)
 
 ## npm Package
 
 - **Binary name:** `codacy` (registered in `package.json` under `bin`)
 - **Included files:** `dist/` and `README.md` (via `files` field)
-- **Pre-publish:** `prepublishOnly` runs `npm run build` using `tsconfig.build.json`
-- **Engines:** requires Node.js >= 18
+- **Pre-publish:** `prepublishOnly` runs `npm run update-api && npm run build` as a safety net for local publishes
+- **Engines:** requires Node.js >= 20
 - **Install globally:** `npm install -g "@codacy/codacy-cloud-cli"`
 
 ## GitHub Actions
@@ -18,23 +18,26 @@ Triggers on: push and pull requests to `main`.
 
 Matrix: Node.js 18, 20, 22.
 
-Steps:
-1. Checkout
-2. Setup Node
-3. `npm ci`
-4. `npm run build`
-5. `npm test`
+Jobs:
+- **build-and-test**: checkout → setup node → install → generate API client → type check → build → test
+- **changeset-check** (PRs only): verifies at least one `.changeset/*.md` file is present in the PR diff
+
+### Release (`release.yml`)
 
-### Publish to npm (`publish.yml`)
+Triggers on: push to `main`.
 
-Triggers on: GitHub release published.
+Uses the [changesets/action](https://github.com/changesets/changesets) to automate versioning and publishing.
 
 Steps:
 1. Checkout
 2. Setup Node with `registry-url: https://registry.npmjs.org`
 3. `npm ci`
-4. `npm run build`
-5. `npm publish` (uses `NODE_AUTH_TOKEN` secret)
+4. Generate API client (`npm run update-api`)
+5. Build (`npm run build`)
+6. Test (`npm test`)
+7. `changesets/action` — either:
+   - Creates/updates a "chore: version packages" PR (bumps version, updates CHANGELOG.md)
+   - If that PR was just merged, runs `changeset publish` to publish to npm with provenance
 
 ## Homebrew Formula
 
@@ -44,5 +47,5 @@ Planned for future distribution as a separate brew formula for macOS/Linux/Windo
 
 | Secret | Used by |
 |---|---|
-| `NODE_AUTH_TOKEN` | npm publish workflow |
+| `NPM_TOKEN` | Release workflow (`NODE_AUTH_TOKEN` for npm publish) |
 | `CODACY_API_TOKEN` | CLI runtime (env var, not a secret in CI) |