chore: manual release process (#1305)

# 🔒 Implement Simple Manual Release Process with Security Fixes

Example release PR created from release command:
#1307

**Problem**: The existing automated release workflow used `lerna
version` commands that pushed commits directly to the `master` branch,
bypassing code review processes and branch protection rules. The new
Policy bot makes this fail, as every commit to master requires approval.

## 📋 Summary

This PR implements a streamlined manual release process that eliminates
direct master branch commits while maintaining simplicity and
reliability. The new process requires only 3 steps:

1. **Release**: `yarn release` (creates PR automatically)
2. **Review**: Review and approve the generated PR
3. **Publish**: Merge PR → packages automatically publish to NPM

## 🔧 Changes Made

### New Files Added

- **`scripts/create-release-pr.js`** - Automated script that creates
release PRs
- **`.github/workflows/publish-on-merge.yaml`** - New workflow for safe
publishing
- **`docs/MANUAL_RELEASE_DESIGN.md`** - Complete documentation of new
process

### Files Modified

- **`package.json`** - Added `yarn release` command
- **`lerna.json`** - Security fixes: removed master from allowBranch,
added push/gitTagVersion protections
- **`.github/workflows/release.yaml`** - Disabled old workflow (renamed
to `.disabled`)

## 🚀 New Release Workflow

### For Release Managers

First time only:
```bash
brew install gh
gh auth login
```

Then:
```bash
# Simple 3-step process
git checkout master && git pull origin master
yarn release
# → Review PR → Merge → Auto-publish ✨
```


### What Happens Automatically

1. **`yarn release`** calculates versions and creates PR with changes
2. **PR merge** triggers publishing workflow
3. **`lerna publish from-package`** publishes to NPM and creates git
tags

## 🛡️ Technical Details

### Lerna Configuration Security Fixes

```json
{
  "allowBranch": ["release/*"], // Removed "master"
  "push": false, // Prevents automatic pushing
  "gitTagVersion": false // Prevents automatic tagging
}
```

## 📚 Documentation

Complete implementation guide available in
`docs/MANUAL_RELEASE_DESIGN.md` including:

- Step-by-step usage instructions
- Security configuration requirements
- Emergency procedures
- Troubleshooting guide

## ⚠️ Required Setup (Post-Merge)

**Enable Branch Protection**:
   - Require PR reviews for master branch
   - Prevent direct pushes (including from administrators)

---------

Co-authored-by: Christian Roligheten <christian.roligheten@cognite.com>

Author: danlevings

.github/workflows/publish-on-merge.yaml

@@ -0,0 +1,34 @@
+name: Publish on Release PR Merge
+
+on:
+  push:
+    branches: [master]
+    paths: ['packages/*/package.json']
+
+jobs:
+  publish:
+    if: contains(github.event.head_commit.message, 'chore(release): publish new package versions')
+    runs-on: ubuntu-latest
+    environment: production
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Build packages
+        run: yarn build
+
+      - name: Configure NPM
+        run: echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" >> .npmrc
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}
+
+      - name: Publish to NPM
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: lerna publish from-package --yes --no-git-reset

.github/workflows/release.yaml

@@ -0,0 +1,42 @@
+name: Validate Release PR
+
+on:
+  pull_request:
+    branches: [master]
+
+jobs:
+  validate-release:
+    if: startsWith(github.head_ref, 'release/automated-')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Validate release branch base
+        run: |
+          # Get the merge-base (common ancestor) of this branch and master
+          MERGE_BASE=$(git merge-base HEAD origin/master)
+          MASTER_HEAD=$(git rev-parse origin/master)
+
+          # Check if this branch was created from current master HEAD
+          if [ "$MERGE_BASE" != "$MASTER_HEAD" ]; then
+            echo "❌ Release branch was not created from current master HEAD"
+            echo "Branch base: $MERGE_BASE"
+            echo "Master HEAD: $MASTER_HEAD"
+            echo ""
+            echo "This release branch is based on outdated master."
+            echo "Please close this PR and create a fresh one with 'yarn release'"
+            exit 1
+          fi
+
+          # Additional check: ensure no merge commits from master
+          MERGE_COMMITS=$(git log --merges --grep="Merge.*master" --oneline | wc -l)
+          if [ "$MERGE_COMMITS" -gt 0 ]; then
+            echo "❌ Release branch contains merge commits from master"
+            echo "This invalidates version calculations."
+            echo "Please close this PR and create a fresh one with 'yarn release'"
+            exit 1
+          fi
+
+          echo "✅ Release branch is properly based on current master"

.github/workflows/validate-release-pr.yaml

@@ -75,50 +75,57 @@ Once the change is pushed to the master branch, it is time for a release.
 
 ## Releases & Versioning
 
