Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

ci(release): enforce reviewed conventional release notes (#616)

mldangelo-oai1ad674b5956c
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 7480d0257..9c1012c63 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,3 +1,5 @@
+<!-- Use a Conventional Commit title: <type>[optional scope][!]: <description>. See RELEASING.md. -->
+
## Summary
<!-- Describe the technical problem and outcome without identifying customers or private systems. -->
diff --git a/.github/release-notes.md b/.github/release-notes.md
new file mode 100644
index 000000000..348394501
--- /dev/null
+++ b/.github/release-notes.md
@@ -0,0 +1,16 @@
+<!-- release-version: 0.1.17 -->
+
+## Highlights
+
+- Split a large repository into explicit or planned components, scan each one
+ independently, and produce a combined coverage report. See
+ [component scans](https://github.com/openai/codex-security/blob/npm-v0.1.17/sdk/typescript/README.md#scan-project-components).
+- Supply validation setup, test, and cleanup steps for standard and diff scans.
+ See
+ [custom validation](https://github.com/openai/codex-security/blob/npm-v0.1.17/sdk/typescript/README.md#custom-validation).
+- Recheck a saved finding without starting another scan. See
+ [finding validation](https://github.com/openai/codex-security/blob/npm-v0.1.17/sdk/typescript/README.md#validate-an-existing-finding).
+
+This release also improves Windows path and process handling, scan result
+reporting, credential lock recovery, and Deep Scan recovery. The categorized
+list below contains the individual changes.
diff --git a/.github/release.yml b/.github/release.yml
index 0fe321195..617d2683a 100644
--- a/.github/release.yml
+++ b/.github/release.yml
@@ -3,6 +3,9 @@ changelog:
labels:
- skip-release-notes
categories:
+ - title: Breaking changes
+ labels:
+ - breaking-change
- title: Features
labels:
- enhancement
diff --git a/.github/workflows/node-ci.yml b/.github/workflows/node-ci.yml
index b8704c94c..2d3bea98a 100644
--- a/.github/workflows/node-ci.yml
+++ b/.github/workflows/node-ci.yml
@@ -4,6 +4,7 @@ on:
push:
branches: [main]
pull_request:
+ types: [opened, edited, reopened, synchronize]
permissions:
contents: read
@@ -13,8 +14,28 @@ concurrency:
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
jobs:
+ validate-title:
+ name: validate pull request title
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Require a Conventional Commit pull request title
+ if: github.event_name == 'pull_request'
+ shell: bash
+ env:
+ PR_TITLE: ${{ github.event.pull_request.title }}
+ run: |
+ set -euo pipefail
+ conventional_title='^([a-z][a-z0-9-]*)(\([a-z0-9][a-z0-9._/-]*\))?(!)?:[ ]([^[:space:]].*[^[:space:]]|[^[:space:]])$'
+ if [[ ! "$PR_TITLE" =~ $conventional_title ]]; then
+ echo "Pull request title must follow <type>[optional scope][!]: <description>." >&2
+ exit 1
+ fi
+
test:
name: ${{ matrix.os }} / node-${{ matrix.node == '22.13.0' && '22' || matrix.node }}
+ needs: validate-title
+ if: always()
runs-on: ${{ matrix.os }}
timeout-minutes: 20
strategy:
@@ -33,6 +54,10 @@ jobs:
node: "26"
steps:
+ - name: Require a valid pull request title
+ if: needs.validate-title.result != 'success'
+ run: exit 1
+
- name: Checkout repository
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
@@ -106,6 +131,7 @@ jobs:
windows-test:
name: windows-latest / node-${{ matrix.node == '22.13.0' && '22' || matrix.node }} / tests-${{ matrix.shard }}
+ needs: validate-title
runs-on: windows-latest
timeout-minutes: 20
strategy:
@@ -164,6 +190,7 @@ jobs:
windows-verify:
name: windows-latest / node-${{ matrix.node == '22.13.0' && '22' || matrix.node }} / verify
+ needs: validate-title
runs-on: windows-latest
timeout-minutes: 20
strategy:
@@ -204,7 +231,7 @@ jobs:
name: windows-latest / node-${{ matrix.node == '22.13.0' && '22' || matrix.node }}
runs-on: ubuntu-latest
if: always()
- needs: [windows-test, windows-verify]
+ needs: [validate-title, windows-test, windows-verify]
strategy:
fail-fast: false
matrix:
@@ -212,5 +239,5 @@ jobs:
steps:
- name: Require every Windows coverage job
- if: needs.windows-test.result != 'success' || needs.windows-verify.result != 'success'
+ if: needs.validate-title.result != 'success' || needs.windows-test.result != 'success' || needs.windows-verify.result != 'success'
run: exit 1
diff --git a/.github/workflows/node-github-release.yml b/.github/workflows/node-github-release.yml
index d8552b357..c556635ae 100644
--- a/.github/workflows/node-github-release.yml
+++ b/.github/workflows/node-github-release.yml
@@ -512,25 +512,10 @@ jobs:
node sdk/typescript/scripts/release-automation.mjs \
verify-github-release "$RELEASE_ARCHIVE" "$RELEASE_TAG" \
"$downloaded_archive"
+ fi
- notes_args=(
- --method POST
- "repos/$GITHUB_REPOSITORY/releases/generate-notes"
- -f "tag_name=$RELEASE_TAG"
- -f "target_commitish=$RELEASE_SHA"
- )
- if git cat-file -e "$RELEASE_SHA:.github/release.yml" 2>/dev/null; then
- notes_args+=(-f "configuration_file_path=.github/release.yml")
- fi
- if [[ -n "$PREVIOUS_TAG" ]]; then
- notes_args+=(-f "previous_tag_name=$PREVIOUS_TAG")
- fi
- generated_notes="$(gh api "${notes_args[@]}" --jq '.body')"
- if [[ -z "$generated_notes" ]]; then
- echo "Generated GitHub release notes must not be empty." >&2
- exit 1
- fi
-
+ existing_notes=""
+ if [[ -n "$existing_release" ]]; then
existing_notes="$(
printf '%s\n' "$existing_release" |
node --input-type=module --eval '
@@ -542,7 +527,89 @@ jobs:
process.stdout.write(release.body ?? "");
'
)"
+ fi
+
+ notes_args=(
+ --method POST
+ "repos/$GITHUB_REPOSITORY/releases/generate-notes"
+ -f "tag_name=$RELEASE_TAG"
+ -f "target_commitish=$RELEASE_SHA"
+ )
+ if git cat-file -e "$RELEASE_SHA:.github/release.yml" 2>/dev/null; then
+ notes_args+=(-f "configuration_file_path=.github/release.yml")
+ fi
+ if [[ -n "$PREVIOUS_TAG" ]]; then
+ notes_args+=(-f "previous_tag_name=$PREVIOUS_TAG")
+ fi
+ generated_notes="$(gh api "${notes_args[@]}" --jq '.body')"
+ if [[ -z "$generated_notes" ]]; then
+ echo "Generated GitHub release notes must not be empty." >&2
+ exit 1
+ fi
+
+ summary_start="<!-- codex-security-release-summary:start -->"
+ summary_end="<!-- codex-security-release-summary:end -->"
+ release_summary=""
+ if git cat-file -e "$RELEASE_SHA:.github/release-notes.md" 2>/dev/null; then
+ release_summary="$(
+ git show "$RELEASE_SHA:.github/release-notes.md"
+ )"
+ summary_header="${release_summary%%$'\n'*}"
+ summary_body="${release_summary#*$'\n'}"
+ expected_header="<!-- release-version: $RELEASE_VERSION -->"
+ if [[ "$summary_header" != "$expected_header" ||
+ "$summary_body" == "$release_summary" ||
+ -z "${summary_body//[[:space:]]/}" ]]; then
+ echo "Release notes must start with $expected_header and include a reviewed summary." >&2
+ exit 1
+ fi
+ elif [[ -n "$existing_notes" ]]; then
+ release_summary="$(
+ printf '%s\n' "$existing_notes" |
+ CODEX_SECURITY_SUMMARY_START="$summary_start" \
+ CODEX_SECURITY_SUMMARY_END="$summary_end" \
+ node --input-type=module --eval '
+ import { readFileSync } from "node:fs";
+ const notes = readFileSync(0, "utf8");
+ const start = process.env.CODEX_SECURITY_SUMMARY_START;
+ const end = process.env.CODEX_SECURITY_SUMMARY_END;
+ const startIndex = notes.indexOf(start);
+ const endIndex = notes.indexOf(end);
+ if (startIndex === -1 && endIndex === -1) process.exit(0);
+ if (
+ startIndex === -1 ||
+ endIndex <= startIndex ||
+ notes.indexOf(start, startIndex + start.length) !== -1 ||
+ notes.indexOf(end, endIndex + end.length) !== -1
+ ) {
+ throw new Error(
+ "Existing release summary markers are malformed.",
+ );
+ }
+ const summary = notes
+ .slice(startIndex + start.length, endIndex)
+ .replace(/^\r?\n/u, "")
+ .replace(/\r?\n$/u, "");
+ if (!/\S/u.test(summary)) {
+ throw new Error("Existing release summary is empty.");
+ }
+ process.stdout.write(summary);
+ '
+ )"
+ fi
+
+ published_notes="$generated_notes"
+ if [[ -n "$release_summary" ]]; then
+ published_notes="$(
+ printf '%s\n%s\n%s\n\n%s' \
+ "$summary_start" \
+ "$release_summary" \
+ "$summary_end" \
+ "$generated_notes"
+ )"
+ fi
+ if [[ -n "$existing_release" ]]; then
latest_response="$(
github_release_or_missing \
"repos/$GITHUB_REPOSITORY/releases/latest" \
@@ -572,16 +639,16 @@ jobs:
currently_latest=true
fi
- if [[ "$existing_notes" != "$generated_notes" ||
+ if [[ "$existing_notes" != "$published_notes" ||
"$currently_latest" != "$MAKE_LATEST" ]]; then
verify_release_tag
- if [[ "$existing_notes" != "$generated_notes" ]]; then
- printf '%s\n' "$generated_notes" |
+ if [[ "$existing_notes" != "$published_notes" ]]; then
+ printf '%s\n' "$published_notes" |
gh release edit "$RELEASE_TAG" \
--repo "$GITHUB_REPOSITORY" \
--latest="$MAKE_LATEST" \
--notes-file -
- echo "Updated existing GitHub Release with generated notes."
+ echo "Updated existing GitHub Release with reviewed and generated notes."
else
gh release edit "$RELEASE_TAG" \
--repo "$GITHUB_REPOSITORY" \
@@ -602,12 +669,9 @@ jobs:
--repo "$GITHUB_REPOSITORY"
--title "Codex Security $RELEASE_VERSION"
--verify-tag
- --generate-notes
+ --notes-file -
--latest="$MAKE_LATEST"
)
- if [[ -n "$PREVIOUS_TAG" ]]; then
- release_args+=(--notes-start-tag "$PREVIOUS_TAG")
- fi
verify_release_tag
- gh release create "${release_args[@]}"
+ printf '%s\n' "$published_notes" | gh release create "${release_args[@]}"
diff --git a/.github/workflows/node-release-cut.yml b/.github/workflows/node-release-cut.yml
index 6edec5634..711fc2772 100644
--- a/.github/workflows/node-release-cut.yml
+++ b/.github/workflows/node-release-cut.yml
@@ -65,6 +65,21 @@ jobs:
fi
version="$(node sdk/typescript/scripts/release-automation.mjs version sdk/typescript/package.json)"
+ if ! release_summary="$(
+ git show "$RELEASE_SHA:.github/release-notes.md" 2>/dev/null
+ )"; then
+ echo "The tagged commit must include .github/release-notes.md." >&2
+ exit 1
+ fi
+ summary_header="${release_summary%%$'\n'*}"
+ summary_body="${release_summary#*$'\n'}"
+ expected_header="<!-- release-version: $version -->"
+ if [[ "$summary_header" != "$expected_header" ||
+ "$summary_body" == "$release_summary" ||
+ -z "${summary_body//[[:space:]]/}" ]]; then
+ echo "Release notes must start with $expected_header and include a reviewed summary." >&2
+ exit 1
+ fi
if ! published_versions="$(
npm view @openai/codex-security versions \
diff --git a/.github/workflows/node-release-labels.yml b/.github/workflows/node-release-labels.yml
index 4bc17b867..9a5903ed1 100644
--- a/.github/workflows/node-release-labels.yml
+++ b/.github/workflows/node-release-labels.yml
@@ -32,17 +32,23 @@ jobs:
set -euo pipefail
release_note_label() {
- case "$1" in
- feat:* | feat\(*\):* | feat!:* | feat\(*\)!:*)
+ local type="$1" breaking_marker="$2"
+ if [[ "$breaking_marker" == "!" ]]; then
+ printf '%s\n' breaking-change
+ return 0
+ fi
+
+ case "$type" in
+ feat)
printf '%s\n' enhancement
;;
- fix:* | fix\(*\):* | fix!:* | fix\(*\)!:*)
+ fix)
printf '%s\n' bug
;;
- docs:* | docs\(*\):* | docs!:* | docs\(*\)!:*)
+ docs)
printf '%s\n' documentation
;;
- release:* | release\(*\):* | release!:* | release\(*\)!:* | test:* | test\(*\):* | test!:* | test\(*\)!:*)
+ release | test)
printf '%s\n' skip-release-notes
;;
*)
@@ -55,7 +61,14 @@ jobs:
gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER" \
--jq '.title'
)"
- label="$(release_note_label "$current_title")"
+ conventional_title='^([a-z][a-z0-9-]*)(\([a-z0-9][a-z0-9._/-]*\))?(!)?:[ ]([^[:space:]].*[^[:space:]]|[^[:space:]])$'
+ if [[ ! "$current_title" =~ $conventional_title ]]; then
+ echo "Pull request title must follow <type>[optional scope][!]: <description>." >&2
+ exit 1
+ fi
+ type="${BASH_REMATCH[1]}"
+ breaking_marker="${BASH_REMATCH[3]:-}"
+ label="$(release_note_label "$type" "$breaking_marker")"
current_labels="$(
gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/labels" \
--jq '.[].name'
@@ -86,7 +99,7 @@ jobs:
label_already_present=false
while IFS= read -r current_label; do
case "$current_label" in
- enhancement | bug | documentation | skip-release-notes)
+ breaking-change | enhancement | bug | documentation | skip-release-notes)
if [[ "$current_label" == "skip-release-notes" &&
"$preserve_skip_label" == true ]]; then
if [[ "$current_label" == "$label" ]]; then
@@ -113,21 +126,35 @@ jobs:
exit 0
fi
- if [[ "$label" == "skip-release-notes" ]]; then
+ ensure_repository_label() {
+ local name="$1" color="$2" description="$3"
if ! gh api \
- "repos/$GITHUB_REPOSITORY/labels/skip-release-notes" \
+ "repos/$GITHUB_REPOSITORY/labels/$name" \
--silent >/dev/null 2>&1; then
if ! gh api --method POST "repos/$GITHUB_REPOSITORY/labels" \
- -f name=skip-release-notes \
- -f color=ededed \
- -f description="Omit internal changes from generated release notes" \
+ -f "name=$name" \
+ -f "color=$color" \
+ -f "description=$description" \
--silent >/dev/null 2>&1; then
gh api \
- "repos/$GITHUB_REPOSITORY/labels/skip-release-notes" \
+ "repos/$GITHUB_REPOSITORY/labels/$name" \
--silent >/dev/null
fi
fi
- fi
+ }
+
+ case "$label" in
+ breaking-change)
+ ensure_repository_label \
+ breaking-change b60205 \
+ "Breaking change called out in generated release notes"
+ ;;
+ skip-release-notes)
+ ensure_repository_label \
+ skip-release-notes ededed \
+ "Omit internal changes from generated release notes"
+ ;;
+ esac
gh api --method POST \
"repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/labels" \
diff --git a/.github/workflows/node-release.yml b/.github/workflows/node-release.yml
index fd17d9fa0..2cf9f3e2f 100644
--- a/.github/workflows/node-release.yml
+++ b/.github/workflows/node-release.yml
@@ -115,6 +115,30 @@ jobs:
printf 'mode=%s\n' "$mode"
} >> "$GITHUB_OUTPUT"
+ - name: Validate reviewed release notes
+ if: steps.release.outputs.mode == 'publish'
+ shell: bash
+ env:
+ RELEASE_VERSION: ${{ steps.release.outputs.version }}
+ run: |
+ set -euo pipefail
+
+ if ! release_summary="$(
+ git show "$GITHUB_SHA:.github/release-notes.md" 2>/dev/null
+ )"; then
+ echo "The tagged commit must include .github/release-notes.md." >&2
+ exit 1
+ fi
+ summary_header="${release_summary%%$'\n'*}"
+ summary_body="${release_summary#*$'\n'}"
+ expected_header="<!-- release-version: $RELEASE_VERSION -->"
+ if [[ "$summary_header" != "$expected_header" ||
+ "$summary_body" == "$release_summary" ||
+ -z "${summary_body//[[:space:]]/}" ]]; then
+ echo "Release notes must start with $expected_header and include a reviewed summary." >&2
+ exit 1
+ fi
+
- name: Install dependencies
run: sfw pnpm --dir sdk/typescript install --frozen-lockfile
diff --git a/.github/workflows/validate-pr-title.yml b/.github/workflows/validate-pr-title.yml
index 3d35cbf8d..846ec8172 100644
--- a/.github/workflows/validate-pr-title.yml
+++ b/.github/workflows/validate-pr-title.yml
@@ -16,8 +16,8 @@ jobs:
env:
PR_TITLE: ${{ github.event.pull_request.title }}
run: |
- pattern='^(build|chore|ci|docs|feat|fix|perf|refactor|release|revert|style|test)(\([^()[:space:]]+\))?!?:[[:space:]][^[:space:]].*$'
- if [[ ! "$PR_TITLE" =~ $pattern ]]; then
- echo '::error::PR titles must use a supported Conventional Commit type.'
+ conventional_title='^([a-z][a-z0-9-]*)(\([a-z0-9][a-z0-9._/-]*\))?(!)?:[ ]([^[:space:]].*[^[:space:]]|[^[:space:]])$'
+ if [[ ! "$PR_TITLE" =~ $conventional_title ]]; then
+ echo '::error::Pull request title must follow <type>[optional scope][!]: <description>.'
exit 1
fi
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 000000000..54c5fb058
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,14 @@
+# Changelog
+
+[GitHub Releases](https://github.com/openai/codex-security/releases) is the
+canonical changelog for Codex Security. Each release page combines a reviewed
+summary with the categorized pull requests included in that version.
+
+Use the [latest release](https://github.com/openai/codex-security/releases/latest)
+for current upgrade notes. The [complete release history](https://github.com/openai/codex-security/releases)
+links every version to its tag, package asset, contributors, and full Git
+comparison.
+
+Maintainers should follow [RELEASING.md](RELEASING.md) when preparing or
+repairing a release. Keeping the detailed history on GitHub avoids maintaining
+two changelogs that can drift apart.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e4e6015f7..029ecd821 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -48,5 +48,9 @@ canonical repository. The public release workflow installs that locked graph,
tests the package, and publishes a verified artifact with npm provenance.
GitHub Actions dependencies are maintained separately in this repository.
+[GitHub Releases](https://github.com/openai/codex-security/releases) is the
+canonical changelog. Maintainers should follow [RELEASING.md](RELEASING.md) to
+prepare, publish, verify, or repair a release.
+
See the [SDK testing guide](sdk/typescript/TESTING.md) for local checks,
test conventions, and the required and experimental CI jobs.
diff --git a/README.md b/README.md
index b53d793ff..b6fb48217 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,9 @@
**See the [Codex Security documentation](https://learn.chatgpt.com/docs/security/cli)** for more details.
+See [GitHub Releases](https://github.com/openai/codex-security/releases) for
+the canonical changelog and upgrade notes.
+
Some cybersecurity requests and protected findings require approval through
Trusted Access for Cyber. To apply or check your access, visit
[chatgpt.com/cyber](https://chatgpt.com/cyber).
diff --git a/RELEASING.md b/RELEASING.md
new file mode 100644
index 000000000..14563c7a2
--- /dev/null
+++ b/RELEASING.md
@@ -0,0 +1,115 @@
+# Releasing Codex Security
+
+[GitHub Releases](https://github.com/openai/codex-security/releases) is the
+canonical changelog. A release combines a short, reviewed summary with a
+categorized list of merged pull requests. The release tag and npm package use
+the same stable version: `npm-vX.Y.Z` and `@openai/[email protected]`.
+
+## Pull request titles and categories
+
+Pull request titles must follow this form:
+
+```text
+<type>[optional scope][!]: <description>
+```
+
+Use a lowercase type and, when present, a lowercase scope. Start the description
+with a non-whitespace character and do not leave trailing whitespace. Examples:
+
+```text
+feat(cli): add component scan planning
+fix(windows): preserve Unicode paths
+docs: explain scan cost limits
+feat(sdk)!: remove the legacy result field
+```
+
+The title controls the generated release category:
+
+| Title | Release category |
+| -------------------- | ---------------- |
+| Any type with `!` | Breaking changes |
+| `feat` | Features |
+| `fix` | Fixes |
+| `docs` | Documentation |
+| `release`, `test` | Excluded |
+| Any other valid type | Other changes |
+
+Use `release` and `test` only for changes that do not affect package users. A
+maintainer can apply `skip-release-notes` to exclude another internal change.
+That manual label takes precedence over the title category.
+
+## Prepare a release
+
+1. Choose the next stable version and update `sdk/typescript/package.json`.
+ Keep the lockfile version in sync when it records the package version.
+2. Update `.github/release-notes.md`. Its first line must be
+ `<!-- release-version: X.Y.Z -->` with the exact package version.
+3. Summarize the changes a user will notice. Call out required migration or
+ compatibility work, link relevant public documentation, and leave the
+ pull-request inventory to the generated section.
+4. Open a pull request with a strict Conventional Commit title such as
+ `release: bump Codex Security to 0.2.0`.
+5. Run the checks required by the changed files and record the results in the
+ pull request. Do not merge until required CI, review, and public disclosure
+ checks pass on the current commit.
+
+Review the summary with the same standard as product documentation. Keep it
+specific, describe behavior before implementation, and do not include private
+repositories, systems, people, findings, links, or issue identifiers.
+
+## Publish
+
+The release starts after the version bump reaches `main` and `node-ci` succeeds
+for that exact commit:
+
+1. `node-release-cut` verifies that the version increased, checks the reviewed
+ summary, and creates the exact `npm-vX.Y.Z` tag.
+2. `node-release` installs the committed dependency graph, tests and packs the
+ package, publishes it to npm, and records npm provenance.
+3. `node-github-release` verifies the public package, provenance, tag, and
+ archive before publishing the GitHub release. It prepends the reviewed
+ summary to GitHub's categorized notes.
+
+Monitor all three workflows. A version bump is not a completed release until
+the npm package and GitHub release both exist and match the tag.
+
+## Verify
+
+Check the published state before announcing the release:
+
+- The tag points to the merged release commit.
+- `npm view @openai/[email protected]` reports the expected version and
+ commit, and the provenance check passed in `node-release`.
+- The GitHub release is stable, has the correct title, and contains exactly one
+ verified package archive.
+- The newest version is marked Latest. A historical backfill is not.
+- The reviewed highlights, category headings, documentation links, and full
+ comparison link are correct.
+- Every merged pull request is included or has an intentional
+ `skip-release-notes` label.
+
+## Recover or repair a release
+
+Do not retarget a release tag or publish a second package under the same
+version. The workflows are designed to recover from partial publication while
+keeping the original tag and package identity.
+
+To retry GitHub publication, run `node-github-release` from `main` with the
+existing `npm-vX.Y.Z` tag. Supply the successful `node-release` run ID when
+automatic lookup is not enough. The workflow verifies the npm artifact and
+provenance again before it creates or updates the release.
+
+To repair categories on an existing release, correct the merged pull request's
+title or release label first, then rerun `node-github-release` for the tag. For
+a release that predates `.github/release-notes.md`, place any reviewed summary
+between these markers before the rerun:
+
+```text
+<!-- codex-security-release-summary:start -->
+Reviewed summary
+<!-- codex-security-release-summary:end -->
+```
+
+The workflow preserves that marked summary and replaces the generated section.
+After any recovery or repair, repeat every verification step above and review
+the final public release body.
diff --git a/sdk/typescript/tests-ts/release-automation.test.ts b/sdk/typescript/tests-ts/release-automation.test.ts
index e69ac613a..79e1847ac 100644
--- a/sdk/typescript/tests-ts/release-automation.test.ts
+++ b/sdk/typescript/tests-ts/release-automation.test.ts
@@ -205,6 +205,14 @@ const releaseLabelsWorkflow = readFileSync(
),
"utf8",
);
+const nodeCiWorkflow = readFileSync(
+ new URL("../../../.github/workflows/node-ci.yml", import.meta.url),
+ "utf8",
+);
+const titleWorkflow = readFileSync(
+ new URL("../../../.github/workflows/validate-pr-title.yml", import.meta.url),
+ "utf8",
+);
function publishedMetadata(): ReleaseMetadata {
return {
@@ -1446,6 +1454,71 @@ describe("GitHub release workflow safeguards", () => {
expect(protectedReleaseWorkflow).toContain('"$GITHUB_REF"');
});
+ test("requires reviewed notes only for new npm publications", () => {
+ expect(protectedReleaseWorkflow).toContain(
+ [
+ " - name: Validate reviewed release notes",
+ " if: steps.release.outputs.mode == 'publish'",
+ ].join("\n"),
+ );
+ });
+
+ test.each([
+ {
+ scenario: "a missing reviewed summary",
+ summary: "__missing__",
+ status: 1,
+ message: "The tagged commit must include .github/release-notes.md.",
+ },
+ {
+ scenario: "a summary for another version",
+ summary: "<!-- release-version: 0.1.5 -->\nReviewed summary",
+ status: 1,
+ message: "Release notes must start with <!-- release-version: 0.1.6 -->",
+ },
+ {
+ scenario: "an empty reviewed summary",
+ summary: "<!-- release-version: 0.1.6 -->\n ",
+ status: 1,
+ message: "Release notes must start with <!-- release-version: 0.1.6 -->",
+ },
+ {
+ scenario: "a matching reviewed summary",
+ summary: "<!-- release-version: 0.1.6 -->\nReviewed summary",
+ status: 0,
+ message: "",
+ },
+ ])(
+ "validates $scenario before protected npm publication",
+ ({ summary, status, message }) => {
+ const script = workflowStepShell(
+ protectedReleaseWorkflow,
+ "Validate reviewed release notes",
+ );
+ const mock = [
+ "git() {",
+ ' if [[ "$MOCK_RELEASE_SUMMARY" == "__missing__" ]]; then return 1; fi',
+ " printf '%s\\n' \"$MOCK_RELEASE_SUMMARY\"",
+ "}",
+ ].join("\n");
+ const result = spawnSync(bash, ["-c", `${mock}\n${script}`], {
+ encoding: "utf8",
+ env: {
+ ...process.env,
+ GITHUB_SHA: releaseCommit,
+ MOCK_RELEASE_SUMMARY: summary,
+ RELEASE_VERSION: "0.1.6",
+ },
+ timeout: 10_000,
+ });
+
+ expect(result.status).toBe(status);
+ if (message !== "") {
+ expect(result.stderr).toContain(message);
+ }
+ },
+ );
+
test("pins both supported-minimum verification and protected signing runtimes", () => {
expect(protectedReleaseWorkflow).toContain('node-version: "22.13.0"');
expect(protectedReleaseWorkflow).toContain('node-version: "24.15.0"');
@@ -1474,7 +1547,12 @@ describe("GitHub release workflow safeguards", () => {
"Resolve the stable package version",
);
const mocks = [
- "git() { return 0; }",
+ "git() {",
+ ' if [[ "$1" == "show" && "$2" == *":.github/release-notes.md" ]]; then',
+ ` printf '%s\\n%s\\n' '<!-- release-version: ${checkedOutVersion} -->' 'Reviewed summary'`,
+ " fi",
+ " return 0",
+ "}",
"npm() { printf '%s\\n' '[\"0.1.1\",\"999999999999999999999999.0.0\"]'; }",
].join("\n");
const result = spawnSync(bash, ["-c", `${mocks}\n${script}`], {
@@ -1548,7 +1626,13 @@ describe("GitHub release workflow safeguards", () => {
' case "$1" in',
" fetch|merge-base) return 0 ;;",
" rev-parse) printf '%s\\n' \"$MOCK_PREVIOUS_SHA\" ;;",
- ' show) printf \'{"version":"%s"}\\n\' "$MOCK_PREVIOUS_VERSION" ;;',
+ " show)",
+ ' if [[ "$2" == *":.github/release-notes.md" ]]; then',
+ " printf '%s\\n%s\\n' \"<!-- release-version: $MOCK_RELEASE_VERSION -->\" 'Reviewed summary'",
+ " else",
+ ' printf \'{"version":"%s"}\\n\' "$MOCK_PREVIOUS_VERSION"',
+ " fi",
+ " ;;",
" *) return 64 ;;",
" esac",
"}",
@@ -1600,6 +1684,64 @@ describe("GitHub release workflow safeguards", () => {
},
);
+ test.each([
+ {
+ scenario: "a missing reviewed summary",
+ summary: "__missing__",
+ message: "The tagged commit must include .github/release-notes.md.",
+ },
+ {
+ scenario: "a summary for another version",
+ summary: "<!-- release-version: 0.1.5 -->\nReviewed summary",
+ message: "Release notes must start with <!-- release-version: 0.1.6 -->",
+ },
+ {
+ scenario: "an empty reviewed summary",
+ summary: "<!-- release-version: 0.1.6 -->\n ",
+ message: "Release notes must start with <!-- release-version: 0.1.6 -->",
+ },
+ ])("rejects $scenario before cutting a tag", ({ summary, message }) => {
+ const script = workflowStepShell(
+ releaseCutWorkflow,
+ "Resolve the stable package version",
+ );
+ const mocks = [
+ "git() {",
+ ' case "$1" in',
+ " fetch|merge-base) return 0 ;;",
+ " show)",
+ ' if [[ "$MOCK_RELEASE_SUMMARY" == "__missing__" ]]; then return 1; fi',
+ " printf '%s\\n' \"$MOCK_RELEASE_SUMMARY\"",
+ " ;;",
+ " *) return 64 ;;",
+ " esac",
+ "}",
+ "node() {",
+ ' if [[ "${2:-}" == "version" ]]; then printf \'%s\\n\' 0.1.6; return 0; fi',
+ ' command node "$@"',
+ "}",
+ "npm() { printf '%s\\n' 'npm history must not be queried' >&2; return 70; }",
+ ].join("\n");
+ const result = spawnSync(bash, ["-c", `${mocks}\n${script}`], {
+ cwd: fileURLToPath(new URL("../../../", import.meta.url)),
+ encoding: "utf8",
+ env: {
+ ...process.env,
+ GITHUB_EVENT_NAME: "workflow_dispatch",
+ GITHUB_OUTPUT: "/dev/null",
+ GITHUB_REF: "refs/heads/main",
+ GITHUB_SHA: releaseCommit,
+ MOCK_RELEASE_SUMMARY: summary,
+ RELEASE_SHA: releaseCommit,
+ },
+ timeout: 10_000,
+ });
+
+ expect(result.status).toBe(1);
+ expect(result.stderr).toContain(message);
+ expect(result.stderr).not.toContain("npm history must not be queried");
+ });
+
test.each([
{
workflow: "release cut",
@@ -1646,7 +1788,12 @@ describe("GitHub release workflow safeguards", () => {
cutting ? "Resolve the stable package version" : "Validate release tag",
);
const mocks = [
- "git() { return 0; }",
+ "git() {",
+ ' if [[ "$1" == "show" && "$2" == *":.github/release-notes.md" ]]; then',
+ " printf '%s\\n%s\\n' \"<!-- release-version: $MOCK_RELEASE_VERSION -->\" 'Reviewed summary'",
+ " fi",
+ " return 0",
+ "}",
"node() {",
' if [[ "${2:-}" == "version" || "${2:-}" == "release-tag" ]]; then',
" printf '%s\\n' \"$MOCK_RELEASE_VERSION\"",
@@ -2505,6 +2652,7 @@ describe("GitHub release workflow safeguards", () => {
' if [[ "$1" == "api" ]]; then',
" shift",
' if [[ "${1:-}" == "--include" ]]; then shift; fi',
+ ' if [[ "${1:-}" == "--method" ]]; then shift 2; fi',
' case "$1" in',
' "repos/test/codex-security/releases/tags/npm-v0.1.2")',
' case "$MOCK_EXISTING_LOOKUP" in',
@@ -2531,6 +2679,9 @@ describe("GitHub release workflow safeguards", () => {
' "repos/test/codex-security/git/tags/"*)',
" printf '%s\\n' \"$MOCK_PEELED_COMMIT\"",
" ;;",
+ ' "repos/test/codex-security/releases/generate-notes")',
+ " printf '%s\\n' 'Generated release notes'",
+ " ;;",
" *) return 65 ;;",
" esac",
' elif [[ "$1" == "release" && "$2" == "create" ]]; then',
@@ -2575,7 +2726,10 @@ describe("GitHub release workflow safeguards", () => {
);
test("explicitly prevents historical releases becoming latest", () => {
- expect(githubReleaseWorkflow).toContain("--generate-notes");
+ expect(githubReleaseWorkflow).toContain(
+ '"repos/$GITHUB_REPOSITORY/releases/generate-notes"',
+ );
+ expect(githubReleaseWorkflow).toContain("--notes-file -");
expect(githubReleaseWorkflow).toContain('--latest="$MAKE_LATEST"');
expect(githubReleaseWorkflow).toContain("release-history");
});
@@ -2588,7 +2742,7 @@ describe("GitHub release workflow safeguards", () => {
"steps.history.outputs.previous-tag",
);
expect(githubReleaseWorkflow).toContain(
- 'release_args+=(--notes-start-tag "$PREVIOUS_TAG")',
+ 'notes_args+=(-f "previous_tag_name=$PREVIOUS_TAG")',
);
});
@@ -2762,6 +2916,49 @@ describe("GitHub release workflow safeguards", () => {
peeledCommit: "",
status: 0,
},
+ {
+ description: "stale generated notes with a marked historical summary",
+ existingNotes:
+ "<!-- codex-security-release-summary:start -->\\n## Highlights\\nPreserved historical summary\\n<!-- codex-security-release-summary:end -->\\n\\nStale generated notes",
+ expectedSummary: "Preserved historical summary",
+ updated: true,
+ latestTag: "npm-v0.1.3",
+ makeLatest: false,
+ latestUpdated: false,
+ tagType: "commit",
+ tagObject: releaseCommit,
+ peeledCommit: "",
+ status: 0,
+ },
+ {
+ description: "generated notes without its tagged reviewed summary",
+ existingNotes: "Generated release notes",
+ releaseSummary:
+ "<!-- release-version: 0.1.2 -->\n## Highlights\nReviewed tagged summary",
+ expectedSummary: "Reviewed tagged summary",
+ updated: true,
+ latestTag: "npm-v0.1.3",
+ makeLatest: false,
+ latestUpdated: false,
+ tagType: "commit",
+ tagObject: releaseCommit,
+ peeledCommit: "",
+ status: 0,
+ },
+ {
+ description: "malformed historical summary markers",
+ existingNotes:
+ "<!-- codex-security-release-summary:start -->\\nIncomplete summary",
+ expectedError: "Existing release summary markers are malformed.",
+ updated: false,
+ latestTag: "npm-v0.1.3",
+ makeLatest: false,
+ latestUpdated: false,
+ tagType: "commit",
+ tagObject: releaseCommit,
+ peeledCommit: "",
+ status: 1,
+ },
{
description: "already current",
existingNotes: "Generated release notes",
@@ -2896,6 +3093,9 @@ describe("GitHub release workflow safeguards", () => {
makeLatest,
latestUpdated,
releaseConfiguration = true,
+ releaseSummary = "__missing__",
+ expectedSummary,
+ expectedError,
tagType,
tagObject,
peeledCommit,
@@ -3006,6 +3206,16 @@ describe("GitHub release workflow safeguards", () => {
' [[ "$MOCK_RELEASE_CONFIGURATION" == "present" ]]',
" return",
" fi",
+ ' if [[ "$1" == "cat-file" && "$2" == "-e" &&',
+ ' "$3" == "$RELEASE_SHA:.github/release-notes.md" ]]; then',
+ ' [[ "$MOCK_RELEASE_SUMMARY" != "__missing__" ]]',
+ " return",
+ " fi",
+ ' if [[ "$1" == "show" &&',
+ ' "$2" == "$RELEASE_SHA:.github/release-notes.md" ]]; then',
+ " printf '%s\\n' \"$MOCK_RELEASE_SUMMARY\"",
+ " return",
+ " fi",
' command git "$@"',
"}",
"node() {",
@@ -3032,6 +3242,7 @@ describe("GitHub release workflow safeguards", () => {
MOCK_RELEASE_CONFIGURATION: releaseConfiguration
? "present"
: "missing",
+ MOCK_RELEASE_SUMMARY: releaseSummary,
MOCK_TAG_OBJECT: tagObject,
MOCK_TAG_TYPE: tagType,
PREVIOUS_TAG: "npm-v0.1.1",
@@ -3046,6 +3257,10 @@ describe("GitHub release workflow safeguards", () => {
expect(result.status).toBe(status);
expect(result.stdout).toContain("verified existing GitHub release asset");
if (status !== 0) {
+ if (expectedError !== undefined) {
+ expect(result.stderr).toContain(expectedError);
+ return;
+ }
const latestLookupFailed = [
"__error__",
"__network__",
@@ -3059,11 +3274,16 @@ describe("GitHub release workflow safeguards", () => {
return;
}
if (updated) {
+ if (expectedSummary !== undefined) {
+ expect(result.stdout).toContain(expectedSummary);
+ expect(result.stdout).toContain("Generated release notes");
+ } else {
+ expect(result.stdout).toContain(
+ "updated release notes: Generated release notes",
+ );
+ }
expect(result.stdout).toContain(
- "updated release notes: Generated release notes",
- );
- expect(result.stdout).toContain(
- "Updated existing GitHub Release with generated notes.",
+ "Updated existing GitHub Release with reviewed and generated notes.",
);
} else if (latestUpdated) {
expect(result.stdout).not.toContain("updated release notes:");
@@ -3110,15 +3330,80 @@ describe("GitHub release workflow safeguards", () => {
'gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER"',
);
expect(releaseLabelsWorkflow).toContain(
- 'label="$(release_note_label "$current_title")"',
+ 'label="$(release_note_label "$type" "$breaking_marker")"',
);
expect(releaseLabelsWorkflow).toContain(
- "enhancement | bug | documentation | skip-release-notes)",
+ "breaking-change | enhancement | bug | documentation | skip-release-notes)",
);
expect(releaseLabelsWorkflow).toContain("gh api --method DELETE");
expect(releaseLabelsWorkflow).toContain("return 0");
});
+ test("enforces the same Conventional Commit title in required CI", () => {
+ const releasePattern = /conventional_title='([^']+)'/u.exec(
+ releaseLabelsWorkflow,
+ )?.[1];
+ const ciPattern = /conventional_title='([^']+)'/u.exec(nodeCiWorkflow)?.[1];
+ const titlePattern = /conventional_title='([^']+)'/u.exec(
+ titleWorkflow,
+ )?.[1];
+
+ expect(releasePattern).toBeDefined();
+ expect(ciPattern).toBe(releasePattern);
+ expect(titlePattern).toBe(releasePattern);
+ expect(nodeCiWorkflow).toContain(
+ "types: [opened, edited, reopened, synchronize]",
+ );
+ expect(nodeCiWorkflow).toContain("needs: validate-title");
+ expect(nodeCiWorkflow).toContain(
+ "needs: [validate-title, windows-test, windows-verify]",
+ );
+ });
+
+ test.each([
+ "[codex] Add a scan feature",
+ "Feat: use an uppercase type",
+ "feat(): use an empty scope",
+ "feat(bad scope): use whitespace in a scope",
+ "feat:no separator space",
+ "feat: use two separator spaces",
+ "feat: leave trailing whitespace ",
+ "feat:",
+ ])("rejects nonconventional pull request title %s", (title) => {
+ const script = workflowStepShell(
+ releaseLabelsWorkflow,
+ "Categorize pull request without checking out its code",
+ );
+ const mock = [
+ "gh() {",
+ ' if [[ "$1" != "api" ]]; then return 64; fi',
+ " shift",
+ ' if [[ "$1" == "repos/test/codex-security/issues/17" ]]; then',
+ " printf '%s\\n' \"$MOCK_PR_TITLE\"",
+ " return 0",
+ " fi",
+ " printf '%s\\n' 'unexpected label mutation'",
+ " return 70",
+ "}",
+ ].join("\n");
+ const result = spawnSync(bash, ["-c", `${mock}\n${script}`], {
+ encoding: "utf8",
+ env: {
+ ...process.env,
+ GITHUB_REPOSITORY: "test/codex-security",
+ MOCK_PR_TITLE: title,
+ PR_NUMBER: "17",
+ },
+ timeout: 10_000,
+ });
+
+ expect(result.status).toBe(1);
+ expect(result.stderr).toContain(
+ "Pull request title must follow <type>[optional scope][!]: <description>.",
+ );
+ expect(result.stdout).not.toContain("unexpected label mutation");
+ });
+
test.each([
{ title: "fix: retitle an internal change", expectedLabel: "bug" },
{ title: "feat: retitle an internal change", expectedLabel: "enhancement" },
@@ -3332,14 +3617,14 @@ describe("GitHub release workflow safeguards", () => {
);
test.each([
- { title: "feat!: breaking feature", label: "enhancement" },
- { title: "feat(api)!: breaking feature", label: "enhancement" },
- { title: "fix!: breaking fix", label: "bug" },
- { title: "fix(api)!: breaking fix", label: "bug" },
- { title: "docs!: breaking documentation", label: "documentation" },
+ { title: "feat!: breaking feature", label: "breaking-change" },
+ { title: "feat(api)!: breaking feature", label: "breaking-change" },
+ { title: "fix!: breaking fix", label: "breaking-change" },
+ { title: "fix(api)!: breaking fix", label: "breaking-change" },
+ { title: "docs!: breaking documentation", label: "breaking-change" },
{
title: "docs(api)!: breaking documentation",
- label: "documentation",
+ label: "breaking-change",
},
])("categorizes breaking-change title $title", ({ title, label }) => {
const script = workflowStepShell(
@@ -3364,6 +3649,9 @@ describe("GitHub release workflow safeguards", () => {
' "GET repos/test/codex-security/issues/17/labels")',
" return 0",
" ;;",
+ ' "GET repos/test/codex-security/labels/breaking-change")',
+ " return 0",
+ " ;;",
' "POST repos/test/codex-security/issues/17/labels")',
" printf '%s\\n' \"$@\"",
" ;;",
diff --git a/sdk/typescript/tests-ts/skeleton.test.ts b/sdk/typescript/tests-ts/skeleton.test.ts
index 1ccf9b86f..2fc79c624 100644
--- a/sdk/typescript/tests-ts/skeleton.test.ts
+++ b/sdk/typescript/tests-ts/skeleton.test.ts
@@ -117,7 +117,11 @@ describe("TypeScript package skeleton", () => {
expect(jobs["windows"]?.name).toBe(
"windows-latest / node-${{ matrix.node == '22.13.0' && '22' || matrix.node }}",
);
- expect(jobs["windows"]?.needs).toEqual(["windows-test", "windows-verify"]);
+ expect(jobs["windows"]?.needs).toEqual([
+ "validate-title",
+ "windows-test",
+ "windows-verify",
+ ]);
expect(jobs["windows-test"]?.strategy?.matrix["node"]).toEqual([
"22.13.0",
"24",