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

fix(release): publish matching Action releases with metadata (#1711)

Michael D'Angelo393996b8858a
diff --git a/.github/workflows/node-github-release.yml b/.github/workflows/node-github-release.yml
index f3b62cfad..75fc6faa4 100644
--- a/.github/workflows/node-github-release.yml
+++ b/.github/workflows/node-github-release.yml
@@ -667,21 +667,45 @@ jobs:
fi
cp github-action/build/release-manifest.json "$RUNNER_TEMP/action-release-manifest.json"
cp github-action/build/sbom.cdx.json "$RUNNER_TEMP/action-sbom.cdx.json"
- existing_assets="$(gh release view "npm-v$RELEASE_VERSION" --repo "$GITHUB_REPOSITORY" --json assets --jq '.assets[].name')"
- comparison="$(mktemp -d)"
- trap 'rm -rf "$comparison"' EXIT
- for asset in action-release-manifest.json action-sbom.cdx.json; do
- if grep -Fxq "$asset" <<< "$existing_assets"; then
- gh release download "npm-v$RELEASE_VERSION" --repo "$GITHUB_REPOSITORY" \
- --pattern "$asset" --dir "$comparison"
- if ! cmp "$RUNNER_TEMP/$asset" "$comparison/$asset"; then
- echo "Published Action metadata differs: $asset" >&2
+ action_tag="action-v$RELEASE_VERSION"
+ if release_state="$(gh release view "$action_tag" --repo "$GITHUB_REPOSITORY" --json isDraft,assets)"; then
+ existing_assets="$(jq -r '.assets[].name' <<< "$release_state")"
+ is_draft="$(jq -r '.isDraft' <<< "$release_state")"
+ comparison="$(mktemp -d)"
+ trap 'rm -rf "$comparison"' EXIT
+ for asset in action-release-manifest.json action-sbom.cdx.json; do
+ if grep -Fxq "$asset" <<< "$existing_assets"; then
+ gh release download "$action_tag" --repo "$GITHUB_REPOSITORY" \
+ --pattern "$asset" --dir "$comparison"
+ if ! cmp "$RUNNER_TEMP/$asset" "$comparison/$asset"; then
+ echo "Published Action metadata differs: $asset" >&2
+ exit 1
+ fi
+ elif [[ "$is_draft" == true ]]; then
+ gh release upload "$action_tag" --repo "$GITHUB_REPOSITORY" "$RUNNER_TEMP/$asset"
+ else
+ echo "Published Action release is missing metadata: $asset" >&2
exit 1
fi
- else
- gh release upload "npm-v$RELEASE_VERSION" --repo "$GITHUB_REPOSITORY" "$RUNNER_TEMP/$asset"
+ done
+ if [[ "$is_draft" == true ]]; then
+ gh release edit "$action_tag" --repo "$GITHUB_REPOSITORY" --draft=false --latest=false
fi
- done
+ else
+ notes="$RUNNER_TEMP/action-release-notes.md"
+ {
+ printf 'GitHub Action for [Codex Security %s](%s/%s/releases/tag/npm-v%s).\n\n' \
+ "$RELEASE_VERSION" "$GITHUB_SERVER_URL" "$GITHUB_REPOSITORY" "$RELEASE_VERSION"
+ printf 'Installs `@openai/codex-security@%s`.\n\n' "$RELEASE_VERSION"
+ printf '```yaml\nuses: %s@%s # %s\n```\n' \
+ "$GITHUB_REPOSITORY" "$(git rev-parse HEAD)" "$action_tag"
+ } > "$notes"
+ # gh attaches both assets to a draft before publishing the immutable release.
+ gh release create "$action_tag" \
+ "$RUNNER_TEMP/action-release-manifest.json" "$RUNNER_TEMP/action-sbom.cdx.json" \
+ --repo "$GITHUB_REPOSITORY" --verify-tag --latest=false \
+ --title "Codex Security GitHub Action $RELEASE_VERSION" --notes-file "$notes"
+ fi
{
printf '### Codex Security %s\n\n' "$RELEASE_VERSION"
printf 'CLI source: `%s`\n\n' "$RELEASE_SHA"
diff --git a/RELEASING.md b/RELEASING.md
index 589777b7e..4d87b3f8f 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -6,8 +6,10 @@ short, reviewed summary with a categorized list of merged pull requests.
Historical releases may contain generated notes only. The release tag and npm
package use the same stable version: `npm-vX.Y.Z` and
`@openai/[email protected]`. Releases whose source includes the GitHub Action
-also publish `action-vX.Y.Z`, which installs that exact CLI version. The Action's
-manifest and SBOM accompany the npm archive on the same GitHub Release.
+also publish a companion `action-vX.Y.Z` GitHub Release, which installs that
+exact CLI version. The npm release contains the package archive and canonical
+changelog. The Action release contains its manifest and SBOM, links to that
+changelog, and lists the full distribution commit SHA for consumers to pin.
## Pull request titles and categories
@@ -111,8 +113,9 @@ if the last review targets an older head.
The proposal updates the SDK version and the Action version in
`github-action/package.json` and `github-action/package-lock.json` together.
-The Action's runtime dependency and lockfile keep their previously published
-CLI version until npm publishes the proposed version. Release packaging then
+The Action's runtime dependency and lockfile keep an already published CLI
+baseline until npm publishes the proposed version. This development baseline
+does not necessarily track the latest CLI release. Release packaging then
updates that pin and lockfile to the verified publication. This lets release
PRs run CI while the next npm version is still unavailable; `node-ci` also
tests the Action against the packed CLI candidate before publication.
@@ -221,7 +224,7 @@ Generated PRs leave the disclosure attestations unchecked for maintainer review.
1. Choose the next stable version and update `sdk/typescript/package.json`,
`github-action/package.json`, and both root version fields in
`github-action/package-lock.json`. The rolling release PR normally prepares
- these changes. Keep the Action runtime pin on the previously published CLI;
+ these changes. Keep the Action runtime pin on its published CLI baseline;
release packaging updates it after npm publication.
2. Update `.github/release-notes.md`. Its first line must be
`<!-- release-version: X.Y.Z -->` with the exact package version.
@@ -261,9 +264,11 @@ for that exact commit:
permissions. A fresh publisher checks out the same
source, downloads only the tested runtime lock by artifact ID, and rebuilds
and verifies the bundles without executing the CLI. It creates
- `action-vX.Y.Z` and uploads the Action release manifest and SBOM to the
- existing `npm-vX.Y.Z` GitHub Release. A final status job reports publication,
- installation smoke, and Action results.
+ `action-vX.Y.Z` and publishes a companion GitHub Release with the Action
+ manifest and SBOM attached before publication makes those assets immutable.
+ The companion links to the `npm-vX.Y.Z` changelog and lists the full Action
+ distribution commit SHA. It is never marked Latest. A final status job
+ reports publication, installation smoke, and Action results.
The Action tag points to a generated distribution commit whose parent is the
CLI release commit. That additional commit contains the runnable Action bundle
@@ -304,13 +309,16 @@ Check the published state before announcing the release:
- `npm-vX.Y.Z` 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 one verified
- npm package archive plus the Action manifest and SBOM when applicable.
+- The npm GitHub Release is stable, has the correct title, and contains one
+ verified npm package archive.
- The exact-version published installation checks succeeded.
- For releases with the Action, `action-vX.Y.Z` points to the distribution
commit recorded in its manifest, whose parent is the CLI release commit.
- The manifest and runtime lock identify the same CLI version and npm integrity.
-- The newest version is marked Latest. A historical backfill is not.
+ Its companion GitHub Release contains the manifest and SBOM, links to the
+ npm changelog, and lists that full distribution commit SHA. The manifest and
+ runtime lock identify the same CLI version and npm integrity.
+- The newest npm release is marked Latest. Action releases and historical
+ backfills are not.
- For releases created under this process, the reviewed highlights, category
headings, documentation links, and full comparison link are correct.
Historical releases may have generated notes only.
@@ -349,10 +357,15 @@ If `action-vX.Y.Z` already exists, recovery checks its package manifests and
lockfiles against the reviewed source and CLI release identity before installing
dependencies or running package scripts. It then reuses that distribution commit.
Do not move that tag or regenerate the release from newer Action source.
-A failure after npm publication can leave
-the npm package or GitHub Release visible while later checks or Action
-publication remain incomplete; use the final workflow status to identify the
-remaining work.
+The workflow verifies existing Action release assets and can finish a partial
+draft before publishing it. It does not replace assets on a published release.
+
+For example, if `npm-v0.4.0` is already immutable and its Action publication
+failed, rerun `node-github-release` from `main` with `tag: npm-v0.4.0`. The retry
+creates the missing `action-v0.4.0` companion release without adding or replacing
+assets on the npm release. A failure after npm publication can leave the npm
+package or GitHub Release visible while later checks or Action publication
+remain incomplete; use the final workflow status to identify the remaining work.
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
diff --git a/github-action/README.md b/github-action/README.md
index 05ec83b42..02497952b 100644
--- a/github-action/README.md
+++ b/github-action/README.md
@@ -13,8 +13,8 @@ with access to the selected model. OpenAI is the default provider. See
Add your API key as a repository secret named `CODEX_SECURITY_API_KEY`, then
save this workflow in `.github/workflows/codex-security.yml`.
Replace `REPLACE_WITH_REVIEWED_COMMIT` with the full SHA of an Action commit.
-The matching `action-vX.Y.Z` tag and distribution commit are listed in each
-product release after the CLI and Action have both passed release checks.
+The matching `action-vX.Y.Z` release lists the full distribution commit SHA
+and links to the product changelog after the Action has passed release checks.
When using a fork, replace `openai` with the fork owner.
This example requests Daybreak Blue. Use an API key from a project with Blue
@@ -429,9 +429,10 @@ Validation checks types, tests, Action metadata, documentation, and bundle
reproducibility. CI also tests the result adapter against the pinned CLI and its
SARIF exporter using synthetic scans, runs the packaged Linux smoke test, and
audits the Action and CLI dependency locks. The `@openai/codex-security` dependency in
-`runtime/package.json` is the installed CLI version source. Main keeps the last
-published CLI pin so its checks remain runnable while a release PR prepares the
-next product version. To upgrade that development pin, update it and regenerate
+`runtime/package.json` is the installed CLI version source. Main keeps an already
+published CLI baseline so its checks remain runnable while a release PR prepares
+the next product version. This development pin does not necessarily track the
+latest CLI release. To upgrade it, update it and regenerate
`runtime/package-lock.json`, rebuild the bundles, and run validation.
Releases use the product version from `sdk/typescript/package.json`. Before npm
@@ -445,12 +446,16 @@ runs the Action checks in a job with read-only repository permissions.
A fresh publisher takes only the tested runtime lock, rebuilds
from the same source, and verifies the bundle hashes without executing the CLI.
It creates a distribution commit and an immutable `action-vX.Y.Z` tag with the
-same version as `npm-vX.Y.Z`.
+same version as `npm-vX.Y.Z`. The companion Action release includes the manifest
+and SBOM before publication, lists the full distribution commit SHA, and links
+to the npm release's canonical changelog. It is never marked Latest.
The Action distribution commit differs from the CLI source commit because the
registry integrity lock is finalized after publication. Release metadata records
both commits, both tags, and the verified CLI integrity. A failed Action stage
-can be rerun without republishing npm. Existing version tags are never moved.
+can be rerun without republishing npm or changing its immutable release assets.
+Recovery verifies existing Action assets and can finish a partial draft release.
+Existing version tags are never moved.
See [the release process](../RELEASING.md) for the orchestration and recovery flow.
<!-- prettier-ignore-start -->
diff --git a/sdk/typescript/tests-ts/action-release-workflow.test.ts b/sdk/typescript/tests-ts/action-release-workflow.test.ts
index 0d2b7ac0a..509169705 100644
--- a/sdk/typescript/tests-ts/action-release-workflow.test.ts
+++ b/sdk/typescript/tests-ts/action-release-workflow.test.ts
@@ -616,55 +616,134 @@ test("detects Action support from the release commit during historical recovery"
expect(current.output).toBe("present=true\n");
});
-function publicationFixture(existingManifest: string) {
+type PublishedRelease = {
+ isDraft: boolean;
+ assets: Record<string, string>;
+};
+
+const actionAssets = {
+ "action-release-manifest.json": "verified manifest\n",
+ "action-sbom.cdx.json": "verified SBOM\n",
+};
+
+function publicationFixture(existingRelease: PublishedRelease | null) {
const release = fixture();
+ const distribution = release.distribution();
+ release.git("checkout", "--detach", distribution);
const runner = join(release.directory, "runner");
- const remote = join(release.directory, "published assets");
- const uploads = join(release.directory, "uploads");
+ const state = join(release.directory, "release.json");
+ const calls = join(release.directory, "calls.jsonl");
+ const github = join(release.directory, "github.cjs");
mkdirSync(runner);
- mkdirSync(remote);
- writeFileSync(uploads, "");
+ writeFileSync(state, JSON.stringify(existingRelease));
+ writeFileSync(calls, "");
release.write(
"github-action/build/release-manifest.json",
- "verified manifest\n",
+ actionAssets["action-release-manifest.json"],
+ );
+ release.write(
+ "github-action/build/sbom.cdx.json",
+ actionAssets["action-sbom.cdx.json"],
);
- release.write("github-action/build/sbom.cdx.json", "verified SBOM\n");
- writeFileSync(join(remote, "action-release-manifest.json"), existingManifest);
- const fakeGitHub = `gh() {
- case "$1 $2" in
- 'release view')
- for asset in "$REMOTE_ASSETS/"*; do basename "$asset"; done
- ;;
- 'release download')
- local asset destination
- while [[ $# -gt 0 ]]; do
- case "$1" in
- --pattern) asset="$2"; shift ;;
- --dir) destination="$2"; shift ;;
- esac
- shift
- done
- cp "$REMOTE_ASSETS/$asset" "$destination/$asset"
- ;;
- 'release upload')
- local asset="$(basename "\${!#}")"
- cp "\${!#}" "$REMOTE_ASSETS/$asset"
- printf '%s\\n' "$asset" >> "$UPLOADS"
- ;;
- *) return 1 ;;
- esac
+ writeFileSync(
+ github,
+ `const assert = require("node:assert/strict");
+const { appendFileSync, readFileSync, writeFileSync } = require("node:fs");
+const { basename, join } = require("node:path");
+const [program, ...args] = process.argv.slice(2);
+if (program === "jq") {
+ const value = JSON.parse(readFileSync(0, "utf8"));
+ assert.equal(args[0], "-r");
+ if (args[1] === ".isDraft") console.log(value.isDraft);
+ else if (args[1] === ".assets[].name") {
+ for (const asset of value.assets) console.log(asset.name);
+ } else throw new Error("Unexpected jq filter: " + args[1]);
+ process.exit(0);
}
+appendFileSync(process.env.GITHUB_CALLS, JSON.stringify(args) + "\\n");
+assert.equal(args[0], "release");
+assert.equal(args[2], "action-v99.1.2");
+const option = (name) => args[args.indexOf(name) + 1];
+assert.equal(option("--repo"), "example/security-tool");
+let state = JSON.parse(readFileSync(process.env.RELEASE_STATE, "utf8"));
+switch (args[1]) {
+ case "view":
+ if (state === null) process.exit(1);
+ assert.equal(option("--json"), "isDraft,assets");
+ console.log(JSON.stringify({
+ isDraft: state.isDraft,
+ assets: Object.keys(state.assets).map((name) => ({ name })),
+ }));
+ break;
+ case "download": {
+ const asset = option("--pattern");
+ assert.ok(Object.hasOwn(state.assets, asset));
+ writeFileSync(join(option("--dir"), asset), state.assets[asset]);
+ break;
+ }
+ case "create": {
+ assert.equal(state, null, "Cannot replace an existing release");
+ assert.ok(args.includes("--verify-tag"));
+ assert.ok(args.includes("--latest=false"));
+ assert.equal(option("--title"), "Codex Security GitHub Action 99.1.2");
+ const assets = args.slice(3, args.indexOf("--repo"));
+ assert.deepEqual(assets.map((asset) => basename(asset)).sort(), [
+ "action-release-manifest.json", "action-sbom.cdx.json",
+ ]);
+ state = {
+ isDraft: false,
+ assets: Object.fromEntries(assets.map((asset) => [basename(asset), readFileSync(asset, "utf8")])),
+ notes: readFileSync(option("--notes-file"), "utf8"),
+ };
+ break;
+ }
+ case "upload": {
+ assert.equal(state.isDraft, true, "Published release assets are immutable");
+ const path = args.at(-1);
+ const asset = basename(path);
+ assert.ok(!Object.hasOwn(state.assets, asset), "Cannot replace existing metadata");
+ state.assets[asset] = readFileSync(path, "utf8");
+ break;
+ }
+ case "edit":
+ assert.equal(state.isDraft, true, "Published releases are immutable");
+ assert.ok(args.includes("--draft=false"));
+ assert.ok(args.includes("--latest=false"));
+ assert.deepEqual(Object.keys(state.assets).sort(), [
+ "action-release-manifest.json", "action-sbom.cdx.json",
+ ]);
+ state.isDraft = false;
+ break;
+ default: throw new Error("Unexpected release command: " + args[1]);
+}
+writeFileSync(process.env.RELEASE_STATE, JSON.stringify(state));
+`,
+ );
+ const fakeGitHub = `gh() { node "$GITHUB_FIXTURE" gh "$@"; }
+jq() { node "$GITHUB_FIXTURE" jq "$@"; }
`;
return {
- remote,
- uploads,
+ distribution,
+ state() {
+ return JSON.parse(readFileSync(state, "utf8")) as PublishedRelease & {
+ notes?: string;
+ };
+ },
+ commands() {
+ return readFileSync(calls, "utf8")
+ .trim()
+ .split("\n")
+ .map((line) => (JSON.parse(line) as string[])[1]);
+ },
run() {
return release.run(`${fakeGitHub}${publish}`, {
EXISTING: "true",
RUNNER_TEMP: runner.replaceAll("\\", "/"),
- REMOTE_ASSETS: remote.replaceAll("\\", "/"),
- UPLOADS: uploads.replaceAll("\\", "/"),
+ GITHUB_FIXTURE: github.replaceAll("\\", "/"),
+ GITHUB_CALLS: calls.replaceAll("\\", "/"),
+ RELEASE_STATE: state.replaceAll("\\", "/"),
GITHUB_REPOSITORY: "example/security-tool",
+ GITHUB_SERVER_URL: "https://github.com",
GITHUB_STEP_SUMMARY: join(release.directory, "summary.md").replaceAll(
"\\",
"/",
@@ -674,35 +753,119 @@ function publicationFixture(existingManifest: string) {
};
}
-test("completes partial Action metadata publication and reuses matching assets", () => {
- const publication = publicationFixture("verified manifest\n");
- expect(publication.run().status).toBe(0);
- expect(readFileSync(publication.uploads, "utf8")).toBe(
- "action-sbom.cdx.json\n",
+test("recovers an existing Action tag by creating its companion release with both metadata assets", () => {
+ const publication = publicationFixture(null);
+ const result = publication.run();
+ expect(result.status, result.stderr).toBe(0);
+ expect(publication.commands()).toEqual(["view", "create"]);
+ expect(publication.state()).toMatchObject({
+ isDraft: false,
+ assets: actionAssets,
+ });
+ expect(publication.state().notes).toContain(
+ "https://github.com/example/security-tool/releases/tag/npm-v99.1.2",
);
- expect(
- readFileSync(join(publication.remote, "action-sbom.cdx.json"), "utf8"),
- ).toBe("verified SBOM\n");
- expect(publication.run().status).toBe(0);
- expect(readFileSync(publication.uploads, "utf8")).toBe(
- "action-sbom.cdx.json\n",
+ expect(publication.state().notes).toContain(
+ `uses: example/security-tool@${publication.distribution}`,
);
+
+ const retry = publication.run();
+ expect(retry.status, retry.stderr).toBe(0);
+ expect(publication.commands()).toEqual([
+ "view",
+ "create",
+ "view",
+ "download",
+ "download",
+ ]);
});
-test("rejects mismatched published Action metadata without replacing it", () => {
- const publication = publicationFixture("different published manifest\n");
+const draftAssetSets: Record<string, string>[] = [
+ {},
+ {
+ "action-release-manifest.json":
+ actionAssets["action-release-manifest.json"],
+ },
+ actionAssets,
+];
+
+test.each(draftAssetSets)(
+ "completes an existing Action release draft before publishing it: %j",
+ (assets) => {
+ const publication = publicationFixture({ isDraft: true, assets });
+ const result = publication.run();
+ expect(result.status, result.stderr).toBe(0);
+ expect(publication.state()).toEqual({
+ isDraft: false,
+ assets: actionAssets,
+ });
+ expect(publication.commands()).toEqual([
+ "view",
+ Object.hasOwn(assets, "action-release-manifest.json")
+ ? "download"
+ : "upload",
+ Object.hasOwn(assets, "action-sbom.cdx.json") ? "download" : "upload",
+ "edit",
+ ]);
+ },
+);
+
+test("reuses identical published Action metadata without changing the immutable release", () => {
+ const publication = publicationFixture({
+ isDraft: false,
+ assets: actionAssets,
+ });
const result = publication.run();
- expect(result.status).not.toBe(0);
- expect(result.stderr).toContain("Published Action metadata differs");
- expect(readFileSync(publication.uploads, "utf8")).toBe("");
- expect(
- readFileSync(
- join(publication.remote, "action-release-manifest.json"),
- "utf8",
- ),
- ).toBe("different published manifest\n");
+ expect(result.status, result.stderr).toBe(0);
+ expect(publication.commands()).toEqual(["view", "download", "download"]);
+ expect(publication.state()).toEqual({ isDraft: false, assets: actionAssets });
});
+test.each(
+ [false, true].flatMap((isDraft) =>
+ Object.keys(actionAssets).map((asset) => ({ isDraft, asset })),
+ ),
+)(
+ "rejects mismatched $asset without replacing it (draft=$isDraft)",
+ ({ isDraft, asset }) => {
+ const assets = {
+ ...actionAssets,
+ [asset]: "different published metadata\n",
+ };
+ const publication = publicationFixture({ isDraft, assets });
+ const result = publication.run();
+ expect(result.status).not.toBe(0);
+ expect(result.stderr).toContain("Published Action metadata differs");
+ expect(publication.commands()).toEqual(
+ asset === "action-release-manifest.json"
+ ? ["view", "download"]
+ : ["view", "download", "download"],
+ );
+ expect(publication.state()).toEqual({ isDraft, assets });
+ },
+);
+
+test.each(Object.keys(actionAssets))(
+ "rejects published metadata missing %s without attempting an immutable upload",
+ (missing) => {
+ const assets = Object.fromEntries(
+ Object.entries(actionAssets).filter(([asset]) => asset !== missing),
+ );
+ const publication = publicationFixture({ isDraft: false, assets });
+ const result = publication.run();
+ expect(result.status).not.toBe(0);
+ expect(result.stderr).toContain(
+ "Published Action release is missing metadata",
+ );
+ expect(publication.commands()).toEqual(
+ missing === "action-release-manifest.json"
+ ? ["view"]
+ : ["view", "download"],
+ );
+ expect(publication.state()).toEqual({ isDraft: false, assets });
+ },
+);
+
test.each([
["success", "success", "success", "true", true],
["success", "success", "skipped", "", true],