-Releases are done from the master branch, so when a pull request is merged,
-CI/CD will run tests, and if successful, do deploys.
-Documentation is built and deployed, and code snippets
-are exported to the service contract repo as a pull request.
-
-Updating and uploading npm packages only happens if the HEAD commit of the master branch
-contains `[release]` in its description and the PR title starts with `feat` or `fix`.
-When CI/CD sees this, it will use lerna to update
-package versions of changed packages based on commit messages, and add the
-changes to the changelogs. The changes are comitted to the master branch
-with the new versions as git tags, and the new package versions are uploaded to npm.
-
-We restrict new npm releases to `[release]`-tagged commits because lerna is
-quite aggressive in its versioning. Changes to any file not ignored by lerna will
-cause a PATCH bump. Markdown files and tests are ignored, but changing anything else,
-like a comment in a source file, will trigger a new version,
-irrespective of conventional commits.
-
-This does _not_ mean you should store unfinished work on the master branch.
-Another package may be ready for release, and once a `[release]`
-commit is pushed, all changed packages are updated.
-Repository administrators should be in control of `[release]` commits.
-
-To add a release commit to a clean working tree, use the command
+**We use a simple manual release process for enhanced security and control.**
+
+### How to Release
+
+Releases are initiated manually but executed automatically through pull requests:
 
 ```bash
+# 1. Pull latest master and run release command
 git checkout master
-git pull
-git commit --allow-empty -m "chore: trigger [release]"
-git push
+git pull origin master
+yarn release
+
+# 2. Review the generated PR in GitHub UI
+# 3. Merge PR → packages automatically publish to NPM
 ```
 
-If you want to push the empty commit to master via a pull request,
-use a squash merge (not rebase+ff). Otherwise GitHub will ignore the empty PR.
+### What Happens
+
+1. **`yarn release`** - Calculates version bumps using conventional commits and creates a PR with:
+
+   - Updated `package.json` versions for changed packages
+   - Generated changelog entries
+   - Automatic branch creation and push
+
+2. **PR Review** - Review the version changes and release notes in the generated PR
+
+3. **Auto-publish** - When the PR is merged to master:
+   - Packages are built and published to NPM
+   - Git tags are created automatically
+   - GitHub releases are generated
+
+### Security Features
 
-Also, keep in mind that the `[release]` commit has to be the HEAD of
-master, and Github Action only runs on the HEAD. If HEAD has changed by the time
-the versioning happens, Github Action will fail.
+- ✅ **No direct master pushes** - All changes go through PR review
+- ✅ **Manual approval required** - Human oversight for every release
+- ✅ **Clear audit trail** - Every release documented in PR history
+- ✅ **Branch protection compatible** - Works with strict branch protection rules
 
-In order to perform a major release by merging a release candidate branch to master by keeping the same major version in release candidate version.
+### Prerequisites
 
-- Create a PR from release-* to master
-- Make a PR title and the message when merging to be ` chore(): details [release]`
-- The release tag is to trigger the release of the package.
+- Repository must have `production` environment configured for manual approval
+- `NPM_PUBLISH_TOKEN` secret must be available
+
+### Emergency Releases
+
+Use the same process - no exceptions. The security model ensures all releases are reviewable:
+
+```bash
+yarn release  # Create emergency release PR
+# Review → Merge → Auto-publish
+```
 
 ## Patching older major versions
 
@@ -196,7 +203,9 @@ We have multiple utilities to easy pagination handling. The first entrypoint is
   ```
 - autoPagingEach
   ```ts
-  for await (const asset of client.assets.list().autoPagingEach({ limit: Infinity })) {
+  for await (const asset of client.assets
+    .list()
+    .autoPagingEach({ limit: Infinity })) {
     // ...
   }
   ```
@@ -221,6 +230,7 @@ We offer users to get hold of the HTTP response status code and headers through
 ### Cognite Clients
 
 There is a Cognite Client per SDK package:
+
 - [Core](./packages/core/src/baseCogniteClient.ts)
 - [Stable](./packages/stable/src/cogniteClient.ts)
 - [Beta](./packages/beta/src/cogniteClient.ts)
@@ -229,7 +239,6 @@ There is a Cognite Client per SDK package:
 
 The Core one is the base, meaning the others extends from it.
 
-
 #### Authentication
 
 The authentication logic lives in the [core BaseCogniteClient](./packages/core/src/baseCogniteClient.ts).
@@ -239,4 +248,4 @@ The SDK will call this method when:
 
 - The user calls `authenticate` on the client.
 - The SDK receives a 401 from the API.
-  When multiple requests receives a 401, then only a single call to `oidcTokenProvider` will be invoked. All requests will wait for `oidcTokenProvider` to resolve/reject. If it's resolved, then all the requests will retry before returning the response to the SDK caller. However, if the resolved access token matches the original access token, then no retry will be performed.
+  When multiple requests receives a 401, then only a single call to `oidcTokenProvider` will be invoked. All requests will wait for `oidcTokenProvider` to resolve/reject. If it's resolved, then all the requests will retry before returning the response to the SDK caller. However, if the resolved access token matches the original access token, then no retry will be performed.

CONTRIBUTING.md

@@ -10,7 +10,9 @@
         "**/*.test.ts"
       ],
       "message": "chore(release): publish new package versions [skip ci]",
-      "allowBranch": ["master", "release-*"]
+      "allowBranch": ["release/*"],
+      "push": false,
+      "gitTagVersion": false
     }
   }
 }

lerna.json

@@ -51,6 +51,7 @@
     "test-snippets": "yarn allsdk test-snippets --stream",
     "test-samples": "SKIP_PREFLIGHT_CHECK=true yarn allsamples test --stream",
     "codegen": "ts-node packages/codegen/src/cli.ts",
+    "release": "node scripts/create-release-pr.js",
     "prepare": "husky"
   },
   "devDependencies": {