From 89a3dba1a7a90a7161602ad4702cc627d3bcc2e9 Mon Sep 17 00:00:00 2001 From: Really Him Date: Fri, 13 Nov 2026 10:04:43 -0500 Subject: [PATCH 1/4] fix: fix codeql alerts --- .github/workflows/release.yml | 26 ++++++++- plugins/badge-buddy/assets/review/review.js | 39 ++++++++++--- plugins/badge-buddy/scripts/scorecard.py | 22 +++++-- tests/badge-buddy/board-browser.js | 43 +++++++++++++- tests/badge-buddy/test_board.py | 7 +++ tests/badge-buddy/test_scorecard.py | 63 +++++++++++++++++++++ tests/maintenance/test_plugin_release.py | 63 +++++++++++++++++++++ tools/plugin_release.py | 15 ++++- 8 files changed, 258 insertions(+), 20 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 0987b1c..bf2058c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -80,11 +80,31 @@ jobs: checks: needs: preflight + if: github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main' && vars.RELEASE_REPOSITORY == github.repository runs-on: ubuntu-latest + permissions: + contents: read steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - name: Load the verifier from the dispatch commit on main + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ github.sha }} + fetch-depth: 0 + persist-credentials: false + - name: Reverify the signed tag and bind it to preflight before checkout + id: verified + env: + TAG: ${{ inputs.tag }} + ALLOWED_SIGNERS: ${{ vars.RELEASE_ALLOWED_SIGNERS }} + EXPECTED_OBJECT: ${{ needs.preflight.outputs.object }} + EXPECTED_HEAD: ${{ needs.preflight.outputs.head }} + run: | + printf '%s\n' "$ALLOWED_SIGNERS" > "$RUNNER_TEMP/allowed_signers" + python3 -I tools/plugin_release.py verify-tag --tag "$TAG" --allowed-signers "$RUNNER_TEMP/allowed_signers" --expected-object "$EXPECTED_OBJECT" --expected-head "$EXPECTED_HEAD" >> "$GITHUB_OUTPUT" + - name: Check out only the locally verified release commit + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: - ref: ${{ needs.preflight.outputs.head }} + ref: ${{ steps.verified.outputs.head }} fetch-depth: 0 persist-credentials: false - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 @@ -92,7 +112,7 @@ jobs: python-version: "3.12" - run: make check - name: Verify Badge Buddy criteria for this release - if: needs.preflight.outputs.plugin == 'badge-buddy' + if: steps.verified.outputs.plugin == 'badge-buddy' run: | make checkout-upstream BADGE_REPO="$RUNNER_TEMP/badgeapp" make download-criteria diff --git a/plugins/badge-buddy/assets/review/review.js b/plugins/badge-buddy/assets/review/review.js index d37d1b6..2f379bb 100644 --- a/plugins/badge-buddy/assets/review/review.js +++ b/plugins/badge-buddy/assets/review/review.js @@ -1,5 +1,13 @@ "use strict"; +// Navigation uses only these literal local routes; evidence URLs are handled separately. +const viewHrefs = new Map([ + ["needs_input", "#view=needs_input"], + ["unmet", "#view=unmet"], + ["na", "#view=na"], + ["met", "#view=met"], + ["all", "#view=all"], +]); const assessment = JSON.parse(document.querySelector("#assessment-data").textContent); const elements = Object.fromEntries([ "overview-view", "list-view", "project-id", "section-name", @@ -30,10 +38,12 @@ function renderContext() { elements.totalCount.textContent = String(assessment.total); } -function renderDashboard() { - views.forEach((view, key) => { +function renderDashboard(dashboardViews) { + dashboardViews.forEach((view, key) => { + const href = viewHrefs.get(key); + if (!href) return; const card = document.createElement("a"); - card.href = `#view=${key}`; + card.href = href; card.id = `nav-${key}`; card.className = "bucket-card"; card.dataset.view = key; @@ -53,9 +63,19 @@ function renderDashboard() { }); } -function createCriterion(criterionId, viewKey) { +function criterionFragment(viewKey, criterionId) { + const href = viewHrefs.get(viewKey); + if (!href) throw new Error("Unknown assessment view"); + // Catalog identifiers must remain a single fragment segment. + if (typeof criterionId !== "string" || !criterionId || /[^A-Za-z0-9_-]/.test(criterionId)) { + throw new Error("Invalid criterion identifier for navigation"); + } + return `${href.slice(1)}/${criterionId}`; +} + +function createCriterion(criterionId, fragment) { const article = document.querySelector("#criterion-template").content.firstElementChild.cloneNode(true); - article.id = `view=${viewKey}/${criterionId}`; + article.id = fragment; article.dataset.criterion = criterionId; const targets = {}; article.querySelectorAll("[data-field]").forEach((element) => { @@ -78,12 +98,13 @@ function renderList(view, key) { elements.emptyList.hidden = view.count > 0; elements.emptyList.textContent = `No criteria in ${view.label}.`; view.criterionIds.forEach((id) => { + const fragment = criterionFragment(key, id); const criterion = criteria.get(id); - const article = createCriterion(id, key); + const article = createCriterion(id, fragment); const item = document.createElement("li"); item.value = criterion.number; const link = document.createElement("a"); - link.href = `#${article.id}`; + link.href = `#${fragment}`; link.id = `toc-${id}`; link.textContent = criterion.displayId; item.append(link); @@ -95,7 +116,7 @@ function renderList(view, key) { function showSelection(event) { // The first part selects a page; the rest is an ordinary in-page anchor. const key = location.hash.slice(1).split("/")[0].replace(/^view=/, ""); - const view = views.get(key); + const view = viewHrefs.has(key) ? views.get(key) : undefined; const selected = view ? key : "overview"; if (selected === currentView) return; currentView = selected; @@ -177,7 +198,7 @@ function renderEvidence(justification, target) { } renderContext(); -renderDashboard(); +renderDashboard(views); showSelection(); window.addEventListener("hashchange", showSelection); document.querySelector(".skip-link").addEventListener("click", (event) => { diff --git a/plugins/badge-buddy/scripts/scorecard.py b/plugins/badge-buddy/scripts/scorecard.py index f67c6af..ec29449 100755 --- a/plugins/badge-buddy/scripts/scorecard.py +++ b/plugins/badge-buddy/scripts/scorecard.py @@ -233,7 +233,7 @@ def api_coverage_notes(repo: str) -> list[str]: "Published API snapshot: fetching it does not run Scorecard. Verify that a newer " "API date and commit reflect the intended remote changes before claiming the badge updated." ] - if normalize_repo(repo).startswith("gitlab.com/"): + if parse_repository_url(repo).hostname == "gitlab.com": notes.append( "For GitLab, V1 reads existing API results; implementation and publication setup " f"guidance is limited to GitHub. For GitLab diagnostics, consult {GITLAB_GUIDANCE}." @@ -272,6 +272,12 @@ def read_result_file(path: str) -> Result: def normalize_repo(repo: str) -> str: """Normalize public API repository identities without accepting URL suffixes.""" + parsed = parse_repository_url(repo) + return parsed.netloc + parsed.path + + +def parse_repository_url(repo: str) -> urllib.parse.SplitResult: + """Validate a public repository and return its canonical host and path.""" trimmed = repo.strip().rstrip("/") if trimmed.count("/") == 1 and ":" not in trimmed: trimmed = f"github.com/{trimmed}" @@ -280,7 +286,10 @@ def normalize_repo(repo: str) -> str: raise CommandError("use owner/repo or a public github.com or gitlab.com repository URL") if parsed.query or parsed.fragment or "?" in trimmed or "#" in trimmed: raise CommandError("repository URLs must not contain a query or fragment") - return "/".join([parsed.netloc.lower(), *repository_path_parts(parsed)]) + return parsed._replace( + netloc=parsed.netloc.lower(), + path="/" + "/".join(repository_path_parts(parsed)), + ) def repository_path_parts(parsed: urllib.parse.SplitResult) -> list[str]: @@ -295,9 +304,10 @@ def repository_path_parts(parsed: urllib.parse.SplitResult) -> list[str]: return parts -def missing_publication_message(normalized: str) -> str: - message = f"{normalized} has no published Scorecard result at this endpoint. " - if normalized.startswith("gitlab.com/"): +def missing_publication_message(repo: str) -> str: + parsed = parse_repository_url(repo) + message = f"{parsed.netloc}{parsed.path} has no published Scorecard result at this endpoint. " + if parsed.hostname == "gitlab.com": return ( message + "V1 supports reading existing GitLab API results, but implementation " "and publication setup guidance is limited to GitHub. You can import upstream " @@ -320,7 +330,7 @@ def fetch_public_api(repo: str, *, opener: Any = urllib.request.urlopen) -> Resu document = json.loads(response.read().decode("utf-8")) except urllib.error.HTTPError as error: if error.code == 404: - raise CommandError(missing_publication_message(normalized)) from error + raise CommandError(missing_publication_message(repo)) from error if error.code == 429: raise CommandError("public Scorecard API is rate-limited (429); wait before retrying") from error raise CommandError(f"public Scorecard API returned HTTP {error.code}; this does not establish a missing result") from error diff --git a/tests/badge-buddy/board-browser.js b/tests/badge-buddy/board-browser.js index 8534c88..95b6442 100644 --- a/tests/badge-buddy/board-browser.js +++ b/tests/badge-buddy/board-browser.js @@ -102,6 +102,47 @@ async (page) => { "https://example.org/explicit!", "https://example.org/docs_(v1)", "https://example.org/bare", ]), "Evidence URLs must preserve Markdown boundaries and trim prose punctuation"); + const navigation = await page.evaluate(() => { + const text = ''; + const unknownKeys = ["unexpected", "javascript:alert(1)", "https://example.org/", 'all/\"']; + const view = { ...views.get("all"), label: text, description: text }; + elements.bucketGrid.replaceChildren(); + renderDashboard(new Map([["all", view], ...unknownKeys.map((key) => [key, view])])); + const card = elements.bucketGrid.querySelector("a"); + const dashboard = elements.bucketGrid.childElementCount === 1 && + card.getAttribute("href") === "#view=all" && card.querySelector("h2").textContent === text && + card.querySelector("p").textContent === text && !card.querySelector("img"); + + views.set("unexpected", view); + history.replaceState(null, "", "#view=unexpected"); + showSelection(); + const unknownView = !elements.overviewView.hidden && elements.listView.hidden; + + const rejectedIds = ["", "bad/id", "bad#id", "bad%2Fid", 'bad\"', "bad\nid", "bad\n", "bad\r", 7, null].every((id) => { + try { + renderList({ ...view, criterionIds: [id], count: 1 }, "all"); + return false; + } catch (error) { + return error.message === "Invalid criterion identifier for navigation" && + !elements.tocList.childElementCount && !elements.criterionList.childElementCount; + } + }); + + const first = criteria.values().next().value; + criteria.set(first.id, { ...first, displayId: text }); + renderList({ ...view, criterionIds: [first.id], count: 1 }, "all"); + const link = elements.tocList.querySelector("a"); + const article = elements.criterionList.querySelector("article"); + const toc = link.textContent === text && !elements.tocList.querySelector("img") && + link.getAttribute("href") === `#view=all/${first.id}` && article.id === `view=all/${first.id}`; + return { dashboard, unknownView, rejectedIds, toc, injected: Boolean(window.injected) }; + }); + check(navigation.dashboard && navigation.unknownView, "Only fixed local dashboard views may be rendered or selected"); + check(navigation.rejectedIds, "Malformed criterion identifiers must fail before an article or ToC link is created"); + check(navigation.toc && !navigation.injected, "Navigation labels must remain text and valid criterion fragments must remain unchanged"); + await page.goto(`${base}#view=all`); + await page.reload(); + // Deliver regenerated HTML on the real reload timer, without changing the browser's in-memory assessment. const html = await page.request.get(base).then((response) => response.text()); const changed = JSON.parse(JSON.stringify(original)); @@ -150,5 +191,5 @@ async (page) => { await page.goto(`${base}#view=all`); await page.reload(); } - return { criteria: original.total, widths: [1440, 600, 375], checks: "dashboard, full lists, ToCs, stable numbering, labels, focus, scroll, five-second refresh, two wording revisions, approved move, empty bucket, safe text" }; + return { criteria: original.total, widths: [1440, 600, 375], checks: "dashboard, full lists, ToCs, stable numbering, labels, focus, scroll, five-second refresh, two wording revisions, approved move, empty bucket, safe text, fixed view routes, criterion fragments" }; } diff --git a/tests/badge-buddy/test_board.py b/tests/badge-buddy/test_board.py index d5ee89c..1e4dbe0 100644 --- a/tests/badge-buddy/test_board.py +++ b/tests/badge-buddy/test_board.py @@ -2,6 +2,7 @@ import json from pathlib import Path +import re import sys import tempfile from typing import ClassVar @@ -73,6 +74,12 @@ def test_criterion_html_preserves_readable_text(self) -> None: with self.subTest(markup=markup): self.assertEqual(expected, plain_text(markup)) + def test_catalog_ids_are_single_navigation_fragment_segments(self) -> None: + for section in self.catalog.section_names: + for criterion in self.catalog.section(section): + with self.subTest(section=section, criterion=criterion.id): + self.assertIsNotNone(re.fullmatch(r"[A-Za-z0-9_-]+", criterion.id)) + def test_future_and_obsolete_criteria_retain_order_and_visible_labels(self) -> None: source = json.loads(self.catalog.asset_path.read_text()) original_ids = [row["id"] for row in source["sections"]["passing"]] diff --git a/tests/badge-buddy/test_scorecard.py b/tests/badge-buddy/test_scorecard.py index 056bb6c..5f5e1bb 100644 --- a/tests/badge-buddy/test_scorecard.py +++ b/tests/badge-buddy/test_scorecard.py @@ -288,6 +288,48 @@ def test_malformed_snapshot_metadata_cannot_claim_api_provenance(self) -> None: self.assertIn("_ossf_scorecard", self.stderr) +class RepositoryGuidanceTest(unittest.TestCase): + def test_guidance_uses_the_parsed_host_not_a_path_substring(self) -> None: + for repo, identity, gitlab in ( + ("https://GitLab.com/group/subgroup/project.git", "gitlab.com/group/subgroup/project", True), + ("http://GitHub.com/example/project.git/", "github.com/example/project", False), + ("github.com/gitlab.com/project", "github.com/gitlab.com/project", False), + ("gitlab.com/project", "github.com/gitlab.com/project", False), + ("gitlab.com/github.com/project", "gitlab.com/github.com/project", True), + ("gitlab.com/group.git/project.git.git", "gitlab.com/group.git/project.git", True), + ): + with self.subTest(repo=repo): + self.assertEqual(identity, controller.normalize_repo(repo)) + notes = " ".join(controller.api_coverage_notes(repo)) + message = controller.missing_publication_message(repo) + self.assertTrue(message.startswith(identity + " has no published")) + self.assertEqual(gitlab, "For GitLab" in notes) + self.assertEqual(gitlab, "existing GitLab API results" in message) + self.assertEqual(not gitlab, "Action publishing run" in notes) + self.assertEqual(not gitlab, "publish_results" in message) + + def test_each_guidance_entry_point_rejects_invalid_repository_urls(self) -> None: + for repo in ( + "https://evil.test/gitlab.com/group/project", + "https://gitlab.com.evil.test/group/project", + "https://evil-gitlab.com/group/project", + "https://gitlab.com@evil.test/group/project", + "https://evil.test@gitlab.com/group/project", + "https://gitlab.com:443/group/project", + "https://gitlab.com./group/project", + "https://gitlab.com%2eevil.test/group/project", + "https://gitlab.com\\@evil.test/group/project", + "https://github.com/owner/repo?next=gitlab.com/group/project", + "https://gitlab.com/group/project?", + "https://gitlab.com/group/project#", + "https://gitlab.com/group/project/-/issues/1", + ): + for guidance in (controller.api_coverage_notes, controller.missing_publication_message): + with self.subTest(repo=repo, guidance=guidance.__name__): + with self.assertRaises(controller.CommandError): + guidance(repo) + + class PublicApiTest(ControllerTestCase): def test_fetch_reads_public_endpoint_and_uses_only_upstream_score(self) -> None: requests: list[tuple[Any, int]] = [] @@ -361,6 +403,13 @@ def test_invalid_repository_forms_do_not_make_network_requests(self) -> None: "https://gitlab.com/fdroid/fdroidclient/-/tree/main", "https://gitlab.com/group/subgroup/project/-/merge_requests/1", "https://gitlab.com/group/subgroup/project/-/", + "https://gitlab.com.evil.test/group/project", + "https://evil.test/gitlab.com/group/project", + "https://gitlab.com@evil.test/group/project", + "https://evil.test@gitlab.com/group/project", + "https://gitlab.com:443/group/project", + "https://gitlab.com/group/project?", + "https://gitlab.com/group/project#", ): with self.subTest(repo=repo): opener = Mock() @@ -411,6 +460,20 @@ def opener(request: Any, timeout: int = 0) -> FakeResponse: self.assertNotIn("Action", self.stderr) self.assertNotIn("publish_results", self.stderr) + def test_missing_result_message_matches_the_requested_repository_identity(self) -> None: + normalized = "gitlab.com/group.git/project.git" + + def opener(request: Any, timeout: int = 0) -> FakeResponse: + self.assertEqual("https://api.scorecard.dev/projects/" + normalized, request.full_url) + raise urllib.error.HTTPError(request.full_url, 404, "Not Found", {}, io.BytesIO()) + + code, _ = self.run_command( + ["fetch", "--repo", "https://GitLab.com/group.git/project.git.git"], opener=opener, + ) + self.assert_clean_error(code) + self.assertIn(normalized + " has no published", self.stderr) + self.assertIn("existing GitLab API results", self.stderr) + def test_api_identity_mismatch_is_not_saved_as_requested_repository(self) -> None: document = result_document() document["repo"]["name"] = "github.com/someone/else" diff --git a/tests/maintenance/test_plugin_release.py b/tests/maintenance/test_plugin_release.py index 0c19ff3..248f7dd 100644 --- a/tests/maintenance/test_plugin_release.py +++ b/tests/maintenance/test_plugin_release.py @@ -3,6 +3,7 @@ from __future__ import annotations import hashlib +import io import json import os from pathlib import Path @@ -164,6 +165,68 @@ def test_tag_delimiter_inside_a_valid_prerelease_identifier(self): self.sign(tag) self.assertEqual(release.verify_tag(tag, self.allow)["version"], version) + def verify_preflight_command(self, expected_object, expected_head): + output, errors = io.StringIO(), io.StringIO() + with patch("sys.stdout", output), patch("sys.stderr", errors): + code = release.main([ + "verify-tag", "--tag", self.tag, + "--allowed-signers", str(self.allow), + "--expected-object", expected_object, + "--expected-head", expected_head, + ]) + return code, output.getvalue(), errors.getvalue() + + def test_preflight_binding_accepts_a_signed_historical_main_commit(self): + self.sign() + tag_object = self.git("rev-parse", self.tag) + self.write("later-main-work", "The release decision remains an ancestor.") + self.git("update-ref", "refs/remotes/origin/main", self.commit()) + + code, output, errors = self.verify_preflight_command(tag_object, self.base) + self.assertEqual(0, code, errors) + self.assertIn(f"head={self.base}\n", output) + self.assertIn(f"object={tag_object}\n", output) + + def test_preflight_binding_rejects_mismatched_or_empty_identities_without_outputs(self): + self.sign() + tag_object = self.git("rev-parse", self.tag) + for expected_object, expected_head, message in ( + ("0" * 40, self.base, "signed tag changed"), + (tag_object, "0" * 40, "release commit changed"), + ("", self.base, "signed tag changed"), + (tag_object, "", "release commit changed"), + ): + with self.subTest(object=expected_object, head=expected_head): + code, output, errors = self.verify_preflight_command( + expected_object, expected_head + ) + self.assertEqual(1, code) + self.assertEqual("", output) + self.assertIn(message, errors) + + def test_preflight_binding_rejects_a_replacement_signed_tag_at_the_same_commit(self): + self.sign() + original_object = self.git("rev-parse", self.tag) + self.git( + "-c", "gpg.format=ssh", + "-c", f"user.signingkey={self.root / 'release'}", + "tag", "-fsm", "Replacement annotation", self.tag, + ) + self.assertNotEqual(original_object, self.git("rev-parse", self.tag)) + code, output, errors = self.verify_preflight_command(original_object, self.base) + self.assertEqual(1, code) + self.assertEqual("", output) + self.assertIn("signed tag changed since preflight", errors) + + def test_preflight_binding_does_not_bypass_signature_validation(self): + self.sign() + tag_object = self.git("rev-parse", self.tag) + self.allow.write_text("other " + self.key("other").with_suffix(".pub").read_text()) + code, output, errors = self.verify_preflight_command(tag_object, self.base) + self.assertEqual(1, code) + self.assertEqual("", output) + self.assertIn("Plugin release failed", errors) + def test_annotated_but_unsigned_and_lightweight_refused(self): self.allow.touch() self.git("tag", self.tag) diff --git a/tools/plugin_release.py b/tools/plugin_release.py index 8c05ef0..87705ad 100644 --- a/tools/plugin_release.py +++ b/tools/plugin_release.py @@ -363,6 +363,16 @@ def prepare_draft(repository: str, plugin: dict, directory: Path) -> dict: } +def check_preflight_identity( + plugin: dict, expected_object: str | None, expected_head: str | None +) -> None: + """Bind a freshly verified tag to the exact subject approved by preflight.""" + if expected_object is not None and plugin["object"] != expected_object: + raise ValueError("signed tag changed since preflight") + if expected_head is not None and plugin["head"] != expected_head: + raise ValueError("release commit changed since preflight") + + def main(argv: list[str] | None = None) -> int: parser = argparse.ArgumentParser(description=__doc__) commands = parser.add_subparsers(dest="command", required=True) @@ -373,7 +383,9 @@ def main(argv: list[str] | None = None) -> int: tag_parser = argparse.ArgumentParser(add_help=False) tag_parser.add_argument("--tag", required=True) tag_parser.add_argument("--allowed-signers", type=Path, required=True) - commands.add_parser("verify-tag", parents=[tag_parser]) + verify = commands.add_parser("verify-tag", parents=[tag_parser]) + verify.add_argument("--expected-object") + verify.add_argument("--expected-head") draft = commands.add_parser("draft", parents=[tag_parser]) draft.add_argument("--receipt", type=Path, required=True) draft.add_argument("--object", required=True) @@ -396,6 +408,7 @@ def main(argv: list[str] | None = None) -> int: receipt = prepare_draft(args.repository, plugin, args.evidence) args.receipt.write_text(json.dumps(receipt) + "\n") else: + check_preflight_identity(plugin, args.expected_object, args.expected_head) print( f"head={plugin['head']}\nobject={plugin['object']}\nplugin={plugin['name']}" ) From 36035eda38c3b578527a9cc699465121be523307 Mon Sep 17 00:00:00 2001 From: Really Him Date: Fri, 13 Nov 2026 10:47:16 -0500 Subject: [PATCH 2/4] refactor: automate approved GitHub-native releases --- .github/workflows/dependency-scan.yml | 9 +- .github/workflows/release.yml | 209 ++++---- Makefile | 14 +- README.md | 14 +- SECURITY.md | 2 +- VERIFYING.md | 89 ++-- docs/criteria-maintenance.md | 4 +- docs/release-notes/README.md | 2 +- docs/releases.md | 71 +-- docs/repo-setup.md | 29 +- tests/maintenance/test_finalize_release.py | 140 ------ tests/maintenance/test_plugin_release.py | 560 ++++++++++++--------- tests/maintenance/test_release_workflow.py | 131 +++++ tools/finalize_release.py | 168 ------- tools/plugin_release.py | 399 ++++++++++----- 15 files changed, 937 insertions(+), 904 deletions(-) delete mode 100644 tests/maintenance/test_finalize_release.py create mode 100644 tests/maintenance/test_release_workflow.py delete mode 100644 tools/finalize_release.py diff --git a/.github/workflows/dependency-scan.yml b/.github/workflows/dependency-scan.yml index 44389a1..99a9d93 100644 --- a/.github/workflows/dependency-scan.yml +++ b/.github/workflows/dependency-scan.yml @@ -5,11 +5,6 @@ on: - cron: "17 6 * * 2" workflow_dispatch: workflow_call: - inputs: - commit: - description: Full validated commit SHA to scan - required: true - type: string outputs: artifact-id: description: Immutable Actions artifact ID for this scan @@ -25,13 +20,13 @@ jobs: outputs: artifact-id: ${{ steps.evidence.outputs.artifact-id }} env: - SCAN_COMMIT: ${{ inputs.commit || github.sha }} + SCAN_COMMIT: ${{ github.sha }} steps: - name: Require a full commit SHA run: '[[ "$SCAN_COMMIT" =~ ^[0-9a-f]{40}$ ]]' - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: - ref: ${{ env.SCAN_COMMIT }} + ref: ${{ github.sha }} persist-credentials: false - name: Confirm the checkout run: test "$(git rev-parse HEAD)" = "$SCAN_COMMIT" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index bf2058c..2d08172 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,164 +1,171 @@ name: release -run-name: ${{ github.event_name == 'workflow_dispatch' && format('Prepare {0}', inputs.tag) || github.event.pull_request.title }} +run-name: ${{ github.event_name == 'pull_request' && github.event.pull_request.title || format('Release from {0}', github.sha) }} on: pull_request: branches: [main] - workflow_dispatch: - inputs: - tag: - description: Existing SSH-signed PLUGIN--vVERSION tag on main - type: string - required: true + push: + branches: [main] permissions: contents: read +# Keep each merged release decision available for approval, even if main advances. concurrency: - group: release-${{ inputs.tag || github.run_id }} + group: release-${{ github.event.pull_request.number || github.sha }} cancel-in-progress: false jobs: validate: runs-on: ubuntu-latest - if: github.event_name == 'pull_request' + outputs: + releases: ${{ steps.plan.outputs.releases }} + base: ${{ steps.plan.outputs.base }} + criteria: ${{ steps.plan.outputs.criteria }} steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: - ref: ${{ github.event.pull_request.head.sha }} + ref: ${{ github.sha }} fetch-depth: 0 persist-credentials: false - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 with: python-version: "3.12" - - name: Validate version decisions and reviewed notes + - name: Validate version decisions and record the exact release commit id: plan env: PR_BASE_SHA: ${{ github.event.pull_request.base.sha }} + PUSH_BASE_SHA: ${{ github.event.before }} run: | - base="$(git merge-base "$PR_BASE_SHA" HEAD)" - make release-plan RELEASE_BASE="$base" - cat .cache/releases/plan.json - if git diff --quiet "$base" HEAD -- plugins/badge-buddy/assets/criteria/; then - echo "criteria=false" >> "$GITHUB_OUTPUT" + if test "$GITHUB_EVENT_NAME" = pull_request; then + base="$(git merge-base "$PR_BASE_SHA" HEAD)" + elif test "$PUSH_BASE_SHA" = 0000000000000000000000000000000000000000; then + base=empty else - echo "criteria=true" >> "$GITHUB_OUTPUT" + base="$PUSH_BASE_SHA" fi - - name: Verify changed criteria against the live application - if: steps.plan.outputs.criteria == 'true' - run: | - make checkout-upstream BADGE_REPO="$RUNNER_TEMP/badgeapp" - make download-criteria - make check-criteria BADGE_REPO="$RUNNER_TEMP/badgeapp" + make release-plan RELEASE_BASE="$base" RELEASE_HEAD="$GITHUB_SHA" + python3 - <<'PY' + import json + import os + import subprocess + from pathlib import Path + + plan = json.loads(Path(".cache/releases/plan.json").read_text()) + criteria = any(p["name"] == "badge-buddy" for p in plan["plugins"]) + if plan["base"]: + difference = subprocess.run([ + "git", "diff", "--quiet", plan["base"], plan["head"], "--", + "plugins/badge-buddy/assets/criteria/", + ]).returncode + if difference not in (0, 1): + raise SystemExit(difference) + criteria = criteria or difference == 1 + with open(os.environ["GITHUB_OUTPUT"], "a") as output: + print(f"releases={str(bool(plan['plugins'])).lower()}", file=output) + print(f"base={plan['base'] or 'empty'}", file=output) + print(f"criteria={str(criteria).lower()}", file=output) + with open(os.environ["GITHUB_STEP_SUMMARY"], "a") as summary: + print(f"## Release decision\n\nRelease source commit: `{plan['head']}`\n", file=summary) + for plugin in plan["plugins"]: + print(f"- `{plugin['tag']}`", file=summary) + if not plan["plugins"]: + print("No plugin release requested by this change.", file=summary) + else: + print("\nPublication requires passing tests, a clean dependency scan, and owner approval in the release environment.", file=summary) + PY - preflight: - if: github.event_name == 'workflow_dispatch' + checks: + needs: validate + if: github.event_name == 'push' && needs.validate.outputs.releases == 'true' && vars.RELEASE_REPOSITORY == github.repository runs-on: ubuntu-latest - outputs: - head: ${{ steps.tag.outputs.head }} - object: ${{ steps.tag.outputs.object }} - plugin: ${{ steps.tag.outputs.plugin }} steps: - # The workflow and helpers come from the dispatch SHA on protected main. - - name: Require the enabled repository and protected main branch - env: - ENABLED_REPOSITORY: ${{ vars.RELEASE_REPOSITORY }} - run: test "$GITHUB_REF" = refs/heads/main && test "$ENABLED_REPOSITORY" = "$GITHUB_REPOSITORY" - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: ref: ${{ github.sha }} - fetch-depth: 0 persist-credentials: false - - name: Verify the tag object, signer, manifest, ancestry and notes - id: tag - env: - TAG: ${{ inputs.tag }} - ALLOWED_SIGNERS: ${{ vars.RELEASE_ALLOWED_SIGNERS }} - run: | - printf '%s\n' "$ALLOWED_SIGNERS" > "$RUNNER_TEMP/allowed_signers" - python3 -I tools/plugin_release.py verify-tag --tag "$TAG" --allowed-signers "$RUNNER_TEMP/allowed_signers" >> "$GITHUB_OUTPUT" + - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: "3.12" + - run: make check - checks: - needs: preflight - if: github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main' && vars.RELEASE_REPOSITORY == github.repository + scan: + needs: validate + if: github.event_name == 'push' && needs.validate.outputs.releases == 'true' && vars.RELEASE_REPOSITORY == github.repository + uses: ./.github/workflows/dependency-scan.yml + + # Advisory only: upstream changes or outages cannot veto an accepted release. + criteria: + needs: validate + if: needs.validate.outputs.criteria == 'true' + continue-on-error: true runs-on: ubuntu-latest - permissions: - contents: read steps: - - name: Load the verifier from the dispatch commit on main - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: ref: ${{ github.sha }} - fetch-depth: 0 - persist-credentials: false - - name: Reverify the signed tag and bind it to preflight before checkout - id: verified - env: - TAG: ${{ inputs.tag }} - ALLOWED_SIGNERS: ${{ vars.RELEASE_ALLOWED_SIGNERS }} - EXPECTED_OBJECT: ${{ needs.preflight.outputs.object }} - EXPECTED_HEAD: ${{ needs.preflight.outputs.head }} - run: | - printf '%s\n' "$ALLOWED_SIGNERS" > "$RUNNER_TEMP/allowed_signers" - python3 -I tools/plugin_release.py verify-tag --tag "$TAG" --allowed-signers "$RUNNER_TEMP/allowed_signers" --expected-object "$EXPECTED_OBJECT" --expected-head "$EXPECTED_HEAD" >> "$GITHUB_OUTPUT" - - name: Check out only the locally verified release commit - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - ref: ${{ steps.verified.outputs.head }} - fetch-depth: 0 persist-credentials: false - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 with: python-version: "3.12" - - run: make check - - name: Verify Badge Buddy criteria for this release - if: steps.verified.outputs.plugin == 'badge-buddy' + - name: Download current criteria + id: download + continue-on-error: true + run: make download-criteria + - name: Compare the accepted catalog with the current site + id: compare + if: steps.download.outcome == 'success' + continue-on-error: true + run: make compare-criteria + - name: Report advisory outcome + if: always() + env: + DOWNLOAD: ${{ steps.download.outcome }} + COMPARISON: ${{ steps.compare.outcome }} run: | - make checkout-upstream BADGE_REPO="$RUNNER_TEMP/badgeapp" - make download-criteria - make check-criteria BADGE_REPO="$RUNNER_TEMP/badgeapp" - - scan: - needs: preflight - uses: ./.github/workflows/dependency-scan.yml - with: - commit: ${{ needs.preflight.outputs.head }} + if test "$DOWNLOAD" != success; then + message='Live criteria could not be checked. Release publication is unaffected.' + echo "::warning::$message" + elif test "$COMPARISON" != success; then + message='Live criteria differ or comparison failed. Review the criteria evidence; release publication is unaffected.' + echo "::warning::$message" + else + message='The accepted criteria catalog matches the current site.' + fi + printf '## Criteria freshness (advisory)\n\n%s\n' "$message" >> "$GITHUB_STEP_SUMMARY" + - name: Preserve criteria evidence + if: always() + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: criteria-advisory-${{ github.run_attempt }} + path: .cache/criteria/ + include-hidden-files: true + if-no-files-found: ignore + retention-days: 14 - draft: - needs: [preflight, checks, scan] - if: github.ref == 'refs/heads/main' && vars.RELEASE_REPOSITORY == github.repository + publish: + needs: [validate, checks, scan] + if: github.event_name == 'push' && github.ref == 'refs/heads/main' && needs.validate.outputs.releases == 'true' && vars.RELEASE_REPOSITORY == github.repository environment: release runs-on: ubuntu-latest permissions: contents: write steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - name: Load the exact commit that passed verification + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: ref: ${{ github.sha }} fetch-depth: 0 persist-credentials: false - - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + - name: Fetch dependency evidence from this run + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 with: artifact-ids: ${{ needs.scan.outputs.artifact-id }} path: ${{ runner.temp }}/evidence merge-multiple: true - - name: Prepare the unpublished release from checked evidence + - name: Create tags, publish and verify immutable releases env: - TAG: ${{ inputs.tag }} - OBJECT: ${{ needs.preflight.outputs.object }} - ALLOWED_SIGNERS: ${{ vars.RELEASE_ALLOWED_SIGNERS }} + RELEASE_BASE: ${{ needs.validate.outputs.base }} GH_TOKEN: ${{ github.token }} run: | - printf '%s\n' "$ALLOWED_SIGNERS" > "$RUNNER_TEMP/allowed_signers" - python3 -I tools/plugin_release.py draft --tag "$TAG" --allowed-signers "$RUNNER_TEMP/allowed_signers" --object "$OBJECT" --repository "$GITHUB_REPOSITORY" --evidence "$RUNNER_TEMP/evidence" --receipt "$RUNNER_TEMP/receipt.json" - - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 - with: - name: release-subject-${{ github.run_attempt }} - path: ${{ runner.temp }}/receipt.json - if-no-files-found: error - - name: Record the maintainer finalization command - env: - TAG: ${{ inputs.tag }} - run: | - echo "Draft ready. Inspect it, then run:" >> "$GITHUB_STEP_SUMMARY" - echo "\`make release-finalize REPO=$GITHUB_REPOSITORY TAG=$TAG RUN=$GITHUB_RUN_ID\`" >> "$GITHUB_STEP_SUMMARY" + make release-publish RELEASE_BASE="$RELEASE_BASE" RELEASE_HEAD="$GITHUB_SHA" REPO="$GITHUB_REPOSITORY" RELEASE_EVIDENCE="$RUNNER_TEMP/evidence" diff --git a/Makefile b/Makefile index 8e7cc38..5f29647 100644 --- a/Makefile +++ b/Makefile @@ -17,7 +17,8 @@ UPSTREAM_REF ?= RELEASE_BASE ?= HEAD^ RELEASE_HEAD ?= HEAD RELEASE_PLAN ?= .cache/releases/plan.json -export TAG REPO RUN OSV_SCANNER +RELEASE_EVIDENCE ?= .cache/dependency-scan +export REPO OSV_SCANNER RSVG ?= rsvg-convert PNGQUANT ?= pngquant OXIPNG ?= oxipng @@ -38,7 +39,7 @@ PY_DIRS := $(wildcard $(foreach plugin,$(PLUGINS),$(plugin)/scripts $(plugin)/sk .PHONY: eval-release-skills mod-test .PHONY: format-deps hooks-install hooks-check hooks-uninstall .PHONY: treestamp-check treestamp-update -.PHONY: download-criteria compare-criteria release-check checkout-upstream release-plan release-finalize dependency-scan +.PHONY: download-criteria compare-criteria criteria-audit release-check checkout-upstream release-plan release-publish dependency-scan help: ## Show available targets. @awk 'BEGIN {FS = ":.*## "; printf "Usage: make \n\nTargets:\n"} /^[a-zA-Z0-9_-]+:.*## / {printf " %-18s %s\n", $$1, $$2}' $(MAKEFILE_LIST) @@ -124,8 +125,8 @@ checkout-upstream: setup ## Create a clean upstream clone at UPSTREAM_REF (defau release-plan: setup ## Preview manifest version changes between RELEASE_BASE and RELEASE_HEAD. $(VENV_PYTHON) tools/plugin_release.py plan --base "$(RELEASE_BASE)" --head "$(RELEASE_HEAD)" --output "$(RELEASE_PLAN)" -release-finalize: setup ## Verify and publish the prepared immutable draft (REPO, TAG and RUN from its Actions summary). - $(VENV_PYTHON) tools/finalize_release.py +release-publish: setup ## Publish the verified plan in the approved Actions job (REPO, RELEASE_BASE, RELEASE_HEAD). + $(VENV_PYTHON) tools/plugin_release.py publish --base "$(RELEASE_BASE)" --head "$(RELEASE_HEAD)" --repository "$(REPO)" --evidence "$(RELEASE_EVIDENCE)" dependency-scan: setup ## Scan resolved maintainer dependencies with OSV-Scanner; save evidence under .cache/dependency-scan. $(VENV_PYTHON) tools/scan_dependencies.py --scanner "$$OSV_SCANNER" --output .cache/dependency-scan @@ -133,10 +134,11 @@ dependency-scan: setup ## Scan resolved maintainer dependencies with OSV-Scanner check-criteria: dev-deps ## Check the bundled catalog, selected checkout, and application snapshot agree. $(VENV_PYTHON) tools/criteria_sync.py check --badge-repo "$(BADGE_REPO)" --snapshot "$(CRITERIA_SNAPSHOT)" -release-check: dev-deps ## Explicitly verify the catalog against the live site and run local checks. +criteria-audit: dev-deps ## Audit catalog freshness against the live site; advisory to release publication. $(MAKE) download-criteria $(MAKE) check-criteria - $(MAKE) check + +release-check: check ## Run the offline release checks; live criteria freshness is advisory. render-assets: ## Re-render and compress the PNG beside each SVG in ASSETS, or only SVG=. RSVG="$(RSVG)" PNGQUANT="$(PNGQUANT)" OXIPNG="$(OXIPNG)" tools/render-assets.sh $(if $(SVG),$(SVG),$(ASSETS)) diff --git a/README.md b/README.md index 8de6f0a..03f3a6a 100644 --- a/README.md +++ b/README.md @@ -48,17 +48,7 @@ Each plugin's README explains what to ask for once it is installed. Badge Buddy ```sh ./ @@ -104,7 +94,7 @@ make plugin-validate # validate each plugin's structure (needs the Claude Code make mod-test # run the mods' tests (needs the Claude Code CLI) ``` -The runtime uses only the Python standard library; the local `venv` holds the development dependencies. `make check` runs the plugin and maintenance suites in separate processes and compiles the Python sources. Continuous integration runs the same target on every push and pull request. See [criteria maintenance](docs/criteria-maintenance.md) for catalog updates and [plugin releases](docs/releases.md) for how to release a plugin: bump its manifest, sign the tag, review the OSV report, then publish the immutable draft. See [Verifying a plugin release](VERIFYING.md) to check a signed release and its attachments. +The runtime uses only the Python standard library; the local `venv` holds the development dependencies. `make check` runs the plugin and maintenance suites in separate processes and compiles the Python sources. Continuous integration runs the same target on every push and pull request. See [criteria maintenance](docs/criteria-maintenance.md) for catalog updates and [plugin releases](docs/releases.md) for how to release a plugin: merge its version and reviewed notes, review the checks and OSV report, then approve publication in GitHub. The workflow tags the checked commit and publishes an immutable release. See [Verifying a plugin release](VERIFYING.md) to check its source and attachments; marketplace installation does not automatically pin or verify a release. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to file issues and propose changes. diff --git a/SECURITY.md b/SECURITY.md index 045ecaf..c32379d 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,6 +1,6 @@ # Security policy for Reponomics plugins -This policy covers the plugins in this repository, their scripts and hooks, and the release workflow and signing process. +This policy covers the plugins in this repository, their scripts and hooks, and the release workflow and verification process. ## Supported versions diff --git a/VERIFYING.md b/VERIFYING.md index 987daf8..f4f1999 100644 --- a/VERIFYING.md +++ b/VERIFYING.md @@ -1,66 +1,85 @@ # Verifying a plugin release -The downloadable plugin is source in Git. For releases made with the signed-tag process, verify the maintainer’s signature on the plugin tag before using its contents. Then check GitHub’s immutable release record if you need to verify the attached dependency scan. These checks answer different questions: who approved this source, and which files GitHub recorded for this release. +Current releases use a lightweight Git tag and GitHub's immutable release attestation. The publication workflow checks the exact source commit, waits for owner approval in the `release` environment, then publishes and verifies the release. Consumers verify the repository, release tag, source commit, and attached evidence against that attestation. -## Get the expected signer independently +Marketplace installation does not automatically pin a plugin to a verified release or perform these checks. Use the verified Git tree below when inspecting or installing the particular release you intend to trust. -For releases beginning with `0.3.0-beta.1`, the authorized maintainer is [hesreallyhim](https://github.com/hesreallyhim). The release-signing public key is listed in [that account's SSH signing keys](https://api.github.com/users/hesreallyhim/ssh_signing_keys) with the SHA256 fingerprint `SHA256:IVsf0Jed2MXKHQkW/FcYtahE6OiovA5+50GxsrZPs9E`. Authenticate the maintainer's account through a channel you already trust; this page alone does not establish trust in the key. A replacement key requires an authenticated maintainer announcement. +## Fetch the exact source -Obtain the release signing **public key** and its expected **SHA256 fingerprint** from the maintainer. Confirm the complete fingerprint through a channel you already trust independently of this release, such as direct contact with a known maintainer or a previously authenticated project announcement. Confirm that the key was authorized for this plugin and version. A key found inside the candidate tag, a comment on a key, or a “Verified” badge alone does not establish that authority. - -Save the public key as `release-signing.pub` outside the source checkout. Compare the fingerprint in the following output with the independently obtained value, character for character: +Set the official release repository and exact plugin tag you intend to use: ```sh -ssh-keygen -lf release-signing.pub -E sha256 +repo=reponomics/plugins +tag=PLUGIN--vVERSION +git clone --no-checkout --no-tags "https://github.com/$repo.git" plugin-source +cd plugin-source +git fetch --no-tags origin "refs/tags/$tag:refs/tags/$tag" +git cat-file -t "refs/tags/$tag" +git rev-parse "refs/tags/$tag" +git rev-parse "refs/tags/$tag^{commit}" ``` -If it matches, use the key to make a one-key verification file. The first field below is your local label for this trusted release signer. +For current lightweight tags, the object type is `commit`, and both object IDs are the same commit SHA. Record that SHA. A lightweight tag has no personal SSH signature; its release identity is verified through GitHub's attestation below. If the object type is `tag`, follow [Historical SSH-signed tags](#historical-ssh-signed-tags) before continuing. Those annotated tags have a separate tag object ID and commit ID. + +## Verify the release and its evidence + +Use a GitHub CLI that supports [release verification](https://cli.github.com/manual/gh_release_verify). From a fresh download directory, with the same `repo` and `tag` values, run: ```sh -{ printf 'release-maintainer namespaces="git" '; cat release-signing.pub; } > allowed_signers -signers="$PWD/allowed_signers" +gh release verify "$tag" --repo "$repo" --format json +gh release download "$tag" --repo "$repo" --pattern osv-results.json --pattern scan-scope.md +gh release verify-asset "$tag" osv-results.json --repo "$repo" +gh release verify-asset "$tag" scan-scope.md --repo "$repo" ``` -If fingerprints disagree, a key changes without an authenticated notice, or you cannot establish trust, stop. Obtain the correct key and applicable versions from the maintainer before continuing. +In the JSON result, find the release's Git subject under `verificationResult.statement.subject`. Require its repository and tag to match the requested release, and its `digest.sha1` to match the fetched Git ref's object ID. For current lightweight tags, this digest is the **commit SHA** itself. For historical annotated tags, it is the **tag object ID**; the verified SSH signature binds that object to the commit. -## Verify the exact source tag +The first command checks GitHub's immutable release attestation; each [verify-asset](https://cli.github.com/manual/gh_release_verify-asset) command checks the downloaded bytes. Asset verification does not apply to GitHub's automatically generated source archives. Check that `scan-scope.md` names the same commit and read its tooling, platform, dependency inputs, and outcome alongside the JSON report. -Use Git with SSH signature support and OpenSSH with `ssh-keygen -Y` support. Set the repository to the official release repository you intended to use, and replace the example tag with the exact plugin name and published version. +After verification, return to the source checkout and select the verified tree: ```sh -repo=OWNER/REPOSITORY -tag=PLUGIN--vVERSION -git clone --no-checkout --no-tags "https://github.com/$repo.git" plugin-source -cd plugin-source -git fetch --no-tags origin "refs/tags/$tag:refs/tags/$tag" -git cat-file -t "refs/tags/$tag" -git cat-file -p "refs/tags/$tag" -git -c gpg.openpgp.program=false -c gpg.x509.program=false -c gpg.ssh.allowedSignersFile="$signers" verify-tag "refs/tags/$tag" +git switch --detach "refs/tags/$tag^{commit}" ``` -Require all three results: an object of type `tag`; its signed header says `type commit` and `tag` followed by the exact requested tag name; and `verify-tag` succeeds with a **Good "git" signature** for your allowed principal and the expected SSH key fingerprint. Checking the signed name prevents a valid tag from being relabeled as another release. A lightweight tag points directly to a commit. Even if that commit is signed, it does not sign the release name or authorize that version. +Check `plugins/PLUGIN/.claude-plugin/plugin.json` for the expected version and read `docs/release-notes/PLUGIN/VERSION.md` from that tree. GitHub permits editing displayed release notes after publication, so the reviewed notes in Git are the source record. + +Matching the attached files proves which reports GitHub recorded for the release. It does not prove that the code, plugin guidance, generated workflows, or all downstream dependencies are free of vulnerabilities. If verification fails, keep the tag, object IDs, and error, and contact the maintainer through a known channel before using that copy. + +## Historical SSH-signed tags + +The previous release process used annotated SSH-signed tags. These instructions apply to those existing tags, not to all versions above a particular number: plugins version independently, and current releases use the GitHub-native process described above. Enabling immutability does not protect older releases retroactively; a historical signature alone does not establish that its GitHub release is immutable. + +### Get the expected signer independently + +The historical release signer is [hesreallyhim](https://github.com/hesreallyhim). Its public key is listed in [that account's SSH signing keys](https://api.github.com/users/hesreallyhim/ssh_signing_keys) with fingerprint `SHA256:IVsf0Jed2MXKHQkW/FcYtahE6OiovA5+50GxsrZPs9E`. Authenticate the account through a channel you already trust and confirm that the key was authorized for the particular plugin and version. This page alone does not establish trust in the key; a replacement requires an authenticated maintainer announcement. -After verification, record the tag object ID and the commit ID. They identify different Git objects. Use that verified tree when inspecting or installing the plugin. +Obtain the release-signing public key and expected complete SHA256 fingerprint independently of the candidate release, through direct contact with a known maintainer or a previously authenticated project announcement. A key inside the candidate tag, a key comment, or a “Verified” badge alone does not establish that authority. + +Save the public key as `release-signing.pub` outside the source checkout and compare this output with the independently obtained fingerprint, character for character: ```sh -git rev-parse "refs/tags/$tag" -git rev-parse "refs/tags/$tag^{commit}" -git switch --detach "refs/tags/$tag^{commit}" +ssh-keygen -lf release-signing.pub -E sha256 ``` -Check the version under `plugins/PLUGIN/.claude-plugin/plugin.json` and read the corresponding `docs/release-notes/PLUGIN/VERSION.md`. +If it matches, create a local verification file. Its first field is your local label for the trusted release signer: -## Verify the GitHub release and its evidence +```sh +{ printf 'release-maintainer namespaces="git" '; cat release-signing.pub; } > allowed_signers +signers="$PWD/allowed_signers" +``` -Using a GitHub CLI with [release verification](https://cli.github.com/manual/gh_release_verify), run these from a fresh download directory with the same `repo` and `tag` values: +If fingerprints disagree, the key changes without an authenticated notice, or you cannot establish authority for this release, obtain the correct key and applicable versions before continuing. + +### Verify the annotated tag + +Use Git with SSH signature support and OpenSSH with `ssh-keygen -Y` support. In the source checkout fetched above, with `signers` set to the absolute path of your trusted verification file, run: ```sh -gh release verify "$tag" --repo "$repo" --format json -gh release download "$tag" --repo "$repo" --pattern osv-results.json --pattern scan-scope.md -gh release verify-asset "$tag" osv-results.json --repo "$repo" -gh release verify-asset "$tag" scan-scope.md --repo "$repo" +git cat-file -p "refs/tags/$tag" +git -c gpg.openpgp.program=false -c gpg.x509.program=false -c gpg.ssh.allowedSignersFile="$signers" verify-tag "refs/tags/$tag" ``` -In the JSON verification result, find the release's Git subject under `verificationResult.statement.subject`. Require its repository and tag to match the requested release, and its `digest.sha1` to match the **tag object ID** recorded above. For these annotated tags, that digest identifies the signed tag object, not the peeled commit; the verified tag binds it to the commit you checked out. The first command checks GitHub’s release attestation; each [verify-asset](https://cli.github.com/manual/gh_release_verify-asset) command checks the downloaded bytes. This check does not apply to GitHub’s automatically generated source archives. Read the reviewed release notes from the signed Git tree: GitHub permits editing the displayed notes even after publication. +Require an object of type `tag`; a signed header saying `type commit` and `tag` followed by the exact requested tag name; and successful verification with a **Good "git" signature** for your allowed principal and expected SSH key fingerprint. Checking the signed name prevents a valid signed tag from being relabeled as another historical release. A signed commit alone does not satisfy this historical tag-signature check. -Read `scan-scope.md` alongside the JSON for the revision, tooling and dependency inputs covered. Matching those files to the release proves which report was attached. It does not prove that the code, plugin guidance, generated workflows or all downstream dependencies are free of vulnerabilities. If a required check fails, do not use that copy; keep the tag, object IDs and error, and contact the maintainer through a known channel. +Record both the tag object ID and its peeled commit ID, then [verify the release and evidence](#verify-the-release-and-its-evidence). For an annotated tag, the attested Git digest must match the tag object ID, not the peeled commit. diff --git a/docs/criteria-maintenance.md b/docs/criteria-maintenance.md index d195e20..c2fefb1 100644 --- a/docs/criteria-maintenance.md +++ b/docs/criteria-maintenance.md @@ -53,8 +53,8 @@ Use the revision recorded in the particular guidance being reviewed, rather than ## Release and automation -Weekly checks download the public application pages, compare the bundled catalog, and retain evidence without modifying files in Git or creating PRs. Routine tests remain offline against saved fixtures. +The independent weekly or manually triggered criteria audit downloads the public application pages, compares the bundled catalog, and retains evidence without modifying files in Git or creating PRs. A reported difference or download failure is advisory: investigate it as maintenance work; it never blocks publication. Routine tests remain offline against saved fixtures. -PRs that change files under Badge Buddy’s `assets/criteria/` run fresh website verification. Changing the bundled catalog requires a version decision for Badge Buddy. Preparing a signed Badge Buddy release repeats the live check against that exact commit; releases of other plugins do not run it. Use `make release-check BADGE_REPO=../best-practices-badge` to run the live check and local tests yourself. See [plugin releases](releases.md) for the release procedure. +Changing the bundled catalog still requires a version decision for Badge Buddy. Use `make criteria-audit BADGE_REPO=../best-practices-badge` for a strict live check against the selected upstream checkout; this maintenance command fails on disagreement or incomplete evidence. `make release-check` is an offline alias for `make check` and does not require the live website to match the bundled catalog. See [plugin releases](releases.md) for publication. Downloaded content is used under the website's published terms and licensing. Retain the OpenSSF Best Practices badge contributors' attribution and the applicable notices when distributing derived material. Respect the site's robots policy and rate limits. diff --git a/docs/release-notes/README.md b/docs/release-notes/README.md index f879899..0bb0ad7 100644 --- a/docs/release-notes/README.md +++ b/docs/release-notes/README.md @@ -4,4 +4,4 @@ For each plugin version selected for release, add a reviewed Markdown file at `d Write for a maintainer deciding whether and how to upgrade. Lead with the user-visible change; call out breaking behavior, required action or migration steps, and relevant compatibility or security fixes. Include important changes in shared files when they affect the plugin. For an initial public release, describe what is available and its limits. Omit empty sections. Do not use raw commit subjects as a substitute for review, predict a clean vulnerability scan, or disclose a confidential issue before coordinated publication. -The signed tag contains these notes. The release workflow uses the tagged file for the GitHub release body. Keep the signed copy as the historical record. See [Plugin releases](../releases.md) for signing, evidence and publication. +The release workflow reads these notes from the exact checked commit and uses them for the GitHub release body. Keep the copy in Git as the historical record; displayed GitHub release notes can be edited after publication. See [Plugin releases](../releases.md) for review, evidence, and publication, and [verification](../../VERIFYING.md) to authenticate that source. diff --git a/docs/releases.md b/docs/releases.md index ea9b98f..1520801 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -1,71 +1,34 @@ # Release a plugin -**Bump the manifest, sign the merged commit, then publish the checked draft.** The bump selects a new plugin version. The signed tag identifies its exact source. The immutable GitHub Release preserves the tag and the dependency-scan evidence. Each plugin releases independently; the marketplace has no version. - -Complete [repository and signer setup](repo-setup.md#authorize-release-signers) before releasing from a repository. +**Merge a version and its notes, review the checks, then approve publication in GitHub.** Each plugin releases independently; the marketplace has no version. Complete the one-time [repository setup](repo-setup.md#prepare-the-release-repository) first. ## 1. Choose the version in a PR -Edit `plugins//.claude-plugin/plugin.json` and add `docs/release-notes//.md`. [Write the notes for someone deciding whether to update](release-notes/README.md). You can merge ordinary development work without a bump. For a plugin with no release tags in the target repository, choose its initial version; if the manifest version stays unchanged, add its first reviewed notes in the PR you intend to tag. Once the plugin has release tags, version changes must increase its semantic version. A prerelease suffix produces a GitHub prerelease. - -Run `make check`. To preview the version changes in your committed PR, run `make release-plan RELEASE_BASE=origin/main` in a full clone with current remote refs. Merge once the checks pass. Record the **full merged commit SHA from that PR**; later work on main does not belong to this release. - -## 2. Sign the release tag - -From a trusted clone of the target repository, set the values below. For example, a Release Buddy version of `0.1.0` would give `release-buddy--v0.1.0`. Use your chosen version. - -```sh -REPO=OWNER/REPOSITORY -PLUGIN=release-buddy -VERSION=YOUR_CHOSEN_VERSION -COMMIT=FULL_MERGED_COMMIT_SHA -TAG="$PLUGIN--v$VERSION" -KEY=/absolute/path/to/your/release-signing.pub -SIGNERS=/absolute/path/to/your/trusted/allowed_signers - -git remote -v -git fetch --no-tags origin refs/heads/main:refs/remotes/origin/main -git merge-base --is-ancestor "$COMMIT" origin/main -git show "$COMMIT:plugins/$PLUGIN/.claude-plugin/plugin.json" -git show "$COMMIT:docs/release-notes/$PLUGIN/$VERSION.md" -``` - -Stop if the remote, ancestry check, version or notes are wrong. With the approved private key available in your SSH agent, sign one annotated tag and verify it locally. Only push if verification succeeds and the tag identifies the intended commit: - -```sh -git -c gpg.format=ssh -c user.signingkey="$KEY" tag -s "$TAG" "$COMMIT" -m "Release $PLUGIN $VERSION" -git -c gpg.ssh.allowedSignersFile="$SIGNERS" verify-tag "refs/tags/$TAG" -git rev-parse "refs/tags/$TAG^{commit}" -git push origin "refs/tags/$TAG:refs/tags/$TAG" -``` +Edit `plugins//.claude-plugin/plugin.json` and add `docs/release-notes//.md`. [Write the notes for someone deciding whether to update](release-notes/README.md). Ordinary development work can merge without a bump. For a plugin with no release tags, add its initial reviewed notes in the PR that should release it; its manifest version may stay unchanged. Once the plugin has release tags, version changes must increase its semantic version. A prerelease suffix produces a GitHub prerelease. -If the tag already exists, inspect it instead of replacing it. A signed commit with an unsigned tag is insufficient. Never send the private signing key to Actions. +Run `make check`. To preview the version changes in your committed PR, run `make release-plan RELEASE_BASE=origin/main` in a full clone with current remote refs. Merge once the required checks pass. -## 3. Prepare the draft and review the OSV results +## 2. Review and approve in GitHub -```sh -gh workflow run release.yml --repo "$REPO" --ref main -f tag="$TAG" -``` +The push to `main` starts the **release** workflow. It plans releases from that push, runs `make check`, and scans dependencies at the exact pushed commit (`github.sha`). Publication waits for `hesreallyhim` to approve the `release` environment. Review the commit, planned versions, reviewed notes, and scan evidence in that run before approving. -Open the **release → Prepare** run on GitHub. It checks the signer, manifest, notes and commit, runs the tests and dependency scan, and prepares an unpublished draft. Badge Buddy additionally repeats its [live criteria check](criteria-maintenance.md). Review the draft notes and its two attachments: +| File | What to review | +| ------------------ | -------------------------------------------------------------------- | +| `scan-scope.md` | Commit, date, scanner version, platform, package count, and outcome. | +| `osv-results.json` | Package inventory and any advisory IDs. | -| File | What to do with it | -| ------------------ | --------------------------------------------------------------------------------------------------- | -| `scan-scope.md` | Check the commit, date, scanner version, platform, package count and outcome. | -| `osv-results.json` | Inspect the package inventory and any advisory IDs. Keep this report with the release it describes. | +The scan checks **maintainer tooling**: the root npm lockfile and the Python dependencies resolved from `requirements-dev.txt`, including transitive wheels for the scan platform. It does not scan plugin instructions, workflow behavior, or software installed by users. A clean result means no known advisories were reported for that inventory at that time. A finding or an incomplete scan blocks publication. The same scan also runs weekly on the default branch. -The scan checks **maintainer tooling**: the root npm lockfile and the Python dependencies resolved from `requirements-dev.txt`, including transitive wheels for the scan platform. It does not scan plugin instructions, workflow behavior, or software installed by users. A clean result means no known advisories were reported for that inventory at that time. +Badge Buddy's live criteria comparison is separate, advisory maintenance. Website drift or an unavailable website does not block a release; [investigate it through criteria maintenance](criteria-maintenance.md). -The same scan runs weekly on the default branch. A finding or an incomplete scan blocks draft preparation. Open the failed run’s summary and available evidence, investigate the advisory and record the disposition. Fix affected dependencies in a PR; if changing already tagged inputs, make a new version and tag. Retry network or service failures against the same tag. To investigate locally, use the OSV-Scanner version pinned in [the scan helper](../tools/scan_dependencies.py) and run `make dependency-scan`; output is in `.cache/dependency-scan/`. Local resolution may differ from Linux CI. +After approval, the workflow creates each lightweight tag, such as `release-buddy--v0.1.0`, at the same checked commit, attaches the evidence, publishes the immutable GitHub Release, and verifies its release attestation and assets. This process uses GitHub's environment approval and release attestation; it does not require a personal SSH signing key, a manually pushed tag, a workflow dispatch, or local finalization. Repository writers are trusted: they can also publish directly, so the environment approval governs this workflow rather than every route to publication. Follow [consumer verification](../VERIFYING.md) from a separate checkout after the first release. -## 4. Publish and verify +## If a run stops -Use a trusted checkout of this repository’s current `main` with the release tag fetched. Copy the **exact command from the successful Prepare run’s summary**: +For a transient failure, rerun the original workflow run. Its commit remains the original `github.sha` even if `main` has advanced. A dependency fix belongs in a PR; review the resulting new run before approving publication. To investigate a scan locally, use the OSV-Scanner version pinned in [the scan helper](../tools/scan_dependencies.py) and run `make dependency-scan`; evidence is written to `.cache/dependency-scan/`. Local dependency resolution may differ from Linux CI. -```sh -make release-finalize REPO=OWNER/REPOSITORY TAG=PLUGIN--vVERSION RUN=SUCCESSFUL_RUN_ID -``` +A retry verifies the original tag, commit, immutable attestation, and attached evidence of an already published release without rewriting it. Later edits to its displayed title, notes, or prerelease label do not invalidate that retry; the reviewed source notes remain in Git. New publication strictly checks the title, notes, prerelease status, and evidence before publishing. -This is the step that publishes. It compares the draft with the signed notes and the successful run’s evidence, checks that GitHub has release immutability enabled, publishes, then verifies the immutable release. The administration read permission needed for the settings check stays in your local GitHub CLI session. Follow [Verifying a plugin release](../VERIFYING.md) once from a separate checkout as a consumer would. +If a partial draft exists, keep it unpublished and inspect its tag, ownership, files, and digests. Retain its evidence before deliberately removing only that unpublished draft and retrying the original run. Tags without a published immutable release may be corrected or deleted after inspecting the intended commit and retaining relevant evidence; do not overwrite unknown draft assets. Publishing an immutable release locks its associated tag and assets while that release exists. Correct a bad published release with a new version. -**If something stops:** Before a draft exists, fix the reported cause and rerun. If a partial draft exists or its preparation receipt is unavailable, keep it unpublished. Inspect ownership, tag, files and digests; after retaining its evidence, remove only that unpublished draft, keep the signed tag, and dispatch again. Never overwrite unknown assets or publish through the UI to bypass a failed check. If finalization was interrupted, check whether publication already occurred and retry the same command. Correct a bad published release with a new version. +Release immutability must remain enabled in repository or organization settings. The workflow's token cannot read that administration setting; verification after publication detects a missing immutable attestation but cannot undo a mutable release that has already been published. See the [setup prerequisite](repo-setup.md#prepare-the-release-repository). diff --git a/docs/repo-setup.md b/docs/repo-setup.md index 290e978..d9daf9c 100644 --- a/docs/repo-setup.md +++ b/docs/repo-setup.md @@ -31,30 +31,23 @@ Open **Settings → Branches** and edit the existing rule for `main`, or choose If an existing ruleset supplies these protections, review its effective settings rather than adding a competing classic rule. GitHub documents the controls in [Managing a branch protection rule](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule). -No release job needs a bypass of branch protection. Maintainers push signed tags for reviewed commits; the workflow creates GitHub drafts and does not commit to `main`. +No release job needs a bypass of branch protection. The approved publication job creates release tags and GitHub Releases at the checked commit; it does not commit to `main`. ## Configure squash merging In **Settings → General → Pull Requests**, enable squash merging and disable merge commits and rebase merging. Set the default squash commit message to use the pull-request title, so the checked conventional title becomes the commit title even for a single-commit PR. See [GitHub's squash merge settings](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests). -Reopen the settings to confirm they were saved, and inspect a pull request to confirm that the three intended checks are required and squash merging is the available merge method. Complete the release-specific setup below before the first draft. +Reopen the settings to confirm they were saved, and inspect a pull request to confirm that the three intended checks are required and squash merging is the available merge method. Complete the release-specific setup below before the first publication. -## Authorize release signers - -Choose who may authorize a release. Each signer keeps the private SSH signing key on their own machine, agent or hardware device. Authenticate the public key and fingerprint using the [signer verification procedure](../VERIFYING.md#get-the-expected-signer-independently) before enrolling it. - -Maintain an OpenSSH allowed-signers file containing one entry per approved key. Each entry consists of the maintainer principal, the restriction `namespaces="git"`, and the public key type and base64 value. For a single public key, create a line locally with the actual principal and previously verified public key: - -```sh -{ printf '%s namespaces="git" ' "$MAINTAINER_PRINCIPAL"; cat release-signing.pub; } > allowed_signers -``` +## Prepare the release repository -In **Settings → Secrets and variables → Actions → Variables**, set `RELEASE_ALLOWED_SIGNERS` to the contents of the reviewed file, and `RELEASE_REPOSITORY` to the target repository’s exact `OWNER/REPO`. Both must be **repository variables**, since validation runs before entering the release environment. The allowlist is public verification material but controls who may authorize releases; restrict who may change it. Publish the keys and their fingerprints through a channel consumers can authenticate independently of the release tag. Document which versions each key covers. Update both the Actions variable and the public notice on rotation or revocation; retain historical verification information and distinguish a compromise from an ordinary retirement. +1. In **Settings → Secrets and variables → Actions → Variables**, set the repository variable `RELEASE_REPOSITORY` to the exact target `OWNER/REPO`. This enables publication only in the intended repository. +2. In **Settings → Environments**, configure an environment named `release`. Limit deployment to `main`, with `hesreallyhim` as a required reviewer. Allow self-review for this single-owner repository and disable administrator bypass. This approval authorizes publication of the exact commit whose checks and scan completed in that run. No environment secret or personal signing key is needed. +3. In **Settings → General → Releases**, enable [release immutability](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/prevent-release-changes), or confirm an organization policy enables it for this repository. This is a one-time prerequisite that must remain enabled; it applies only to future releases. The workflow's `GITHUB_TOKEN` cannot read the administration setting. It verifies the attestation after publishing, but that check cannot prevent an already-published mutable release if an administrator disables immutability. +4. No custom release-tag creation or preservation rulesets are required. Repository writers are trusted to manage tags and releases, including correcting or deleting tags that are not attached to a published immutable release. Once an immutable release is published, GitHub locks its associated tag and assets while that release exists. This protection does not apply retroactively to older releases or to unpublished tags. +5. Confirm Actions policy permits job-level `contents: write` for publication and read-only access for planning, checks, and scans. Keep `main` and the `release` environment protected: the reviewed workflow, successful checks, and owner approval govern publication through this workflow. Repository writers can also publish releases directly; the environment is not a repository-wide release-access restriction. No additional secret token or signing bot is needed. +6. Follow the [release guide](releases.md) with a deliberately selected plugin version. Setup remains incomplete until a run confirms that tag creation is permitted, publication waits for owner approval, and the release attestation identifies the checked commit. After publication, use [consumer verification](../VERIFYING.md) from a separate checkout. -## Prepare the release repository +The live `release` environment is configured for `main` only, with `hesreallyhim` as required reviewer, administrator bypass disabled, and self-approval allowed because the owner initiates releases. Release immutability is enabled. The release policy uses ordinary writer permissions without custom release-tag rulesets. -1. Under **Settings → Environments**, configure an environment named `release`. Limit deployment to the branch `main`; do not permit tag refs or other branches. The maintainer’s local publication step is the human decision; a second environment reviewer is optional. No environment secret is required for signing or publication. -2. Under **Settings → General → Releases**, enable [release immutability](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/prevent-release-changes) before publishing. Enabling it only affects future releases. Use an authorized local GitHub CLI session for finalization. It needs Administration: read for the immutable-release setting, Actions: read for the successful run and artifacts, Variables: read for the independent signer allowlist, and Contents: write to publish the draft. These permissions are for the maintainer; Actions does not need an administration token. -3. Protect release tags against updates and deletion. Use tag rulesets matching this repository’s actual plugin tag names, and authorize only designated maintainers to create them. If granting a bypass to allow tag creation, use separate creation and update/deletion rulesets so that a release signer cannot bypass both protections with the same grant. Check organization rules too. -4. Confirm Actions policy permits the draft job’s job-level `contents: write` and the read-only validation and scan jobs. A secret token, GitHub App private key or bot that pushes tags is not needed. Keep `main` and the release environment protected: their workflows govern what reaches the draft. -5. Follow the [release guide](releases.md) using one deliberately selected version for the first plugin. Test signer recognition, notes, scanning and draft preparation before finalization. After publication, use [consumer verification](../VERIFYING.md) from a separate checkout. +Historical SSH-signed tags remain verifiable using the [historical signer instructions](../VERIFYING.md#historical-ssh-signed-tags). Their signer allowlist is not an input to the current publication workflow. diff --git a/tests/maintenance/test_finalize_release.py b/tests/maintenance/test_finalize_release.py deleted file mode 100644 index 37db257..0000000 --- a/tests/maintenance/test_finalize_release.py +++ /dev/null @@ -1,140 +0,0 @@ -"""The only operation allowed to publish a draft must fail closed.""" - -from pathlib import Path -import sys -import unittest -from unittest import mock - -sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "tools")) -import finalize_release as finalize - - -class FinalizationTests(unittest.TestCase): - def setUp(self): - self.repo = "fixture/plugins" - self.tag = "release-buddy--v1.0.0" - self.base = f"repos/{self.repo}" - self.settings_enabled = True - self.writes = [] - self.plugin = { - "tag": self.tag, - "object": "1" * 40, - "head": "2" * 40, - "name": "release-buddy", - "version": "1.0.0", - "prerelease": False, - } - hashes = dict.fromkeys(finalize.release.ASSETS, "sha256:" + "a" * 64) - self.receipt = {**self.plugin, "draft_id": 12, "assets": hashes} - self.record = { - "id": 12, - "tag_name": self.tag, - "name": "release-buddy 1.0.0", - "target_commitish": self.plugin["head"], - "prerelease": False, - "assets": [ - {"name": k, "digest": v, "state": "uploaded"} for k, v in hashes.items() - ], - "body": "Reviewed notes", - "html_url": "https://example.invalid/release", - "draft": True, - "immutable": False, - } - for module, name, kwargs in [ - (finalize, "load_receipt", {"return_value": self.receipt}), - (finalize.release, "verify_tag", {"return_value": self.plugin}), - (finalize.release, "check_remote_ref", {}), - (finalize.release, "release_notes", {"return_value": "Reviewed notes\n"}), - (finalize.release, "run", {}), - (finalize.release, "api", {"side_effect": self.api}), - ]: - self.enter_patch(module, name, kwargs) - - def enter_patch(self, module, name, kwargs): - patch = mock.patch.object(module, name, **kwargs) - patch.start() - self.addCleanup(patch.stop) - - def api(self, endpoint, *args): - if endpoint.endswith("/actions/variables/RELEASE_REPOSITORY"): - return {"value": self.repo} - if endpoint.endswith("/actions/variables/RELEASE_ALLOWED_SIGNERS"): - return {"value": "public fixture key"} - if endpoint.endswith("/immutable-releases"): - return {"enabled": self.settings_enabled} - self.assertEqual(endpoint, self.base + "/releases/12") - if args: - self.assertIn("PATCH", args) - self.assertIn("draft=false", args) - self.writes.append(endpoint) - self.record.update(draft=False, immutable=True) - return self.record.copy() - - def finish(self): - finalize.finalize(self.repo, self.tag, "1234") - - def test_publish_and_retry_preserve_same_verified_release(self): - self.finish() - self.finish() - self.assertEqual(self.writes, [self.base + "/releases/12"]) - finalize.release.run.assert_called_with( - "gh", "release", "verify", self.tag, "--repo", self.repo - ) - - def test_changed_asset_is_rejected_before_publication(self): - self.record["assets"][0]["digest"] = "sha256:" + "f" * 64 - with self.assertRaisesRegex(ValueError, "assets"): - self.finish() - self.assertFalse(self.writes) - - def test_disabled_immutability_leaves_draft_intact(self): - self.settings_enabled = False - with self.assertRaisesRegex(ValueError, "immutability"): - self.finish() - self.assertFalse(self.writes) - - def test_retagged_object_at_same_commit_is_rejected(self): - self.receipt["object"] = "f" * 40 - with self.assertRaisesRegex(ValueError, "signed tag"): - self.finish() - self.assertFalse(self.writes) - - -class PreparationRunTests(unittest.TestCase): - repo = "fixture/plugins" - tag = "release-buddy--v1.0.0" - - def test_short_ref_named_main_cannot_supply_an_off_branch_receipt(self): - run = { - "path": ".github/workflows/release.yml", - "event": "workflow_dispatch", - "head_branch": "main", - "display_title": f"Prepare {self.tag}", - "conclusion": "success", - "status": "completed", - "head_sha": "3" * 40, - } - with mock.patch.object( - finalize.release, "api", side_effect=[run, {"status": "diverged"}] - ): - with self.assertRaisesRegex(ValueError, "workflow commit"): - finalize.load_receipt(self.repo, "1", self.tag, Path("unused")) - - def test_another_workflow_or_failed_run_cannot_supply_evidence(self): - good = { - "path": ".github/workflows/release.yml", - "event": "workflow_dispatch", - "head_branch": "main", - "display_title": "Prepare " + self.tag, - "conclusion": "success", - "status": "completed", - } - for key, value in ( - ("path", "other.yml"), - ("conclusion", "failure"), - ("head_branch", "feature"), - ("display_title", "Prepare other--v1.0.0"), - ("event", "pull_request"), - ): - with self.subTest(key=key), self.assertRaises(ValueError): - finalize.check_run({**good, key: value}, self.tag) diff --git a/tests/maintenance/test_plugin_release.py b/tests/maintenance/test_plugin_release.py index 248f7dd..2d79fd3 100644 --- a/tests/maintenance/test_plugin_release.py +++ b/tests/maintenance/test_plugin_release.py @@ -1,4 +1,4 @@ -"""Release policy, real signed Git objects and fail-closed draft preparation.""" +"""Release planning, exact Git commit binding and fail-closed native publication.""" from __future__ import annotations @@ -33,7 +33,6 @@ def setUp(self): self.git("config", "user.email", "fixture@example.invalid") self.git("config", "commit.gpgsign", "false") self.git("config", "tag.gpgsign", "false") - self.allow = self.root / "allowed_signers" self.manifest("1.0.0") self.write( ".claude-plugin/marketplace.json", @@ -69,37 +68,32 @@ def commit(self): self.git("commit", "-qm", "fixture") return self.git("rev-parse", "HEAD") - def key(self, name="release"): - key = self.root / name - subprocess.run( - ["ssh-keygen", "-q", "-t", "ed25519", "-N", "", "-f", str(key)], check=True - ) - return key - - def sign(self, tag=None): - key = self.key() - self.allow.write_text( - 'maintainer namespaces="git" ' + key.with_suffix(".pub").read_text() - ) - self.git( - "-c", - "gpg.format=ssh", - "-c", - f"user.signingkey={key}", - "tag", - "-sm", - "Release", - tag or self.tag, - ) - def test_initial_version_can_decrease_in_new_repo_only(self): self.manifest("0.1.0") self.commit() self.assertEqual(release.plan(self.base)["plugins"][0]["tag"], "alpha--v0.1.0") + self.git("tag", "alpha--v0.1.0", "HEAD") + self.assertEqual(release.plan(self.base)["plugins"][0]["tag"], "alpha--v0.1.0") self.git("tag", "alpha--v0.4.0", self.base) + self.write("later-work", "This is not the exact tagged release commit.") + self.commit() with self.assertRaisesRegex(ValueError, "must increase"): release.plan(self.base) + def test_initial_reset_rerun_survives_later_release_tags(self): + self.manifest("0.1.0") + first_head = self.commit() + first_plan = release.plan(self.base, first_head) + self.git("tag", "alpha--v0.1.0", first_head) + self.manifest("0.2.0") + later_head = self.commit() + self.git("tag", "alpha--v0.2.0", later_head) + self.assertEqual(release.plan(self.base, first_head), first_plan) + self.manifest("0.0.5") + decrease_head = self.commit() + with self.assertRaisesRegex(ValueError, "must increase"): + release.plan(later_head, decrease_head) + def test_version_rules_and_notes(self): self.manifest("1.0.0+metadata") self.commit() @@ -145,232 +139,348 @@ def test_criteria_require_badge_version_change(self): self.commit() self.assertEqual(release.plan(base)["plugins"][0]["tag"], "badge-buddy--v0.1.1") - def test_signed_tag_verified_against_allowed_key_only(self): - self.sign() - result = release.verify_tag(self.tag, self.allow) - self.assertEqual(result["head"], self.base) - self.assertEqual(result["object"], self.git("rev-parse", self.tag)) - self.assertNotEqual(result["object"], result["head"]) - self.allow.write_text( - "other " + self.key("other").with_suffix(".pub").read_text() - ) - with self.assertRaises(subprocess.CalledProcessError): - release.verify_tag(self.tag, self.allow) - - def test_tag_delimiter_inside_a_valid_prerelease_identifier(self): - version = "1.0.1-alpha--v2" - self.manifest(version) - self.git("update-ref", "refs/remotes/origin/main", self.commit()) - tag = f"alpha--v{version}" - self.sign(tag) - self.assertEqual(release.verify_tag(tag, self.allow)["version"], version) - - def verify_preflight_command(self, expected_object, expected_head): - output, errors = io.StringIO(), io.StringIO() - with patch("sys.stdout", output), patch("sys.stderr", errors): - code = release.main([ - "verify-tag", "--tag", self.tag, - "--allowed-signers", str(self.allow), - "--expected-object", expected_object, - "--expected-head", expected_head, - ]) - return code, output.getvalue(), errors.getvalue() - - def test_preflight_binding_accepts_a_signed_historical_main_commit(self): - self.sign() - tag_object = self.git("rev-parse", self.tag) - self.write("later-main-work", "The release decision remains an ancestor.") - self.git("update-ref", "refs/remotes/origin/main", self.commit()) - - code, output, errors = self.verify_preflight_command(tag_object, self.base) - self.assertEqual(0, code, errors) - self.assertIn(f"head={self.base}\n", output) - self.assertIn(f"object={tag_object}\n", output) - - def test_preflight_binding_rejects_mismatched_or_empty_identities_without_outputs(self): - self.sign() - tag_object = self.git("rev-parse", self.tag) - for expected_object, expected_head, message in ( - ("0" * 40, self.base, "signed tag changed"), - (tag_object, "0" * 40, "release commit changed"), - ("", self.base, "signed tag changed"), - (tag_object, "", "release commit changed"), - ): - with self.subTest(object=expected_object, head=expected_head): - code, output, errors = self.verify_preflight_command( - expected_object, expected_head - ) - self.assertEqual(1, code) - self.assertEqual("", output) - self.assertIn(message, errors) - - def test_preflight_binding_rejects_a_replacement_signed_tag_at_the_same_commit(self): - self.sign() - original_object = self.git("rev-parse", self.tag) - self.git( - "-c", "gpg.format=ssh", - "-c", f"user.signingkey={self.root / 'release'}", - "tag", "-fsm", "Replacement annotation", self.tag, - ) - self.assertNotEqual(original_object, self.git("rev-parse", self.tag)) - code, output, errors = self.verify_preflight_command(original_object, self.base) - self.assertEqual(1, code) - self.assertEqual("", output) - self.assertIn("signed tag changed since preflight", errors) - - def test_preflight_binding_does_not_bypass_signature_validation(self): - self.sign() - tag_object = self.git("rev-parse", self.tag) - self.allow.write_text("other " + self.key("other").with_suffix(".pub").read_text()) - code, output, errors = self.verify_preflight_command(tag_object, self.base) - self.assertEqual(1, code) - self.assertEqual("", output) - self.assertIn("Plugin release failed", errors) - - def test_annotated_but_unsigned_and_lightweight_refused(self): - self.allow.touch() - self.git("tag", self.tag) - with self.assertRaisesRegex(ValueError, "annotated"): - release.verify_tag(self.tag, self.allow) - self.git("tag", "-fam", "Unsigned", self.tag) - with self.assertRaises(subprocess.CalledProcessError): - release.verify_tag(self.tag, self.allow) - - def test_relocated_tag_object_and_wrong_version_refused(self): - self.sign("alpha--v1.2.3") - with self.assertRaisesRegex(ValueError, "manifest"): - release.verify_tag("alpha--v1.2.3", self.allow) - self.git( - "update-ref", - "refs/tags/" + self.tag, - self.git("rev-parse", "alpha--v1.2.3"), - ) - with self.assertRaisesRegex(ValueError, "signed tag name"): - release.verify_tag(self.tag, self.allow) - - def test_later_main_commit_inheriting_a_version_is_not_a_decision(self): - self.write("unrelated", "work") - self.git("update-ref", "refs/remotes/origin/main", self.commit()) - self.sign() - with self.assertRaisesRegex(ValueError, "version decision"): - release.verify_tag(self.tag, self.allow) - - def test_adding_first_notes_for_initial_public_version_is_a_decision(self): + def test_first_notes_without_version_change_and_idempotent_tag(self): notes = Path("docs/release-notes/alpha/1.0.0.md") notes.unlink() - self.commit() - notes.write_text("Reviewed first public release.\n") + base = self.commit() + notes.write_text("Reviewed initial public release.\n") head = self.commit() - self.git("update-ref", "refs/remotes/origin/main", head) - self.sign() - self.assertEqual(release.verify_tag(self.tag, self.allow)["head"], head) - - def test_unmerged_commit_is_not_a_release(self): - self.write("unmerged", "work") + self.assertEqual(release.plan(base, head)["plugins"][0]["tag"], self.tag) + self.git("tag", self.tag, head) + self.assertEqual(len(release.plan(base, head)["plugins"]), 1) + self.git("tag", "-f", self.tag, base) + self.assertEqual(release.plan(base, head)["plugins"], []) + + def test_changed_existing_notes_do_not_release_again(self): + Path("docs/release-notes/alpha/1.0.0.md").write_text("Edited text.\n") self.commit() - self.sign() - with self.assertRaisesRegex(ValueError, "not reachable"): - release.verify_tag(self.tag, self.allow) + self.assertEqual(release.plan(self.base)["plugins"], []) - -class DraftTests(unittest.TestCase): + def test_exact_checkout_accepts_historical_main_when_main_advances(self): + self.write("later", "work") + self.git("update-ref", "refs/remotes/origin/main", self.commit()) + self.git("checkout", "--detach", self.base) + release.check_checkout("empty", self.base) + for head in ("HEAD", self.base[:12], "f" * 40, self.base.upper()): + with ( + self.subTest(head=head), + self.assertRaisesRegex(ValueError, "full event SHA"), + ): + release.check_checkout("empty", head) + + def test_checkout_requires_main_ancestry_and_event_base_ancestry(self): + self.write("later", "work") + head = self.commit() + with self.assertRaisesRegex(ValueError, "origin/main"): + release.check_checkout(self.base, head) + self.git("update-ref", "refs/remotes/origin/main", head) + self.git("checkout", "--detach", self.base) + with self.assertRaisesRegex(ValueError, "event base"): + release.check_checkout(head, self.base) + + +SCOPE = ( + "# Dependency scan\n\nCommit: `{head}`\n\n" + "Scanned at {timestamp} using OSV-Scanner 2.7.0; Python 3.13.0 on Linux x86_64.\n\n" + "Scope: repository maintainer tooling in the root npm lockfile (including dev dependencies) " + "and requirements-dev.txt, including transitive wheels resolved for this platform at scan time. " + "This is not a scan of consumers' dependencies, sample workflows, action implementations, " + "pre-commit hook environments, or host system packages. Results cover known OSV advisories.\n\n" + "Compared 1 distinct ecosystem/name/version coordinates.\n\n" + "PASS: no known vulnerabilities found.\n" +) + + +def write_evidence(directory, head, timestamp="2026-11-13T00:00:00+00:00"): + report = { + "results": [ + { + "packages": [ + { + "package": { + "ecosystem": "npm", + "name": "example", + "version": "1.0.0", + } + } + ] + } + ] + } + (directory / "osv-results.json").write_text(json.dumps(report)) + (directory / "scan-scope.md").write_text( + SCOPE.format(head=head, timestamp=timestamp) + ) + return release.evidence_digests(directory) + + +class PublicationTests(unittest.TestCase): def setUp(self): temp = tempfile.TemporaryDirectory() self.addCleanup(temp.cleanup) self.evidence = Path(temp.name) - self.digests = {} - for file in release.ASSETS: - payload = f"an example {file}\n".encode() - (self.evidence / file).write_bytes(payload) - self.digests[file] = "sha256:" + hashlib.sha256(payload).hexdigest() self.plugin = { "name": "alpha", "version": "1.0.0-beta.1", "tag": "alpha--v1.0.0-beta.1", "head": "a" * 40, - "object": "b" * 40, "prerelease": True, } - self.existing = False - self.remote_object = self.plugin["object"] - self.uploads = [] - self.calls = [] - self.pending = None - self.asset_digests = self.digests.copy() - api = patch.object(release, "api", side_effect=self.github) - self.addCleanup(api.stop) - api.start() - notes = patch.object(release, "release_notes", return_value="Reviewed notes.\n") - self.addCleanup(notes.stop) - notes.start() - - def github(self, endpoint, *args, **_kwargs): + self.hashes = write_evidence(self.evidence, self.plugin["head"]) + self.original_bytes = { + name: (self.evidence / name).read_bytes() for name in release.ASSETS + } + self.ref = None + self.record = None + self.foreign_draft = False + self.upload_bad_digest = False + self.bad_draft = None + self.immutable_enabled = True + self.calls, self.writes = [], [] + for name, kwargs in ( + ("check_checkout", {}), + ("plan", {"return_value": {"plugins": [self.plugin]}}), + ("release_notes", {"return_value": "Reviewed notes.\n"}), + ("api", {"side_effect": self.github}), + ("run", {"side_effect": self.command}), + ): + mock = patch.object(release, name, **kwargs) + mock.start() + self.addCleanup(mock.stop) + + def command(self, *args, **kwargs): + if args[:3] == ("gh", "release", "download"): + directory = Path(args[args.index("--dir") + 1]) + for name, payload in self.original_bytes.items(): + (directory / name).write_bytes(payload) + return subprocess.CompletedProcess(args, 0, "", "") + + def github(self, endpoint, *args, **kwargs): self.calls.append((endpoint, args)) + if "--method" in args: + self.writes.append((endpoint, args)) if "/git/ref/tags/" in endpoint: - return {"object": {"sha": self.remote_object, "type": "tag"}} + return self.ref + if endpoint.endswith("/git/refs"): + self.assertIn("sha=" + self.plugin["head"], args) + self.assertIn("ref=refs/tags/" + self.plugin["tag"], args) + self.ref = {"object": {"type": "commit", "sha": self.plugin["head"]}} + return self.ref if "/releases/tags/" in endpoint: - return {"immutable": True} if self.existing else None + return self.record if endpoint == "graphql": - return {"data": {"repository": {"release": self.pending}}} - if endpoint.endswith("/releases") and "--input" in args: - self.created = json.loads(Path(args[-1]).read_text()) - return {"id": 12, "draft": True, "tag_name": self.plugin["tag"]} - if endpoint.startswith( - "https://uploads.github.com/repos/example/plugins/releases/12/assets?name=" - ): + return { + "data": { + "repository": { + "release": {"id": "foreign"} if self.foreign_draft else None + } + } + } + if endpoint.endswith("/releases"): + payload = json.loads(Path(args[-1]).read_text()) + self.record = { + **payload, + "id": 12, + "assets": [], + "html_url": "https://example.invalid/release", + } + return self.record.copy() + if endpoint.startswith("https://uploads.github.com/"): name = endpoint.split("=")[1] - self.assertEqual(Path(args[-1]), self.evidence / name) - self.uploads.append(name) - return {"digest": self.asset_digests[name], "state": "uploaded"} - self.fail(f"Unexpected API mutation or endpoint: {endpoint} {args}") - - def draft(self): - return release.prepare_draft("example/plugins", self.plugin, self.evidence) - - def test_prepares_only_unpublished_draft_with_reviewed_notes_and_evidence(self): - receipt = self.draft() + digest = ( + "sha256:" + "f" * 64 if self.upload_bad_digest else self.hashes[name] + ) + asset = {"name": name, "digest": digest, "state": "uploaded"} + self.record["assets"].append(asset) + return asset + if endpoint.endswith("/releases/12"): + if "PATCH" in args: + self.assertIn("draft=false", args) + self.record.update(draft=False, immutable=self.immutable_enabled) + record = self.record.copy() + if self.bad_draft and record["draft"]: + record.update(self.bad_draft) + return record + self.fail(f"Unexpected API request: {endpoint} {args}") + + def publish(self): + release.publish("b" * 40, self.plugin["head"], "example/plugins", self.evidence) + + def test_unsigned_lightweight_tag_and_immutable_release_at_exact_commit(self): + self.publish() self.assertEqual( - self.created, - { - "tag_name": self.plugin["tag"], - "name": "alpha 1.0.0-beta.1", - "body": "Reviewed notes.\n", - "target_commitish": self.plugin["head"], - "draft": True, - "prerelease": True, - "make_latest": "false", - }, + self.ref["object"], {"sha": self.plugin["head"], "type": "commit"} + ) + self.assertEqual(self.record["target_commitish"], self.plugin["head"]) + self.assertTrue(self.record["immutable"]) + self.assertFalse(self.record["draft"]) + release.run.assert_called_with( + "gh", "release", "verify", self.plugin["tag"], "--repo", "example/plugins" + ) + release.plan.assert_called_with("b" * 40, self.plugin["head"]) + self.assertFalse( + any("immutable-releases" in endpoint for endpoint, _ in self.calls) ) - self.assertEqual(self.uploads, list(release.ASSETS)) - self.assertEqual(receipt["assets"], self.digests) - self.assertEqual(receipt["object"], self.plugin["object"]) - self.assertEqual(receipt["draft_id"], 12) - - def test_existing_release_or_draft_never_modified(self): - self.existing = True - with self.assertRaisesRegex(ValueError, "already exists"): - self.draft() - self.existing = False - self.pending = {"id": 123} + + def test_immutable_rerun_uses_original_assets_not_new_scan_timestamps(self): + self.publish() + mutations = list(self.writes) + write_evidence(self.evidence, self.plugin["head"], "2026-11-14T00:00:00+00:00") + self.assertNotEqual(self.hashes, release.evidence_digests(self.evidence)) + self.publish() + self.assertEqual(self.writes, mutations) + + def test_conflicting_commit_and_annotated_tag_refused_before_writes(self): + for object_type, sha in (("commit", "c" * 40), ("tag", self.plugin["head"])): + self.ref = {"object": {"type": object_type, "sha": sha}} + with ( + self.subTest(kind=object_type), + self.assertRaisesRegex(ValueError, "conflicts"), + ): + self.publish() + self.assertEqual(self.writes, []) + + def test_existing_exact_lightweight_tag_is_preserved(self): + self.ref = {"object": {"type": "commit", "sha": self.plugin["head"]}} + self.publish() + self.assertFalse( + any(endpoint.endswith("/git/refs") for endpoint, _ in self.writes) + ) + + def test_foreign_draft_refused_without_mutation(self): + self.foreign_draft = True with self.assertRaisesRegex(ValueError, "existing draft"): - self.draft() - self.assertFalse(self.uploads) - - def test_changed_remote_object_or_bad_evidence_prevents_draft(self): - self.remote_object = self.plugin["head"] - with self.assertRaisesRegex(ValueError, "tag object changed"): - self.draft() - self.remote_object = self.plugin["object"] - (self.evidence / "extra").touch() - with self.assertRaisesRegex(ValueError, "expected exactly"): - self.draft() - self.assertFalse(self.uploads) + self.publish() + self.assertEqual(self.writes, []) + self.record = {"draft": True} + with self.assertRaisesRegex(ValueError, "existing draft"): + self.publish() + self.assertEqual(self.writes, []) - def test_mismatched_upload_digest_stops_after_first_upload(self): - self.asset_digests[release.ASSETS[0]] = "sha256:bad" + def test_upload_digest_mismatch_leaves_unpublished_draft(self): + self.upload_bad_digest = True with self.assertRaisesRegex(ValueError, "leave draft unpublished"): - self.draft() - self.assertEqual(self.uploads, [release.ASSETS[0]]) + self.publish() + self.assertTrue(self.record["draft"]) + self.assertEqual(len(self.record["assets"]), 1) + self.assertFalse(any("PATCH" in args for _, args in self.writes)) + + def test_draft_metadata_notes_and_asset_changes_block_publication(self): + for change in ( + {"id": 13}, + {"target_commitish": "c" * 40}, + {"body": "foreign notes"}, + {"assets": []}, + ): + with self.subTest(change=change): + self.record, self.ref, self.writes = None, None, [] + self.bad_draft = change + with self.assertRaises(ValueError): + self.publish() + self.assertFalse(any("PATCH" in args for _, args in self.writes)) + + def test_missing_immutability_fails_after_publication(self): + self.immutable_enabled = False + with self.assertRaisesRegex(ValueError, "did not confirm an immutable"): + self.publish() + self.assertFalse(self.record["draft"]) + self.assertFalse( + any( + call.args[:3] == ("gh", "release", "verify") + for call in release.run.call_args_list + ) + ) + + def test_immutable_retry_accepts_edited_display_fields(self): + self.publish() + writes = list(self.writes) + self.record.update( + body="Edited displayed release notes.", + name="New display title", + prerelease=False, + ) + self.publish() + self.assertEqual(writes, self.writes) + release.run.assert_called_with( + "gh", "release", "verify", self.plugin["tag"], "--repo", "example/plugins" + ) + + def test_published_release_with_changed_subject_or_bytes_is_not_accepted(self): + self.publish() + writes = list(self.writes) + for field, wrong in ( + ("tag_name", "alpha--v9.0.0"), + ("target_commitish", "c" * 40), + ): + original = self.record[field] + self.record[field] = wrong + with ( + self.subTest(field=field), + self.assertRaisesRegex(ValueError, "subject"), + ): + self.publish() + self.record[field] = original + self.record["assets"][0]["digest"] = "sha256:" + "f" * 64 + with self.assertRaisesRegex(ValueError, "bytes do not match"): + self.publish() + self.assertEqual(writes, self.writes) + + def test_editorial_scan_scope_changes_do_not_block_publication(self): + scope = ( + "# Maintainer dependency evidence\n\n" + f"Commit: `{self.plugin['head']}`\n\n" + "Scanned yesterday with an updated scanner on a new platform.\n\n" + "Scope: repository maintainer tooling; see scanner documentation.\n\n" + "Compared packages using the scanner's inventory validation.\n\n" + "PASS: no known vulnerabilities found.\n" + ) + (self.evidence / "scan-scope.md").write_text(scope) + self.hashes = release.evidence_digests(self.evidence) + self.publish() + self.assertFalse(self.record["draft"]) + + def test_malformed_evidence_prevents_all_mutation(self): + for content in ( + "{}", + "[]", + '{"results": []}', + '{"results": [{"packages": []}]}', + "not json", + ): + with self.subTest(content=content): + (self.evidence / "osv-results.json").write_text(content) + with self.assertRaises(ValueError): + self.publish() + self.assertEqual(self.writes, []) + + def test_scan_failure_wrong_or_duplicate_commit_prevents_mutation(self): + scope = (self.evidence / "scan-scope.md").read_text() + for bad in ( + scope.replace(self.plugin["head"], "c" * 40), + scope.replace("PASS:", "BLOCKED:"), + scope + "INCOMPLETE: failure\n", + scope + f"Commit: `{self.plugin['head']}`\n", + scope.replace("PASS: no known vulnerabilities found.\n", ""), + ): + with self.subTest(scope=bad): + (self.evidence / "scan-scope.md").write_text(bad) + with self.assertRaisesRegex(ValueError, "commit.*PASS"): + self.publish() + self.assertEqual(self.writes, []) + + def test_vulnerabilities_and_extra_artifacts_prevent_mutation(self): + report = json.loads((self.evidence / "osv-results.json").read_text()) + report["results"][0]["packages"][0]["vulnerabilities"] = [ + {"id": "GHSA-example"} + ] + (self.evidence / "osv-results.json").write_text(json.dumps(report)) + with self.assertRaisesRegex(ValueError, "vulnerabilities"): + self.publish() + write_evidence(self.evidence, self.plugin["head"]) + (self.evidence / "unexpected").touch() + with self.assertRaisesRegex(ValueError, "expected exactly"): + self.publish() + self.assertEqual(self.writes, []) if __name__ == "__main__": diff --git a/tests/maintenance/test_release_workflow.py b/tests/maintenance/test_release_workflow.py new file mode 100644 index 0000000..6497129 --- /dev/null +++ b/tests/maintenance/test_release_workflow.py @@ -0,0 +1,131 @@ +"""Keep publication bound to verified source and independent of live criteria.""" + +import os +from pathlib import Path +import subprocess +import tempfile +import unittest + +import yaml + +ROOT = Path(__file__).resolve().parents[2] + + +class ReleaseWorkflowTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.release = yaml.safe_load( + (ROOT / ".github/workflows/release.yml").read_text() + ) + cls.scan = yaml.safe_load( + (ROOT / ".github/workflows/dependency-scan.yml").read_text() + ) + + def dependencies(self, job): + needs = self.release["jobs"][job].get("needs", []) + return {needs} if isinstance(needs, str) else set(needs) + + def test_criteria_cannot_gate_publication(self): + pending = list(self.dependencies("publish")) + required = set() + while pending: + job = pending.pop() + if job not in required: + required.add(job) + pending.extend(self.dependencies(job)) + self.assertEqual({"validate", "checks", "scan"}, required) + self.assertNotIn("criteria", required) + self.assertTrue(self.release["jobs"]["criteria"]["continue-on-error"]) + + def test_only_approved_main_publication_can_write(self): + self.assertEqual({"contents": "read"}, self.release["permissions"]) + publish = self.release["jobs"]["publish"] + self.assertEqual("release", publish["environment"]) + for condition in ( + "github.event_name == 'push'", + "github.ref == 'refs/heads/main'", + "vars.RELEASE_REPOSITORY == github.repository", + ): + self.assertIn(condition, publish["if"]) + for name, job in self.release["jobs"].items(): + permissions = job.get("permissions", self.release["permissions"]) + self.assertEqual( + "write" if name == "publish" else "read", permissions["contents"] + ) + + def test_checks_scan_and_publisher_use_the_same_event_commit(self): + for workflow in (self.release, self.scan): + for job in workflow["jobs"].values(): + for step in job.get("steps", []): + if step.get("uses", "").startswith("actions/checkout@"): + self.assertEqual("${{ github.sha }}", step["with"]["ref"]) + self.assertFalse(step["with"]["persist-credentials"]) + events = self.scan.get("on", self.scan.get(True)) + self.assertNotIn("inputs", events["workflow_call"]) + self.assertEqual( + "${{ github.sha }}", self.scan["jobs"]["scan"]["env"]["SCAN_COMMIT"] + ) + publish_steps = self.release["jobs"]["publish"]["steps"] + download = next( + step + for step in publish_steps + if step.get("uses", "").startswith("actions/download-artifact@") + ) + self.assertEqual( + "${{ needs.scan.outputs.artifact-id }}", download["with"]["artifact-ids"] + ) + + def test_criteria_failures_report_warnings_without_failing(self): + steps = self.release["jobs"]["criteria"]["steps"] + report = next( + step for step in steps if step.get("name") == "Report advisory outcome" + ) + for download, comparison, warning in ( + ("success", "success", False), + ("failure", "skipped", True), + ("success", "failure", True), + ): + with ( + self.subTest(download=download, comparison=comparison), + tempfile.TemporaryDirectory() as temp, + ): + summary = Path(temp) / "summary.md" + result = subprocess.run( + [ + "bash", + "--noprofile", + "--norc", + "-eo", + "pipefail", + "-c", + report["run"], + ], + env={ + **os.environ, + "DOWNLOAD": download, + "COMPARISON": comparison, + "GITHUB_STEP_SUMMARY": str(summary), + }, + text=True, + capture_output=True, + check=False, + ) + self.assertEqual(0, result.returncode, result.stderr) + self.assertEqual(warning, "::warning::" in result.stdout) + self.assertIn("advisory", summary.read_text()) + + def test_local_release_checks_do_not_contact_live_criteria(self): + result = subprocess.run( + ["make", "--dry-run", "release-check"], + cwd=ROOT, + text=True, + capture_output=True, + check=True, + ) + self.assertIn("unittest", result.stdout) + self.assertNotIn("criteria_sync.py", result.stdout) + self.assertNotIn("download-criteria", result.stdout) + + +if __name__ == "__main__": + unittest.main() diff --git a/tools/finalize_release.py b/tools/finalize_release.py deleted file mode 100644 index 302c8f4..0000000 --- a/tools/finalize_release.py +++ /dev/null @@ -1,168 +0,0 @@ -"""Publish a reviewed draft from the successful preparation run printed in its summary.""" - -from __future__ import annotations - -import json -import os -from pathlib import Path -import re -import subprocess -import sys -import tempfile - -import plugin_release as release - - -def check_run(run: dict, tag: str) -> None: - expected = { - "path": ".github/workflows/release.yml", - "event": "workflow_dispatch", - "head_branch": "main", - "display_title": f"Prepare {tag}", - "conclusion": "success", - "status": "completed", - } - if any(run.get(key) != value for key, value in expected.items()): - raise ValueError( - "RUN must be the successful Prepare run on main for this exact tag" - ) - - -def load_receipt(repo: str, run_id: str, tag: str, directory: Path) -> dict: - result = release.api(f"repos/{repo}/actions/runs/{run_id}") - check_run(result, tag) - # A short ref named "main" could also identify a tag. Trust the workflow - # code only if the repository's main branch actually contains its SHA. - sha = result["head_sha"] - if not re.fullmatch(r"[a-f0-9]{40}", sha): - raise ValueError("invalid workflow commit") - comparison = release.api(f"repos/{repo}/compare/{sha}...main?per_page=1") - if comparison.get("status") not in {"identical", "ahead"}: - raise ValueError( - "preparation workflow commit is not on the repository's main branch" - ) - name = f"release-subject-{int(result['run_attempt'])}" - release.run( - "gh", - "run", - "download", - run_id, - "--repo", - repo, - "--name", - name, - "--dir", - str(directory), - ) - return json.loads((directory / "receipt.json").read_text()) - - -def check_receipt(receipt: dict, plugin: dict) -> None: - if any(receipt.get(field) != plugin[field] for field in ("tag", "head", "object")): - raise ValueError("prepared tag differs from the signed tag; do not publish") - if type(receipt.get("draft_id")) is not int or receipt["draft_id"] <= 0: - raise ValueError("missing draft ID in preparation receipt") - assets = receipt["assets"] - if set(assets) != set(release.ASSETS) or not all( - re.fullmatch(r"sha256:[a-f0-9]{64}", h) for h in assets.values() - ): - raise ValueError("preparation receipt missing release evidence digests") - - -def check_draft(record: dict, plugin: dict, receipt: dict) -> None: - expected = { - "id": receipt["draft_id"], - "tag_name": plugin["tag"], - "name": f"{plugin['name']} {plugin['version']}", - "prerelease": plugin["prerelease"], - } - if any(record.get(key) != value for key, value in expected.items()): - raise ValueError("release metadata differs from signed tag or draft receipt") - # GitHub may normalize line endings when storing the body. - notes = release.release_notes(plugin, plugin["head"]).strip() - if record["body"].replace("\r\n", "\n").strip() != notes: - raise ValueError("release notes differ from the file at the signed commit") - assets = { - a["name"]: a["digest"] for a in record["assets"] if a["state"] == "uploaded" - } - if len(record["assets"]) != len(release.ASSETS) or assets != receipt["assets"]: - raise ValueError( - "release assets differ from the successful scan; do not publish" - ) - - -def finalize(repo: str, tag: str, run_id: str) -> None: - if ( - not release.REPOSITORY.fullmatch(repo) - or ".." in repo - or not re.fullmatch(r"[1-9][0-9]*", run_id) - or not tag - ): - raise ValueError( - "copy REPO=owner/repo TAG=plugin--vVERSION RUN=id from the Prepare workflow summary" - ) - base = f"repos/{repo}" - if release.api(f"{base}/actions/variables/RELEASE_REPOSITORY")["value"] != repo: - raise ValueError("release preparation is not enabled for this repository") - with tempfile.TemporaryDirectory(prefix="release-receipt-") as temp: - root = Path(temp) - signers = root / "allowed_signers" - signers.write_text( - release.api(f"{base}/actions/variables/RELEASE_ALLOWED_SIGNERS")["value"] - + "\n" - ) - plugin = release.verify_tag(tag, signers) - receipt = load_receipt(repo, run_id, tag, root / "subject") - check_receipt(receipt, plugin) - endpoint = f"{base}/releases/{receipt['draft_id']}" - record = release.api(endpoint) - check_draft(record, plugin, receipt) - release.check_remote_ref(repo, plugin) - if record["draft"]: - if release.api(f"{base}/immutable-releases").get("enabled") is not True: - raise ValueError( - "enable release immutability in repository settings first; draft left unpublished" - ) - print( - f"Publishing verified draft {repo} {tag} ({plugin['head'][:12]})", - flush=True, - ) - release.api( - endpoint, - "--method", - "PATCH", - "-F", - "draft=false", - "-f", - "make_latest=false", - ) - published = release.api(endpoint) - if published.get("immutable") is not True or published["draft"]: - raise ValueError( - "GitHub did not confirm an immutable published release; inspect it before taking further action" - ) - check_draft(published, plugin, receipt) - release.check_remote_ref(repo, plugin) - release.run("gh", "release", "verify", tag, "--repo", repo) - print(f"Verified immutable release: {published['html_url']}") - - -def main() -> int: - try: - finalize(*(os.environ.get(key, "") for key in ("REPO", "TAG", "RUN"))) - return 0 - except ( - KeyError, - OSError, - ValueError, - TypeError, - subprocess.CalledProcessError, - ) as exc: - print(f"Release finalization stopped: {exc}", file=sys.stderr) - if isinstance(exc, subprocess.CalledProcessError) and exc.stderr: - print(exc.stderr.strip(), file=sys.stderr) - return 1 - - -if __name__ == "__main__": - sys.exit(main()) diff --git a/tools/plugin_release.py b/tools/plugin_release.py index 87705ad..5e804a4 100644 --- a/tools/plugin_release.py +++ b/tools/plugin_release.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Validate plugin versions and prepare drafts from maintainer-signed release tags.""" +"""Plan reviewed plugin versions and publish verified GitHub-native releases.""" from __future__ import annotations @@ -124,8 +124,13 @@ def plan(base: str = "HEAD^", head: str = "HEAD") -> dict: old = previous.get(name, {}).get("version") if old == plugin["version"]: _check_catalog_version(plugin, base_sha, head_sha) - continue - if old is not None and not _valid_transition(name, old, plugin["version"]): + if not _first_reviewed_notes(plugin, base_sha, head_sha): + continue + if ( + old is not None + and old != plugin["version"] + and not _valid_transition(name, old, plugin["version"], head_sha) + ): raise ValueError( f"{name}: changed version must increase in SemVer precedence" ) @@ -136,12 +141,18 @@ def plan(base: str = "HEAD^", head: str = "HEAD") -> dict: return {"base": base_sha, "head": head_sha, "plugins": changed} -def _valid_transition(name: str, previous: str, version: str) -> bool: +def _valid_transition(name: str, previous: str, version: str, head: str) -> bool: before, after = _precedence(previous), _precedence(version) if after >= before: return after > before # Build metadata alone cannot be a version bump. - return git("rev-parse", "--is-shallow-repository") == "false" and not git( - "tag", "--list", f"{name}--v*" + if git("rev-parse", "--is-shallow-repository") != "false": + return False + tags = git("tag", "--list", f"{name}--v*").splitlines() + # The first publication can reset an inherited version. Its exact lightweight + # tag preserves that decision on historical retries, even after later releases. + own_tag = f"{name}--v{version}" + return not tags or ( + own_tag in tags and git("rev-parse", f"refs/tags/{own_tag}") == head ) @@ -175,67 +186,14 @@ def release_notes(plugin: dict, head: str) -> str: return notes -def _require_decision_commit(plugin: dict, head: str) -> None: - parents = git("rev-list", "--parents", "-n", "1", head).split()[1:] - if not parents or not git("ls-tree", parents[0], "--", MARKETPLACE): - return - old = plugins_at(parents[0]).get(plugin["name"]) - if ( - old - and old["version"] == plugin["version"] - and git("ls-tree", parents[0], "--", _notes_path(plugin)) - ): - raise ValueError( - "tag must point to the version decision or first reviewed notes commit" - ) - - -def verify_tag(tag: str, allowed_signers: Path) -> dict: - """Read tagged data as Git objects. Never execute or check out the tagged tree.""" - match = re.fullmatch(r"([a-z0-9][a-z0-9-]*)--v([0-9]+\..+)", tag) - if not match: - raise ValueError("tag must be PLUGIN--vSEMVER") - name, version = match.groups() - _version(version) - if git("rev-parse", "--is-shallow-repository") != "false": - raise ValueError("verification requires full history and release tags") - ref = f"refs/tags/{tag}" - oid = git("rev-parse", "--verify", ref) - if git("cat-file", "-t", oid) != "tag": - raise ValueError("release requires a signed annotated tag") - headers = git("cat-file", "tag", oid).split("\n\n", 1)[0].splitlines() - if f"tag {tag}" not in headers or "type commit" not in headers: - raise ValueError( - "signed tag name or target type does not match its release ref" - ) - # verify-tag detects signature format from the object, irrespective of gpg.format. - # Disable the other verifiers: a trusted OpenPGP or X.509 key is not an SSH allowlist entry. - git( - "-c", - "gpg.openpgp.program=false", - "-c", - "gpg.x509.program=false", - "-c", - f"gpg.ssh.allowedSignersFile={allowed_signers.resolve(strict=True)}", - "verify-tag", - oid, - ) - head = resolve(oid) - if run( - "git", - "merge-base", - "--is-ancestor", - head, - "refs/remotes/origin/main", - check=False, - ).returncode: - raise ValueError("signed commit is not reachable from origin/main") - plugin = plugins_at(head).get(name) - if not plugin or plugin["version"] != version: - raise ValueError("tag does not match the registered plugin manifest") - release_notes(plugin, head) - _require_decision_commit(plugin, head) - return {**plugin, "tag": tag, "head": head, "object": oid} +def _first_reviewed_notes(plugin: dict, base: str, head: str) -> bool: + path = _notes_path(plugin) + if git("ls-tree", base, "--", path) or not git("ls-tree", head, "--", path): + return False + # A tag at this exact event commit is an idempotent publication retry. + tag = f"refs/tags/{plugin['name']}--v{plugin['version']}" + existing = run("git", "rev-parse", "--verify", tag, check=False) + return existing.returncode != 0 or existing.stdout.strip() == head def api(endpoint: str, *args: str, missing: bool = False) -> dict | None: @@ -271,19 +229,96 @@ def evidence_digests(directory: Path) -> dict[str, str]: return hashes -def check_remote_ref(repository: str, plugin: dict) -> None: - ref = api(f"repos/{repository}/git/ref/tags/{quote(plugin['tag'], safe='')}") - target = ref["object"] - if target.get("sha") != plugin["object"] or target.get("type") != "tag": - raise ValueError("remote signed tag object changed; stop and investigate") +def _validate_scan_package(item: Any) -> None: + if not isinstance(item, dict) or not isinstance(item.get("package"), dict): + raise ValueError("malformed OSV package") + package = item["package"] + coordinate = tuple(package.get(key) for key in ("ecosystem", "name", "version")) + if not all(isinstance(value, str) and value for value in coordinate): + raise ValueError("malformed OSV package coordinate") + if coordinate[0] not in {"npm", "PyPI"}: + raise ValueError("unexpected ecosystem in release evidence") + vulnerabilities = item.get("vulnerabilities", []) + if not isinstance(vulnerabilities, list) or vulnerabilities: + raise ValueError("invalid or nonempty vulnerabilities in release evidence") + + +def _validate_scan_results(report: dict) -> None: + results = report.get("results") + if not isinstance(results, list) or not results: + raise ValueError("missing completed OSV results") + for source in results: + packages = source.get("packages") if isinstance(source, dict) else None + if not isinstance(packages, list) or not packages: + raise ValueError("missing OSV package inventory") + for item in packages: + _validate_scan_package(item) + + +def validate_evidence(directory: Path, head: str) -> dict[str, str]: + hashes = evidence_digests(directory) + report = json.loads((directory / "osv-results.json").read_text()) + if not isinstance(report, dict): + raise ValueError("OSV report must be an object") + _validate_scan_results(report) + scope = (directory / "scan-scope.md").read_text() + # The successful scan job and same-run artifact identity establish completeness. + # These checks bind its evidence to the release without parsing editorial prose. + lines = [line.strip() for line in scope.splitlines()] + commits = [line for line in lines if line.startswith("Commit:")] + outcomes = [line for line in lines if line.startswith("PASS:")] + if ( + commits != [f"Commit: `{head}`"] + or outcomes != ["PASS: no known vulnerabilities found."] + or "BLOCKED" in scope + or "INCOMPLETE" in scope + ): + raise ValueError( + "scan scope must record one exact commit and a successful PASS outcome" + ) + return hashes + + +def check_checkout(base: str, head: str) -> None: + if not re.fullmatch(r"[a-f0-9]{40}", head) or head != resolve("HEAD"): + raise ValueError("publish requires the full event SHA equal to checkout HEAD") + if base != "empty" and re.fullmatch(r"[a-f0-9]{40}", base) is None: + raise ValueError("publish requires the full event base SHA or empty") + if git("rev-parse", "--is-shallow-repository") != "false": + raise ValueError("publication requires full history and tags") + for ancestor, descendant in ((head, "refs/remotes/origin/main"), (base, head)): + if ancestor == "empty": + continue + if run( + "git", "merge-base", "--is-ancestor", ancestor, descendant, check=False + ).returncode: + raise ValueError( + "release commit must be on origin/main and descend from the event base" + ) + + +def remote_ref(repository: str, plugin: dict) -> dict | None: + ref = api( + f"repos/{repository}/git/ref/tags/{quote(plugin['tag'], safe='')}", missing=True + ) + if ref is not None: + target = ref.get("object", {}) + if target.get("sha") != plugin["head"] or target.get("type") != "commit": + raise ValueError("remote release tag conflicts with the exact event commit") + return ref -def _require_new_release(repository: str, tag: str) -> None: - root = f"repos/{repository}/releases" - if api(f"{root}/tags/{quote(tag, safe='')}", missing=True) is not None: - raise ValueError(f"{tag}: release already exists; inspect it, never overwrite") - # GraphQL includes an unpublished draft for callers with push access. The REST - # by-tag endpoint alone is insufficient to distinguish it from a missing release. +def _existing_release(repository: str, tag: str) -> dict | None: + record = api( + f"repos/{repository}/releases/tags/{quote(tag, safe='')}", missing=True + ) + if record is not None: + if record.get("draft") is not False: + raise ValueError( + "existing draft; inspect and explicitly recover it before retrying" + ) + return record + # REST's by-tag endpoint can hide drafts. GraphQL includes drafts for push callers. owner, repo = repository.split("/") data = api( "graphql", @@ -297,19 +332,98 @@ def _require_new_release(repository: str, tag: str) -> None: f"t={tag}", ) if data["data"]["repository"]["release"] is not None: - raise ValueError(f"{tag}: existing draft; inspect it before retrying") + raise ValueError( + "existing draft; inspect and explicitly recover it before retrying" + ) + return None -def prepare_draft(repository: str, plugin: dict, directory: Path) -> dict: - if not REPOSITORY.fullmatch(repository) or ".." in repository: - raise ValueError("expected OWNER/REPO") - hashes = evidence_digests(directory) - check_remote_ref(repository, plugin) - root = f"repos/{repository}/releases" - tag = plugin["tag"] - _require_new_release(repository, tag) +def _asset_digests(record: dict) -> dict[str, str]: + assets = record.get("assets") + if not isinstance(assets, list) or len(assets) != len(ASSETS): + raise ValueError("release must contain exactly the expected evidence assets") + hashes = {} + for asset in assets: + if not isinstance(asset, dict) or asset.get("state") != "uploaded": + raise ValueError("release evidence asset is not uploaded") + name, digest = asset.get("name"), asset.get("digest") + if ( + name not in ASSETS + or name in hashes + or not isinstance(digest, str) + or not re.fullmatch(r"sha256:[a-f0-9]{64}", digest) + ): + raise ValueError("release evidence asset names or digests are invalid") + hashes[name] = digest + return hashes + + +def _check_release_subject(record: dict, plugin: dict) -> None: + expected = {"tag_name": plugin["tag"], "target_commitish": plugin["head"]} + if any(record.get(key) != value for key, value in expected.items()): + raise ValueError( + "release subject differs from the exact reviewed tag and commit" + ) + + +def check_release(record: dict, plugin: dict, hashes: dict[str, str]) -> None: + _check_release_subject(record, plugin) + expected = { + "name": f"{plugin['name']} {plugin['version']}", + "prerelease": plugin["prerelease"], + } + if any(record.get(key) != value for key, value in expected.items()): + raise ValueError("release metadata differs from the exact reviewed release") + notes = release_notes(plugin, plugin["head"]).replace("\r\n", "\n").strip() + body = record.get("body") + if not isinstance(body, str) or body.replace("\r\n", "\n").strip() != notes: + raise ValueError("release notes differ from the reviewed commit") + if _asset_digests(record) != hashes: + raise ValueError("release evidence digests differ; leave draft unpublished") + + +def verify_published( + repository: str, plugin: dict, record: dict, hashes: dict[str, str] | None = None +) -> None: + if record.get("immutable") is not True or record.get("draft") is not False: + raise ValueError( + "GitHub did not confirm an immutable published release; inspect repository immutability settings and this release" + ) + _check_release_subject(record, plugin) + if remote_ref(repository, plugin) is None: + raise ValueError("published release tag is missing") + if hashes is None: + # A rerun verifies the original assets, not a fresh scan's timestamped bytes. + hashes = _asset_digests(record) + with tempfile.TemporaryDirectory(prefix="release-evidence-") as temp: + run( + "gh", + "release", + "download", + plugin["tag"], + "--repo", + repository, + "--dir", + temp, + "--pattern", + ASSETS[0], + "--pattern", + ASSETS[1], + ) + if validate_evidence(Path(temp), plugin["head"]) != hashes: + raise ValueError( + "published evidence bytes do not match recorded digests" + ) + else: + # New publication still must match reviewed notes and all draft metadata. + check_release(record, plugin, hashes) + run("gh", "release", "verify", plugin["tag"], "--repo", repository) + print(f"Verified immutable release: {record['html_url']}") + + +def _create_draft(repository: str, plugin: dict) -> int: payload = { - "tag_name": tag, + "tag_name": plugin["tag"], "name": f"{plugin['name']} {plugin['version']}", "body": release_notes(plugin, plugin["head"]), "target_commitish": plugin["head"], @@ -321,7 +435,7 @@ def prepare_draft(repository: str, plugin: dict, directory: Path) -> dict: request = Path(temp) / "draft.json" request.write_text(json.dumps(payload)) created = api( - root, + f"repos/{repository}/releases", "--method", "POST", "-H", @@ -329,16 +443,23 @@ def prepare_draft(repository: str, plugin: dict, directory: Path) -> dict: "--input", str(request), ) - release_id = created["id"] + release_id = created.get("id") if ( - not created.get("draft") - or created.get("tag_name") != tag + created.get("draft") is not True + or created.get("tag_name") != plugin["tag"] or type(release_id) is not int + or release_id <= 0 ): - raise ValueError("unexpected GitHub draft response") + raise ValueError("unexpected GitHub draft response; inspect before retrying") + return release_id + + +def _upload_evidence( + repository: str, release_id: int, directory: Path, hashes: dict[str, str] +) -> None: for name in ASSETS: - endpoint = f"https://uploads.github.com/{root}/{release_id}/assets?name={name}" path = directory / name + endpoint = f"https://uploads.github.com/repos/{repository}/releases/{release_id}/assets?name={name}" asset = api( endpoint, "--method", @@ -354,23 +475,52 @@ def prepare_draft(repository: str, plugin: dict, directory: Path) -> dict: raise ValueError( f"uploaded evidence mismatch for {name}; leave draft unpublished" ) - check_remote_ref(repository, plugin) - print(f"Prepared draft {tag}. It has not been published.") - return { - **{key: plugin[key] for key in ("tag", "head", "object")}, - "draft_id": release_id, - "assets": hashes, - } -def check_preflight_identity( - plugin: dict, expected_object: str | None, expected_head: str | None +def _publish_new( + repository: str, plugin: dict, directory: Path, hashes: dict[str, str] ) -> None: - """Bind a freshly verified tag to the exact subject approved by preflight.""" - if expected_object is not None and plugin["object"] != expected_object: - raise ValueError("signed tag changed since preflight") - if expected_head is not None and plugin["head"] != expected_head: - raise ValueError("release commit changed since preflight") + if remote_ref(repository, plugin) is None: + api( + f"repos/{repository}/git/refs", + "--method", + "POST", + "-f", + f"ref=refs/tags/{plugin['tag']}", + "-f", + f"sha={plugin['head']}", + ) + if remote_ref(repository, plugin) is None: + raise ValueError("release tag creation was not confirmed") + release_id = _create_draft(repository, plugin) + _upload_evidence(repository, release_id, directory, hashes) + endpoint = f"repos/{repository}/releases/{release_id}" + record = api(endpoint) + if record.get("id") != release_id or record.get("draft") is not True: + raise ValueError("new draft identity changed; inspect before retrying") + check_release(record, plugin, hashes) + if remote_ref(repository, plugin) is None: + raise ValueError("release tag disappeared; leave draft unpublished") + api(endpoint, "--method", "PATCH", "-F", "draft=false", "-f", "make_latest=false") + verify_published(repository, plugin, api(endpoint), hashes) + + +def publish(base: str, head: str, repository: str, directory: Path) -> None: + if not REPOSITORY.fullmatch(repository) or ".." in repository: + raise ValueError("expected OWNER/REPO") + check_checkout(base, head) + selected = [{**plugin, "head": head} for plugin in plan(base, head)["plugins"]] + hashes = validate_evidence(directory, head) + pending = [] + for plugin in selected: + remote_ref(repository, plugin) + existing = _existing_release(repository, plugin["tag"]) + if existing is not None: + verify_published(repository, plugin, existing) + else: + pending.append(plugin) + for plugin in pending: + _publish_new(repository, plugin, directory, hashes) def main(argv: list[str] | None = None) -> int: @@ -380,39 +530,20 @@ def main(argv: list[str] | None = None) -> int: prepare.add_argument("--base", default="HEAD^") prepare.add_argument("--head", default="HEAD") prepare.add_argument("--output", type=Path, required=True) - tag_parser = argparse.ArgumentParser(add_help=False) - tag_parser.add_argument("--tag", required=True) - tag_parser.add_argument("--allowed-signers", type=Path, required=True) - verify = commands.add_parser("verify-tag", parents=[tag_parser]) - verify.add_argument("--expected-object") - verify.add_argument("--expected-head") - draft = commands.add_parser("draft", parents=[tag_parser]) - draft.add_argument("--receipt", type=Path, required=True) - draft.add_argument("--object", required=True) - draft.add_argument("--repository", required=True) - draft.add_argument("--evidence", type=Path, required=True) + publication = commands.add_parser("publish") + publication.add_argument("--base", required=True) + publication.add_argument("--head", required=True) + publication.add_argument("--repository", required=True) + publication.add_argument("--evidence", type=Path, required=True) args = parser.parse_args(argv) try: if args.command == "plan": result = plan(args.base, args.head) args.output.parent.mkdir(parents=True, exist_ok=True) args.output.write_text(json.dumps(result, indent=2) + "\n") - print( - f"Planned {len(result['plugins'])} plugin version change(s): {args.output}" - ) + print(f"Planned {len(result['plugins'])} plugin release(s): {args.output}") else: - plugin = verify_tag(args.tag, args.allowed_signers) - if args.command == "draft": - if args.object != plugin["object"]: - raise ValueError("signed tag changed since preflight") - receipt = prepare_draft(args.repository, plugin, args.evidence) - args.receipt.write_text(json.dumps(receipt) + "\n") - else: - check_preflight_identity(plugin, args.expected_object, args.expected_head) - print( - f"head={plugin['head']}\nobject={plugin['object']}\nplugin={plugin['name']}" - ) - print(f"prerelease={str(plugin['prerelease']).lower()}") + publish(args.base, args.head, args.repository, args.evidence) return 0 except ( OSError, From 31fb8b621bda8b7148feab1a847f08202e8399ae Mon Sep 17 00:00:00 2001 From: Really Him Date: Fri, 13 Nov 2026 10:49:11 -0500 Subject: [PATCH 3/4] docs: explain release authorization and tag protection --- docs/releases.md | 12 ++++++++++++ docs/repo-setup.md | 4 +++- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/releases.md b/docs/releases.md index 1520801..e8902bb 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -23,6 +23,18 @@ Badge Buddy's live criteria comparison is separate, advisory maintenance. Websit After approval, the workflow creates each lightweight tag, such as `release-buddy--v0.1.0`, at the same checked commit, attaches the evidence, publishes the immutable GitHub Release, and verifies its release attestation and assets. This process uses GitHub's environment approval and release attestation; it does not require a personal SSH signing key, a manually pushed tag, a workflow dispatch, or local finalization. Repository writers are trusted: they can also publish directly, so the environment approval governs this workflow rather than every route to publication. Follow [consumer verification](../VERIFYING.md) from a separate checkout after the first release. +## What authorizes and protects a release + +| Control | Responsibility | +| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Checks at the event commit | Tests and dependency scanning evaluate the exact commit that will be tagged, even if `main` advances before approval. | +| Owner approval in the `release` environment | Authorizes this workflow to publish that checked commit. Repository writers remain trusted to publish directly through GitHub. | +| Immutable GitHub release | Locks the published release's associated tag and attached assets while the release exists. It does not validate the code or protect an unpublished tag. | + +We intentionally do not maintain separate tag-creation or tag-preservation rulesets. Before publication, ordinary writer permissions allow an unused tag to be corrected or deleted. After immutable publication, GitHub supplies the tag and asset protection. The old owner-only creation rule prevented the workflow token from creating tags and added an unnecessary credential or local handoff to this trusted-writer model. See [repository setup](repo-setup.md#prepare-the-release-repository) for the settings that implement this policy. + +Commit signing is independent of release publication. Use your normal Git commit-signing configuration; this repository no longer needs a special SSH signing key. Existing signed tags retain their [historical verification procedure](../VERIFYING.md#historical-ssh-signed-tags). + ## If a run stops For a transient failure, rerun the original workflow run. Its commit remains the original `github.sha` even if `main` has advanced. A dependency fix belongs in a PR; review the resulting new run before approving publication. To investigate a scan locally, use the OSV-Scanner version pinned in [the scan helper](../tools/scan_dependencies.py) and run `make dependency-scan`; evidence is written to `.cache/dependency-scan/`. Local dependency resolution may differ from Linux CI. diff --git a/docs/repo-setup.md b/docs/repo-setup.md index d9daf9c..ed756ed 100644 --- a/docs/repo-setup.md +++ b/docs/repo-setup.md @@ -48,6 +48,8 @@ Reopen the settings to confirm they were saved, and inspect a pull request to co 5. Confirm Actions policy permits job-level `contents: write` for publication and read-only access for planning, checks, and scans. Keep `main` and the `release` environment protected: the reviewed workflow, successful checks, and owner approval govern publication through this workflow. Repository writers can also publish releases directly; the environment is not a repository-wide release-access restriction. No additional secret token or signing bot is needed. 6. Follow the [release guide](releases.md) with a deliberately selected plugin version. Setup remains incomplete until a run confirms that tag creation is permitted, publication waits for owner approval, and the release attestation identifies the checked commit. After publication, use [consumer verification](../VERIFYING.md) from a separate checkout. -The live `release` environment is configured for `main` only, with `hesreallyhim` as required reviewer, administrator bypass disabled, and self-approval allowed because the owner initiates releases. Release immutability is enabled. The release policy uses ordinary writer permissions without custom release-tag rulesets. +As verified on November 13, 2026, the live `release` environment is configured for `main` only, with `hesreallyhim` as required reviewer, administrator bypass disabled, and self-approval allowed because the owner initiates releases. Release immutability is enabled. The `release-tag-creation` and `release-tag-preservation` rulesets were removed; the `protect-main` ruleset remains active. This records the configured state, not completion of the first publication run. + +An existing local checkout may still have `gpg.format` and `user.signingkey` overrides from the former SSH-tag process. Inspect their origins with `git config --show-origin --get-regexp '^(gpg\.format|user\.signingkey)$'`. If those repository-local overrides were installed only for the old release process, remove them with `git config --local --unset-all gpg.format` and `git config --local --unset-all user.signingkey` to inherit your usual Git configuration. Preserve intentional personal settings; release automation does not require changing global configuration or disabling commit signing. Historical SSH-signed tags remain verifiable using the [historical signer instructions](../VERIFYING.md#historical-ssh-signed-tags). Their signer allowlist is not an input to the current publication workflow. From fcbd0e8fb4c4fd90f3cb3a731f23d89d0ecf4a52 Mon Sep 17 00:00:00 2001 From: Really Him Date: Fri, 13 Nov 2026 10:51:26 -0500 Subject: [PATCH 4/4] docs: archive one-time repository setup checklist Signed-off-by: Really Him --- docs/{ => archive}/repo-setup.md | 8 +++++--- docs/releases.md | 12 ++++++++---- 2 files changed, 13 insertions(+), 7 deletions(-) rename docs/{ => archive}/repo-setup.md (89%) diff --git a/docs/repo-setup.md b/docs/archive/repo-setup.md similarity index 89% rename from docs/repo-setup.md rename to docs/archive/repo-setup.md index ed756ed..449ca16 100644 --- a/docs/repo-setup.md +++ b/docs/archive/repo-setup.md @@ -1,4 +1,6 @@ -# Repository setup +# Repository setup (archived) + +Archived November 13, 2026. This is a historical record of the one-time repository setup and release migration, not an active checklist. Its settings and UI instructions may become outdated. Use the current [release guide](../releases.md) for ongoing operation and required configuration. The first complete publication run was still pending when this document was archived. Configure branch protection and pull-request merging in GitHub's UI when preparing a development or public plugin repository. These settings describe the project's intended baseline; compare them with any existing repository or organization rules before editing those rules. @@ -46,10 +48,10 @@ Reopen the settings to confirm they were saved, and inspect a pull request to co 3. In **Settings → General → Releases**, enable [release immutability](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/prevent-release-changes), or confirm an organization policy enables it for this repository. This is a one-time prerequisite that must remain enabled; it applies only to future releases. The workflow's `GITHUB_TOKEN` cannot read the administration setting. It verifies the attestation after publishing, but that check cannot prevent an already-published mutable release if an administrator disables immutability. 4. No custom release-tag creation or preservation rulesets are required. Repository writers are trusted to manage tags and releases, including correcting or deleting tags that are not attached to a published immutable release. Once an immutable release is published, GitHub locks its associated tag and assets while that release exists. This protection does not apply retroactively to older releases or to unpublished tags. 5. Confirm Actions policy permits job-level `contents: write` for publication and read-only access for planning, checks, and scans. Keep `main` and the `release` environment protected: the reviewed workflow, successful checks, and owner approval govern publication through this workflow. Repository writers can also publish releases directly; the environment is not a repository-wide release-access restriction. No additional secret token or signing bot is needed. -6. Follow the [release guide](releases.md) with a deliberately selected plugin version. Setup remains incomplete until a run confirms that tag creation is permitted, publication waits for owner approval, and the release attestation identifies the checked commit. After publication, use [consumer verification](../VERIFYING.md) from a separate checkout. +6. Follow the [release guide](../releases.md) with a deliberately selected plugin version. Setup remains incomplete until a run confirms that tag creation is permitted, publication waits for owner approval, and the release attestation identifies the checked commit. After publication, use [consumer verification](../../VERIFYING.md) from a separate checkout. As verified on November 13, 2026, the live `release` environment is configured for `main` only, with `hesreallyhim` as required reviewer, administrator bypass disabled, and self-approval allowed because the owner initiates releases. Release immutability is enabled. The `release-tag-creation` and `release-tag-preservation` rulesets were removed; the `protect-main` ruleset remains active. This records the configured state, not completion of the first publication run. An existing local checkout may still have `gpg.format` and `user.signingkey` overrides from the former SSH-tag process. Inspect their origins with `git config --show-origin --get-regexp '^(gpg\.format|user\.signingkey)$'`. If those repository-local overrides were installed only for the old release process, remove them with `git config --local --unset-all gpg.format` and `git config --local --unset-all user.signingkey` to inherit your usual Git configuration. Preserve intentional personal settings; release automation does not require changing global configuration or disabling commit signing. -Historical SSH-signed tags remain verifiable using the [historical signer instructions](../VERIFYING.md#historical-ssh-signed-tags). Their signer allowlist is not an input to the current publication workflow. +Historical SSH-signed tags remain verifiable using the [historical signer instructions](../../VERIFYING.md#historical-ssh-signed-tags). Their signer allowlist is not an input to the current publication workflow. diff --git a/docs/releases.md b/docs/releases.md index e8902bb..acb7ba0 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -1,6 +1,6 @@ # Release a plugin -**Merge a version and its notes, review the checks, then approve publication in GitHub.** Each plugin releases independently; the marketplace has no version. Complete the one-time [repository setup](repo-setup.md#prepare-the-release-repository) first. +**Merge a version and its notes, review the checks, then approve publication in GitHub.** Each plugin releases independently; the marketplace has no version. ## 1. Choose the version in a PR @@ -31,10 +31,16 @@ After approval, the workflow creates each lightweight tag, such as `release-budd | Owner approval in the `release` environment | Authorizes this workflow to publish that checked commit. Repository writers remain trusted to publish directly through GitHub. | | Immutable GitHub release | Locks the published release's associated tag and attached assets while the release exists. It does not validate the code or protect an unpublished tag. | -We intentionally do not maintain separate tag-creation or tag-preservation rulesets. Before publication, ordinary writer permissions allow an unused tag to be corrected or deleted. After immutable publication, GitHub supplies the tag and asset protection. The old owner-only creation rule prevented the workflow token from creating tags and added an unnecessary credential or local handoff to this trusted-writer model. See [repository setup](repo-setup.md#prepare-the-release-repository) for the settings that implement this policy. +We intentionally do not maintain separate tag-creation or tag-preservation rulesets. Before publication, ordinary writer permissions allow an unused tag to be corrected or deleted. After immutable publication, GitHub supplies the tag and asset protection. The old owner-only creation rule prevented the workflow token from creating tags and added an unnecessary credential or local handoff to this trusted-writer model. Commit signing is independent of release publication. Use your normal Git commit-signing configuration; this repository no longer needs a special SSH signing key. Existing signed tags retain their [historical verification procedure](../VERIFYING.md#historical-ssh-signed-tags). +## Configuration to retain + +Keep `main` protected and the `release` environment limited to `main`, with owner approval required and administrator bypass disabled. Self-approval is allowed so the owner can approve their own release run. The repository variable `RELEASE_REPOSITORY` must match `reponomics/plugins`; publication uses the workflow's `GITHUB_TOKEN` with job-level `contents: write` permission. + +Release immutability must remain enabled in repository or organization settings. The workflow's token cannot read that administration setting; verification after publication detects a missing immutable attestation but cannot undo a mutable release that has already been published. + ## If a run stops For a transient failure, rerun the original workflow run. Its commit remains the original `github.sha` even if `main` has advanced. A dependency fix belongs in a PR; review the resulting new run before approving publication. To investigate a scan locally, use the OSV-Scanner version pinned in [the scan helper](../tools/scan_dependencies.py) and run `make dependency-scan`; evidence is written to `.cache/dependency-scan/`. Local dependency resolution may differ from Linux CI. @@ -42,5 +48,3 @@ For a transient failure, rerun the original workflow run. Its commit remains the A retry verifies the original tag, commit, immutable attestation, and attached evidence of an already published release without rewriting it. Later edits to its displayed title, notes, or prerelease label do not invalidate that retry; the reviewed source notes remain in Git. New publication strictly checks the title, notes, prerelease status, and evidence before publishing. If a partial draft exists, keep it unpublished and inspect its tag, ownership, files, and digests. Retain its evidence before deliberately removing only that unpublished draft and retrying the original run. Tags without a published immutable release may be corrected or deleted after inspecting the intended commit and retaining relevant evidence; do not overwrite unknown draft assets. Publishing an immutable release locks its associated tag and assets while that release exists. Correct a bad published release with a new version. - -Release immutability must remain enabled in repository or organization settings. The workflow's token cannot read that administration setting; verification after publication detects a missing immutable attestation but cannot undo a mutable release that has already been published. See the [setup prerequisite](repo-setup.md#prepare-the-release-repository).