Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 18 additions & 20 deletions docs/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,45 +63,43 @@ If the commit or version changes, the job stops and must be started again.
A GitHub Actions success alone from an unchecked run is a dry-run, not
evidence of npm publication.

## Single-maintainer exception — v1.15.6 only
## Single-maintainer release

A project with one authorized repository maintainer may release **v1.15.6 only**
without inventing a second GitHub reviewer, but this is **not** an implicit
override of CI or governance approvals:
While Kucell is the sole collaborator with write access, the maintainer uses
the single-maintainer release path after the required CI checks pass.
GitHub Actions checks the collaborator list before publication.

1. The canonical private governance `/release` Decision must be genuinely
`approved`, `resolved_by=interactive-user`, `workflow_gate=user`,
`type=approval`, selected option **`approve-single-maintainer`**, and
`options` must explicitly include that option. Its `rationale` must mention
`single-maintainer` and `v1.15.6`.
`single-maintainer` and the exact package version, for example `v1.16.0`.
2. A matching `released` Waitpoint must be released by `/release` with
`workflow_gate=owner`. Both records must bind to the **actual current main**
using `release:cortex-agent@<mainSHA>`; prior 1.15.0 release records are invalid
for this candidate.
3. The release-preparation PR must really have merged, modify only reviewed
metadata/verification paths, and its merge SHA must be an ancestor of current
main. It need not equal current main when later safe fixes landed. Any
`CHANGES_REQUESTED` review blocks the waiver.
using `release:cortex-agent@<mainSHA>`.
3. The release-preparation PR must modify only the allowed release paths and
its merge SHA must match current main. For the transition to this policy,
v1.16.0 may use [PR #190](https://github.com/Kucell/cortex-agent/pull/190)
at its pinned merge commit `9cdf6ae9978dad96de1594465a0010d3dbf0a02d`
when that commit is an ancestor of the authorized main commit. A
`CHANGES_REQUESTED` review blocks the single-maintainer path.
4. The release-workflow preflight, exact-head tests, packaging, npm/tag
collision checks and effect-time authority checks remain mandatory.
This exception does not change GitHub permissions, npm Trusted Publishing
or the Auto Release opt-in variable.
5. Future versions require independent reviewer approval unless a separately
reviewed policy explicitly extends this exception. A chat message or PR
comment does not create authoritative Decision/Waitpoint records.
GitHub permissions, npm Trusted Publishing and the Auto Release opt-in
variable continue to apply.

The existing independent-review path remains the default when selected option
is `approve`. **Do not falsify an APPROVED GitHub Review to activate this mode.**
When more collaborators have write access, use the independent-review path
with the Decision option `approve`.

## Approval-driven release

- **Automatic preflight:** `.github/workflows/npm-release-preflight.yml` runs after version-file changes land on `main`. This workflow has read-only permissions, runs architecture/contract tests and `npm pack --dry-run`, and never publishes.
- **Publish trigger:** the owner dispatches `npm-release.yml` from `main` with `publish=true` and the governance inputs listed above. Publication always runs under the `workflow_dispatch` event, because npm Trusted Publishing rejects OIDC tokens minted for `issue_comment` runs.
- **Credential prerequisite:** configure a read-only credential in secret `CORTEX_GOVERNANCE_READ_TOKEN` capable of reading the private `Kucell/cortex-agent-agent` Decision/Waitpoint files. Prefer a short-lived GitHub App installation token; do not use npm tokens or put credentials in versioned files.
- The release gate must verify the exact main commit, actual merged release-preparation PR (matching main or an ancestor in the explicitly approved v1.15.6 single-maintainer mode), accepted file scope, private interactive-user-approved Decision and owner-released Waitpoint for the exact main, and current package version. An ordinary approval requires a distinct write-authorized reviewer; the explicit v1.15.6 `approve-single-maintainer` mode waives only this reviewer identity requirement. Active `CHANGES_REQUESTED` is never waived.
- The release gate verifies the exact main commit, the merged release-preparation PR, allowed file scope, current package version, a private interactive-user-approved Decision and an owner-released Waitpoint. With the `approve` option, a distinct reviewer with write access must approve the exact PR head. With `approve-single-maintainer`, GitHub must report Kucell as the sole collaborator with write access.
- **Input format:** `release_pr` is the merged release-preparation PR number, `expected_sha` is the exact current `main` SHA, and `decision_id` / `waitpoint_id` are the IDs created by the authoritative `/release` owner after the exact-commit dry-run / approval process. Do not confuse a GitHub PR comment with the authoritative Cortex Decision/Waitpoint itself.
- Failure to verify anything (including unavailable private governance credential) blocks publication; no fallback to simulated approvals or `--force`.
- Publisher remains `npm-release.yml` with npm Trusted Publishing/OIDC. Publication uses `release_type=current`, `dist_tag=latest` and the existing validations/retry logic. **Manual dispatch is the only publication path; `publish=true` is not an authorization bypass.** It requires the same live private Decision + released Waitpoint, independent write-authorized review, and exact-head verification.
- The owner dispatches `npm-release.yml` with `release_type=current`, `dist_tag=latest` and `publish=true`. npm Trusted Publishing uses the resulting OIDC identity. The workflow verifies the live private Decision and released Waitpoint, the exact source commit, and the applicable review path above.

**Important:** A pull request that adds this automation cannot activate the trigger until it is separately reviewed and merged. The publish path is owner-dispatched and fail-closed; do not weaken the gate without a separately reviewed policy.

Expand Down
54 changes: 33 additions & 21 deletions scripts/release/verify-approved-release.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,13 @@ const MATCH = /^\/cortex-release publish v(\d+\.\d+\.\d+) decision=(D-[A-Za-z0-9
// the changelog and the consistency test that guards the carrier versions.
const { carrierFiles } = require(path.join(__dirname, "..", "..", "lib", "release", "version-carriers"));
const ALLOWED = new Set([...carrierFiles(), "pnpm-lock.yaml", "CHANGELOG.md", "tests/release/release-version-consistency.test.js"]);
// The single-maintainer exception is bound to one exact release version. The
// binding lives in a single constant because it used to be hardcoded twice —
// once in the command check and once in the Decision-rationale pattern — and
// the two must name the same version or the waiver becomes unusable.
const SINGLE_MAINTAINER_EXCEPTION_VERSION = "1.15.6";
const SINGLE_MAINTAINER_EXCEPTION_VERSION_RE = new RegExp(
SINGLE_MAINTAINER_EXCEPTION_VERSION.replace(/\./g, "\\."),
);
// Metadata for 1.16.0 was merged before the single-maintainer policy.
// Later releases must use a metadata PR merged at the current main commit.
const SINGLE_MAINTAINER_TRANSITION = Object.freeze({
version: "1.16.0",
number: 190,
mergeSha: "9cdf6ae9978dad96de1594465a0010d3dbf0a02d",
});
function must(ok, reason) { if (!ok) throw new Error("RELEASE_GATE_BLOCKED: " + reason); }
function parseCommand(body) {
const m = String(body || "").trim().match(MATCH);
Expand All @@ -42,17 +41,20 @@ function hasIndependentApproval(pr, reviews, eligibleReviewers = null) {
(eligibleReviewers === null || eligibleReviewers.has(r.user.login.toLowerCase())) &&
r.commit_id === pr.head.sha);
}
function validateGovernance(decision, waitpoint, sha, now=new Date()) {
function validateGovernance(decision, waitpoint, sha, now=new Date(), version) {
const target = "release:cortex-agent@" + sha;
const waiver = decision.selected_option === "approve-single-maintainer";
const rationaleVersion = /^\d+\.\d+\.\d+$/.test(version)
? new RegExp("\\bv" + version.replace(/\./g, "\\.") + "(?![\\w+-]|\\.\\d)")
: null;
must(decision.type === "approval" && decision.status === "approved" &&
(decision.selected_option === "approve" || waiver) &&
(!waiver || (
Array.isArray(decision.options) &&
decision.options.includes("approve-single-maintainer") &&
typeof decision.rationale === "string" &&
/single-maintainer/i.test(decision.rationale) &&
SINGLE_MAINTAINER_EXCEPTION_VERSION_RE.test(decision.rationale)
rationaleVersion && rationaleVersion.test(decision.rationale)
)) &&
decision.resolved_by === "interactive-user" && decision.workflow_gate === "user" &&
decision.resolved_at && Number.isFinite(Date.parse(decision.resolved_at)) &&
Expand Down Expand Up @@ -143,19 +145,29 @@ async function verifyApproval({event,eventName="issue_comment",actor="Kucell",re
const decision = decode(await getJson(base+"/decisions/"+command.decision+".json?ref=main",governanceToken,http));
const waitpoint = decode(await getJson(base+"/waitpoints/"+command.waitpoint+".json?ref=main",governanceToken,http));
must(decision.decision_id === command.decision && waitpoint.waitpoint_id === command.waitpoint,"governance ID mismatch");
validateGovernance(decision,waitpoint,mainSha,now);
validateGovernance(decision,waitpoint,mainSha,now,command.version);
const waiver = decision.selected_option === "approve-single-maintainer";
if (waiver) {
must(command.version === SINGLE_MAINTAINER_EXCEPTION_VERSION,
"single-maintainer exception limited to v" + SINGLE_MAINTAINER_EXCEPTION_VERSION);
// A reviewed metadata PR can precede later main commits. The actual release
// approval still binds to the newest exact main SHA (not the stale PR SHA).
const comparison = await getJson(api+"/compare/"+
encodeURIComponent(pr.merge_commit_sha)+"..."+encodeURIComponent(mainSha),repoToken,http);
must(["ahead","identical"].includes(comparison.status) && comparison.behind_by === 0,
"approved release PR is not an ancestor of current main");
const collaborators = await getJson(api+"/collaborators?per_page=100",repoToken,http);
must(Array.isArray(collaborators) && collaborators.length < 100 &&
collaborators.every(row=>row && typeof row.login === "string" &&
row.permissions && typeof row.permissions.push === "boolean"),
"complete collaborator evidence required for single-maintainer release");
const writers = collaborators.filter(row=>row.permissions.push);
must(writers.length === 1 && writers[0].login === actor,
"single-maintainer release requires the repository owner to be the sole writer");
if (pr.merge_commit_sha !== mainSha) {
must(command.version === SINGLE_MAINTAINER_TRANSITION.version &&
pr.number === SINGLE_MAINTAINER_TRANSITION.number &&
pr.merge_commit_sha === SINGLE_MAINTAINER_TRANSITION.mergeSha,
"release preparation PR merge SHA differs from current main");
const comparison = await getJson(api+"/compare/"+
encodeURIComponent(pr.merge_commit_sha)+"..."+encodeURIComponent(mainSha),repoToken,http);
must(["ahead","identical"].includes(comparison.status) && comparison.behind_by === 0,
"approved release PR is not an ancestor of current main");
}
must(!reviews.some(r=>r.state === "CHANGES_REQUESTED"),
"unresolved PR change request forbids review waiver");
"PR change request blocks single-maintainer release");
} else {
must(pr.merge_commit_sha === mainSha, "release PR merge digest differs from current HEAD");
must(hasIndependentApproval(pr,reviews,eligible),
Expand All @@ -174,4 +186,4 @@ async function main() {
console.log("Governed release gate verified exact HEAD "+result.sha+" from merged PR #"+result.pr);
}
if (require.main === module) main().catch(e=>{console.error(e.message);process.exitCode=1;});
module.exports = {parseCommand,hasIndependentApproval,validateGovernance,resolveReleaseTrigger,verifyApproval,ALLOWED,SINGLE_MAINTAINER_EXCEPTION_VERSION};
module.exports = {parseCommand,hasIndependentApproval,validateGovernance,resolveReleaseTrigger,verifyApproval,ALLOWED};
Loading
Loading