Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: pin release tags to the tree CI verified (#10945)

Adam Eivy9070dab6b93e
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index f25a365cd1..9825dc8250 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -125,6 +125,14 @@ jobs:
echo "exists=false" >> $GITHUB_OUTPUT
fi
+ # A tag that already exists is never retargeted by the release action, so
+ # it must already sit on the tree CI verified. Fails closed, read-only.
+ - name: Verify existing release tag matches this tree
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ RELEASE_TAG: v${{ steps.package-version.outputs.version }}
+ run: node scripts/verify-release-tag.js
+
- name: Generate changelog
id: changelog
if: steps.release-check.outputs.exists == 'false'
@@ -211,11 +219,22 @@ jobs:
tag_name: v${{ steps.package-version.outputs.version }}
name: ${{ steps.changelog.outputs.release_title }}
body_path: ${{ steps.changelog.outputs.body_path }}
+ # Create a missing tag at the exact commit CI verified. Without this
+ # GitHub resolves a new tag against main's tip, which can have moved.
+ target_commitish: ${{ github.sha }}
draft: false
prerelease: false
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ - name: Confirm published tag is on the verified tree
+ if: steps.release-check.outputs.exists == 'false'
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ RELEASE_TAG: v${{ steps.package-version.outputs.version }}
+ REQUIRE_TAG: 'true'
+ run: node scripts/verify-release-tag.js
+
- name: Archive changelog on main
run: |
CURRENT_VERSION=${{ steps.package-version.outputs.version }}
diff --git a/docs/GITHUB_ACTIONS.md b/docs/GITHUB_ACTIONS.md
index 5cb4317a70..b4538c6bb4 100644
--- a/docs/GITHUB_ACTIONS.md
+++ b/docs/GITHUB_ACTIONS.md
@@ -903,6 +903,18 @@ Everything else fails closed and runs the complete suite again: a direct push to
`release`, a hotfix committed on `release` that changes the merge tree, a
missing, failed, or merely impact-scoped gate, or an unreachable checks API.
+### Pinning the release tag to the verified tree
+
+The release action creates a missing tag at the repository default branch
+unless told otherwise, and main may have advanced since CI verified the release
+push. `release.yml` therefore passes `target_commitish: ${{ github.sha }}`, and
+`scripts/verify-release-tag.js` covers the case the input cannot: a tag that
+already exists is peeled (annotated tags included) and its commit's tree must
+equal the released tree. A different tree, a non-commit target, or any lookup
+GitHub does not answer fails the job; the script is read-only and never moves
+or deletes a tag. It runs again after publication to confirm the new tag landed
+on the verified tree.
+
## Working with CI
### Skip CI
diff --git a/scripts/verify-release-tag.js b/scripts/verify-release-tag.js
new file mode 100644
index 0000000000..01762b470c
--- /dev/null
+++ b/scripts/verify-release-tag.js
@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+// Guards the release tag against drifting off the tree CI verified.
+//
+// `softprops/action-gh-release` creates a missing tag at the repository's
+// default branch unless it is told otherwise, and ignores its target entirely
+// when the tag already exists. release.yml therefore pins `target_commitish` to
+// the triggering SHA for the missing-tag case, and runs this script for the
+// other one: when `v<version>` already exists, it is peeled (annotated tags
+// included) to its commit and that commit's TREE must equal the tree being
+// released. A same-tree commit with a different SHA (a main merge parent) is
+// fine; anything else — different tree, unexpected object type, or any lookup
+// that cannot be answered — fails the release. This script only reads: it
+// never creates, moves, or deletes a tag.
+//
+// Run again after publication with REQUIRE_TAG=true to prove the tag now exists
+// on the verified tree (closes the window where something else created it
+// between the first check and the release).
+
+import { spawnSync } from 'child_process';
+import { isDirectlyInvoked } from './lib/directInvocation.js';
+import { writeStepOutput } from './lib/githubOutput.js';
+
+const MAX_TAG_DEPTH = 5;
+
+/**
+ * Resolve an existing tag to its commit's tree and compare with `headTree`.
+ *
+ * @param {object} args
+ * @param {string} args.tag full tag name, e.g. `v1.2.3`
+ * @param {string|null} args.headTree tree SHA of the checked-out release commit
+ * @param {(path: string) => {status: number, body: any}|null} args.api GET against
+ * `repos/<repo>/...`; null = the request could not be answered
+ * @returns {{ok: boolean, exists: boolean, reason: string}}
+ */
+export function checkReleaseTag({ tag, headTree, api }) {
+ const fail = (reason) => ({ ok: false, exists: true, reason });
+ if (!headTree) return fail('the release commit tree could not be resolved');
+
+ const ref = api(`git/ref/tags/${encodeURIComponent(tag)}`);
+ if (!ref) return fail(`the lookup of tag ${tag} could not be answered`);
+ if (ref.status === 404) return { ok: true, exists: false, reason: `tag ${tag} does not exist yet` };
+ if (ref.status !== 200 || ref.body?.ref !== `refs/tags/${tag}`) {
+ return fail(`the lookup of tag ${tag} returned an unusable answer (HTTP ${ref.status})`);
+ }
+
+ let object = ref.body.object;
+ for (let depth = 0; depth < MAX_TAG_DEPTH; depth += 1) {
+ if (!object?.sha || typeof object.type !== 'string') return fail(`tag ${tag} points at an unreadable object`);
+ if (object.type === 'tag') {
+ const tagObject = api(`git/tags/${object.sha}`);
+ if (tagObject?.status !== 200) return fail(`annotated tag ${tag} could not be read`);
+ object = tagObject.body?.object;
+ continue;
+ }
+ if (object.type !== 'commit') return fail(`tag ${tag} points at a ${object.type}, not a commit`);
+ const commit = api(`git/commits/${object.sha}`);
+ const tagTree = commit?.status === 200 ? commit.body?.tree?.sha : null;
+ if (!tagTree) return fail(`the commit behind tag ${tag} could not be read`);
+ if (tagTree !== headTree) {
+ return fail(`tag ${tag} points at tree ${tagTree.slice(0, 8)}, not the verified release tree ${headTree.slice(0, 8)}`);
+ }
+ return { ok: true, exists: true, reason: `tag ${tag} points at the verified release tree` };
+ }
+ return fail(`tag ${tag} is nested more than ${MAX_TAG_DEPTH} tag objects deep`);
+}
+
+// `gh api` exits non-zero on any HTTP error and names the status on stderr; a
+// 404 is an answer ("no such tag"), everything else unparseable is not.
+function ghApi(repo, path) {
+ const result = spawnSync('gh', ['api', `repos/${repo}/${path}`], { encoding: 'utf8' });
+ if (result.error) return null;
+ if (result.status === 0) {
+ try {
+ return { status: 200, body: JSON.parse(result.stdout) };
+ } catch {
+ return null;
+ }
+ }
+ return /HTTP 404/.test(result.stderr || '') ? { status: 404, body: null } : null;
+}
+
+function main() {
+ const repo = process.env.GITHUB_REPOSITORY;
+ const sha = process.env.GITHUB_SHA;
+ const tag = process.env.RELEASE_TAG;
+ const requireTag = process.env.REQUIRE_TAG === 'true';
+
+ const treeResult = sha ? spawnSync('git', ['rev-parse', `${sha}^{tree}`], { encoding: 'utf8' }) : null;
+ const headTree = treeResult?.status === 0 ? treeResult.stdout.trim() : null;
+
+ const result = !repo || !tag
+ ? { ok: false, exists: true, reason: 'missing repository or release tag name' }
+ : checkReleaseTag({ tag, headTree, api: (path) => ghApi(repo, path) });
+ const ok = result.ok && (result.exists || !requireTag);
+ const reason = result.ok && !result.exists && requireTag
+ ? `tag ${tag} was not found after publication`
+ : result.reason;
+
+ writeStepOutput('tag_exists', result.exists);
+ if (!ok) {
+ console.error(`❌ ${reason}`);
+ console.log(`::error::release ${tag || ''} blocked: ${reason}`);
+ process.exit(1);
+ }
+ console.log(`✅ ${reason}`);
+}
+
+if (isDirectlyInvoked(import.meta.url)) main();
diff --git a/scripts/verify-release-tag.test.js b/scripts/verify-release-tag.test.js
new file mode 100644
index 0000000000..bbb7eb90b0
--- /dev/null
+++ b/scripts/verify-release-tag.test.js
@@ -0,0 +1,89 @@
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+import { describe, expect, it } from 'vitest';
+
+import { workflowJobs } from './lib/workflowJobs.js';
+import { checkReleaseTag } from './verify-release-tag.js';
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+const TAG = 'v1.2.3';
+const TESTED_TREE = 'a'.repeat(40);
+const MAIN_TREE = 'b'.repeat(40);
+
+// A fake GitHub: refs maps path -> {status, body}; anything absent is unanswerable.
+const fakeApi = (routes) => (path) => routes[path] ?? null;
+const tagRef = (object) => ({ status: 200, body: { ref: `refs/tags/${TAG}`, object } });
+const commitRoute = (sha, tree) => ({ [`git/commits/${sha}`]: { status: 200, body: { tree: { sha: tree } } } });
+
+describe('checkReleaseTag', () => {
+ it('lets a missing tag through so the pinned target creates it', () => {
+ const api = fakeApi({ [`git/ref/tags/${TAG}`]: { status: 404, body: null } });
+ expect(checkReleaseTag({ tag: TAG, headTree: TESTED_TREE, api })).toMatchObject({ ok: true, exists: false });
+ });
+
+ it('accepts a lightweight tag on a different commit with the same tree', () => {
+ const api = fakeApi({
+ [`git/ref/tags/${TAG}`]: tagRef({ type: 'commit', sha: 'mainparent' }),
+ ...commitRoute('mainparent', TESTED_TREE),
+ });
+ expect(checkReleaseTag({ tag: TAG, headTree: TESTED_TREE, api })).toMatchObject({ ok: true, exists: true });
+ });
+
+ it('peels an annotated tag before comparing trees', () => {
+ const api = fakeApi({
+ [`git/ref/tags/${TAG}`]: tagRef({ type: 'tag', sha: 'tagobj' }),
+ 'git/tags/tagobj': { status: 200, body: { object: { type: 'commit', sha: 'c1' } } },
+ ...commitRoute('c1', TESTED_TREE),
+ });
+ expect(checkReleaseTag({ tag: TAG, headTree: TESTED_TREE, api }).ok).toBe(true);
+ });
+
+ it('fails a tag that landed on main after it advanced (different tree)', () => {
+ const api = fakeApi({
+ [`git/ref/tags/${TAG}`]: tagRef({ type: 'commit', sha: 'maintip' }),
+ ...commitRoute('maintip', MAIN_TREE),
+ });
+ const result = checkReleaseTag({ tag: TAG, headTree: TESTED_TREE, api });
+ expect(result.ok).toBe(false);
+ expect(result.reason).toContain('not the verified release tree');
+ });
+
+ it.each([
+ ['the tag lookup is unavailable', {}],
+ ['the tag lookup is a server error', { [`git/ref/tags/${TAG}`]: { status: 500, body: null } }],
+ ['the answer is for a different ref', { [`git/ref/tags/${TAG}`]: { status: 200, body: { ref: 'refs/tags/v1.2.30', object: { type: 'commit', sha: 'x' } } } }],
+ ['the tag points at a tree', { [`git/ref/tags/${TAG}`]: tagRef({ type: 'tree', sha: 'x' }) }],
+ ['the commit cannot be read', { [`git/ref/tags/${TAG}`]: tagRef({ type: 'commit', sha: 'x' }) }],
+ ['the annotated tag cannot be read', { [`git/ref/tags/${TAG}`]: tagRef({ type: 'tag', sha: 'x' }) }],
+ ])('fails closed when %s', (_name, routes) => {
+ expect(checkReleaseTag({ tag: TAG, headTree: TESTED_TREE, api: fakeApi(routes) }).ok).toBe(false);
+ });
+
+ it('fails closed when the release tree is unknown, before asking GitHub', () => {
+ const api = () => { throw new Error('should not be called'); };
+ expect(checkReleaseTag({ tag: TAG, headTree: null, api }).ok).toBe(false);
+ });
+});
+
+describe('release.yml publication contract', () => {
+ const yaml = readFileSync(join(repoRoot, '.github/workflows/release.yml'), 'utf8');
+ const release = workflowJobs(yaml).release;
+
+ it('creates a new tag at the triggering SHA, never the default branch', () => {
+ expect(release).toMatch(/uses: softprops\/action-gh-release@[0-9a-f]{40}[\s\S]*?target_commitish: \$\{\{ github\.sha \}\}/);
+ });
+
+ it('checks an existing tag before the release can be created', () => {
+ const check = release.indexOf('node scripts/verify-release-tag.js');
+ expect(check).toBeGreaterThan(-1);
+ expect(check).toBeLessThan(release.indexOf('softprops/action-gh-release'));
+ });
+
+ it('re-checks the tag after publication and keeps the existing permissions', () => {
+ expect(release.lastIndexOf('node scripts/verify-release-tag.js')).toBeGreaterThan(release.indexOf('softprops/action-gh-release'));
+ expect(yaml.match(/^permissions:\n {2}contents: write\n/m)).not.toBeNull();
+ expect(yaml).not.toMatch(/--force|git push[^\n]*\btag\b|git tag /);
+ });
+});