From d624684581b9562e659856944c663f22937a0776 Mon Sep 17 00:00:00 2001 From: jiandong Date: Tue, 28 Jul 2026 13:59:41 +0800 Subject: [PATCH 1/8] fix(release): use resolvable setup-go revision --- .github/workflows/release-build.yml | 2 +- test/suites/product/endpoint/release-workflow-contract.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release-build.yml b/.github/workflows/release-build.yml index 87c934c2..6ae3e55e 100644 --- a/.github/workflows/release-build.yml +++ b/.github/workflows/release-build.yml @@ -41,7 +41,7 @@ jobs: steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - uses: actions/setup-go@b7ad1dad31e06c5925f5d2fc7ad053ef454303e # v7.0.0 + - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 with: go-version-file: go.mod cache: true diff --git a/test/suites/product/endpoint/release-workflow-contract.sh b/test/suites/product/endpoint/release-workflow-contract.sh index 4d739b7e..153598c0 100755 --- a/test/suites/product/endpoint/release-workflow-contract.sh +++ b/test/suites/product/endpoint/release-workflow-contract.sh @@ -43,7 +43,7 @@ grep -Fq 'openssl genrsa' "$build" grep -Fq 'openssl genpkey -algorithm ED25519' "$build" grep -Fq 'sha256sum -c SHA256SUMS' "$build" grep -Fq 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1' "$build" -grep -Fq 'actions/setup-go@b7ad1dad31e06c5925f5d2fc7ad053ef454303e # v7.0.0' "$build" +grep -Fq 'actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0' "$build" grep -Fq 'actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1' "$build" grep -Fq 'actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1' "$build" From efcc6869b3d17eddb1b0d088f8f4efa2ff362144 Mon Sep 17 00:00:00 2001 From: jiandong Date: Tue, 28 Jul 2026 15:27:29 +0800 Subject: [PATCH 2/8] docs(release): design installation notes rendering --- .../2026-07-28-release-installation-notes.md | 102 ++++++++++++++++++ ...07-28-release-installation-notes-design.md | 40 +++++++ 2 files changed, 142 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-28-release-installation-notes.md create mode 100644 docs/superpowers/specs/2026-07-28-release-installation-notes-design.md diff --git a/docs/superpowers/plans/2026-07-28-release-installation-notes.md b/docs/superpowers/plans/2026-07-28-release-installation-notes.md new file mode 100644 index 00000000..c20b2cac --- /dev/null +++ b/docs/superpowers/plans/2026-07-28-release-installation-notes.md @@ -0,0 +1,102 @@ +# Release Installation Notes Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 让 RC 与 GA 自动生成包含安装、容器和 provenance 说明的 GitHub Release notes。 + +**Architecture:** 一个纯 Bash 渲染器负责内容与输入校验，两个发布入口只负责调用并传给 `gh release create --notes-file`。Shell 契约直接验证渲染输出，workflow 契约验证接线。 + +**Tech Stack:** Bash、GitHub Actions、GitHub CLI。 + +## Global Constraints + +- 不改变 release 制品、签名、安装或 provenance 构建逻辑。 +- RC 与 GA 使用同一个 notes 渲染器。 +- 不再使用 `--generate-notes`。 +- 版本、仓库和发布类型必须严格校验。 + +--- + +### Task 1: Release Notes Renderer + +**Files:** +- Create: `deployments/packages/render-github-release-notes.sh` +- Create: `test/suites/product/endpoint/release-notes.sh` +- Modify: `test/Makefile:131-140` + +**Interfaces:** +- Consumes: `render-github-release-notes.sh VERSION REPOSITORY rc|ga`。 +- Produces: 标准输出 Markdown；非法输入退出 2。 + +- [ ] **Step 1: 写失败测试** + + 测试 `v0.1.0-rc.2 PKU-ASAL/sysarmor rc` 和 `v0.1.0 PKU-ASAL/sysarmor ga`，要求输出包含 + `install.sh`、`--profile linux-container`、`gh attestation verify` 和 changelog URL；错误版本、 + 仓库或类型必须失败。 + +- [ ] **Step 2: 确认 RED** + + Run: `bash test/suites/product/endpoint/release-notes.sh` + + Expected: FAIL，缺少 `deployments/packages/render-github-release-notes.sh`。 + +- [ ] **Step 3: 实现最小渲染器** + + 使用 Bash 正则分别校验 RC/GA 版本，仓库匹配 `owner/name` 安全字符；通过单个 heredoc 输出 + 完整 Markdown，不执行用户输入。 + +- [ ] **Step 4: 确认 GREEN** + + Run: `bash test/suites/product/endpoint/release-notes.sh` + + Expected: `[release-notes] ok`。 + +### Task 2: Workflow Integration + +**Files:** +- Modify: `.github/workflows/release-candidate.yml:81-94` +- Modify: `.github/workflows/release-stable.yml:100-112` +- Modify: `test/suites/product/endpoint/release-workflow-contract.sh` + +**Interfaces:** +- Consumes: Task 1 渲染器标准输出。 +- Produces: `$RUNNER_TEMP/release-notes.md` 和 `gh release create --notes-file`。 + +- [ ] **Step 1: 扩展 workflow 契约并确认 RED** + + 要求 RC/GA 都包含 `render-github-release-notes.sh`、`--notes-file`，并拒绝任一文件出现 + `--generate-notes`。运行契约，预期因旧接线失败。 + +- [ ] **Step 2: 接入两个工作流** + + 在 release job checkout 精确 `SOURCE_SHA`，调用： + + ```bash + deployments/packages/render-github-release-notes.sh \ + "$VERSION" "$GITHUB_REPOSITORY" rc >"$RUNNER_TEMP/release-notes.md" + ``` + + GA 使用 `ga`，`gh release create` 使用 + `--notes-file "$RUNNER_TEMP/release-notes.md"`。 + +- [ ] **Step 3: 验证 GREEN 和语法** + + ```bash + bash test/suites/product/endpoint/release-notes.sh + bash test/suites/product/endpoint/release-workflow-contract.sh + go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.7 .github/workflows/release-candidate.yml .github/workflows/release-stable.yml + git diff --check + ``` + + Expected: 全部 exit 0。 + +- [ ] **Step 4: 提交并发布 rc.2** + + ```bash + git add deployments/packages/render-github-release-notes.sh test/suites/product/endpoint/release-notes.sh test/suites/product/endpoint/release-workflow-contract.sh test/Makefile .github/workflows/release-candidate.yml .github/workflows/release-stable.yml + git commit -m "fix(release): restore installation notes" + git push github release/v0.1.0 + gh workflow run release-candidate.yml --ref release/v0.1.0 -f rc_number=2 + ``` + + Expected: `v0.1.0-rc.2` 为 Pre-release，描述包含三类用户说明并指向新提交。 diff --git a/docs/superpowers/specs/2026-07-28-release-installation-notes-design.md b/docs/superpowers/specs/2026-07-28-release-installation-notes-design.md new file mode 100644 index 00000000..bc2b0126 --- /dev/null +++ b/docs/superpowers/specs/2026-07-28-release-installation-notes-design.md @@ -0,0 +1,40 @@ +# Release 安装说明设计 + +## 结论 + +新增一个共享 Bash 渲染器生成 GitHub Release notes，RC 与 GA 工作流都通过 +`--notes-file` 使用它。GitHub 自动 changelog 由渲染器输出链接替代，避免 +`--generate-notes` 覆盖面向用户的安装说明。 + +## 背景 + +旧 `dev-prerelease.yml` 在工作流内生成在线安装、容器安装和 provenance 验证说明。迁移到 +`release-candidate.yml` 与 `release-stable.yml` 时改用了 `--generate-notes`，导致 +`v0.1.0-rc.1` 只有变更列表，没有安装入口。 + +## 方案 + +`deployments/packages/render-github-release-notes.sh` 接收三个位置参数：版本、仓库和发布类型 +`rc|ga`，向标准输出生成 Markdown。内容固定包含： + +- 精确版本和源码提交； +- 在线安装命令； +- `linux-container` Dockerfile 示例和运行约束； +- `gh attestation verify` 命令； +- 指向当前 tag 的 GitHub changelog 链接。 + +脚本严格校验版本、仓库和发布类型，不接受任意模板或 shell 片段。RC/GA 发布 job 将输出 +写入 `$RUNNER_TEMP/release-notes.md`，并使用 `gh release create --notes-file`。不再使用 +`--generate-notes`。 + +## 测试 + +- 独立脚本契约验证 RC、GA 输出及非法参数失败。 +- workflow 契约要求两个入口调用共享渲染器、使用 `--notes-file` 且不使用 + `--generate-notes`。 +- 继续运行 `actionlint` 与现有 release workflow contract。 + +## 发布影响 + +该改动会改变 Git tree，因此在 `release/v0.1.0` 提交后发布 `v0.1.0-rc.2`。它不改变 +Agent 二进制、签名格式或安装器，但 GA 仍以 rc.2 的相同 Git tree 为准。 From 8570b97252aa47e2919b68c41588bdd62e7efc13 Mon Sep 17 00:00:00 2001 From: jiandong Date: Tue, 28 Jul 2026 15:45:19 +0800 Subject: [PATCH 3/8] docs(release): expand pre-release audit design --- ...07-28-release-installation-notes-design.md | 52 ++++++++++++++++--- 1 file changed, 44 insertions(+), 8 deletions(-) diff --git a/docs/superpowers/specs/2026-07-28-release-installation-notes-design.md b/docs/superpowers/specs/2026-07-28-release-installation-notes-design.md index bc2b0126..a652d61a 100644 --- a/docs/superpowers/specs/2026-07-28-release-installation-notes-design.md +++ b/docs/superpowers/specs/2026-07-28-release-installation-notes-design.md @@ -1,16 +1,25 @@ -# Release 安装说明设计 +# 发布前文档与 Release 说明设计 ## 结论 -新增一个共享 Bash 渲染器生成 GitHub Release notes，RC 与 GA 工作流都通过 -`--notes-file` 使用它。GitHub 自动 changelog 由渲染器输出链接替代，避免 -`--generate-notes` 覆盖面向用户的安装说明。 +精准修复发布相关的用户入口、维护者文档和 GitHub Release notes，不机械更新历史记录或 +测试 fixture。新增一个共享 Bash 渲染器，RC 与 GA 工作流都通过 `--notes-file` 使用它； +同时补齐公开仓库必要的安全报告与贡献入口。 ## 背景 旧 `dev-prerelease.yml` 在工作流内生成在线安装、容器安装和 provenance 验证说明。迁移到 `release-candidate.yml` 与 `release-stable.yml` 时改用了 `--generate-notes`，导致 -`v0.1.0-rc.1` 只有变更列表，没有安装入口。 +`v0.1.0-rc.1` 初始发布时只有变更列表，没有安装入口；该页面已经手工修复，但工作流仍会复现 +同一问题。 + +全仓审计还发现以下发布前缺口： + +- 中英文 README 和部署指南仍将 GitHub 发行包描述为从 `dev` 构建的开发预发布； +- 部署指南使用了会快速过期的固定 dev tag； +- 开发指南没有完整说明 Release notes、默认分支工作流和正式发布前置配置； +- 公开仓库缺少 `SECURITY.md`、`CONTRIBUTING.md`，GitHub 仓库简介为空； +- `production-release` Environment 尚未配置，因此 GA 当前仍应被阻止。 ## 方案 @@ -27,14 +36,41 @@ 写入 `$RUNNER_TEMP/release-notes.md`，并使用 `gh release create --notes-file`。不再使用 `--generate-notes`。 +### 文档入口 + +- `README.md` 与 `README.zh-CN.md` 保持现有简洁产品语气，只将安装入口改成同时适用于 RC + 和正式版本的表述，不把完整发布流程搬到首页。 +- `docs/operations/deployment.md` 使用 `` 作为稳定示例，说明公开发行包、主机 profile、 + 容器 profile、来源验证和离线分发边界，不绑定某个短期版本。 +- `docs/development/development.md` 按 release 分支、RC、公开验收、合入 `main`、GA 的顺序 + 说明维护者操作，并明确受保护 Environment、审批人与签名 secret 是 GA 前置条件。 +- 历史验收报告、已提交的设计记录和用于版本解析的测试 fixture 保持原样，以保留证据真实性和 + 测试覆盖意图。 + +### 仓库治理 + +- `SECURITY.md` 说明受支持版本范围和私密漏洞报告入口，不要求用户在公开 Issue 披露漏洞。 +- `CONTRIBUTING.md` 复用现有开发、测试文档，简要说明从 `dev` 拉分支、通过 PR 回到 `dev` + 以及提交和验证要求，避免复制长篇开发手册。 +- GitHub 仓库简介使用一句准确英文描述，不设置尚不存在的产品主页。 +- 不新增 `CHANGELOG.md`；GitHub Releases 继续作为发行变更的唯一事实源。 + ## 测试 - 独立脚本契约验证 RC、GA 输出及非法参数失败。 - workflow 契约要求两个入口调用共享渲染器、使用 `--notes-file` 且不使用 `--generate-notes`。 -- 继续运行 `actionlint` 与现有 release workflow contract。 +- 检查 README 与主要文档链接，运行 `actionlint`、现有 release workflow contract、相关 + Product 测试和 `git diff --check`。 + +## 文风与边界 + +新增内容沿用相邻文档的语言和结构：先说明用户要完成的动作，再说明约束与原因；英文保持简洁， +中文保持技术说明口吻。避免模板化口号、重复定义和生硬直译。每项修改必须对应本次发布入口、 +发布操作或公开仓库治理，不扩展到无关架构文档。 ## 发布影响 -该改动会改变 Git tree，因此在 `release/v0.1.0` 提交后发布 `v0.1.0-rc.2`。它不改变 -Agent 二进制、签名格式或安装器，但 GA 仍以 rc.2 的相同 Git tree 为准。 +这些改动会改变 Git tree，因此在 `release/v0.1.0` 提交后发布 `v0.1.0-rc.2`。它们不改变 +Agent 二进制、签名格式或安装器，但 GA 仍以 rc.2 的相同 Git tree 为准。RC2 按既定门禁完成 +fresh medium 与 Ubuntu 22.04、Ubuntu 24.04、Debian 12 三镜像公开验收后，才可作为 GA 基线。 From 6eef0dca8e4a35fd4f1ac01deb7e35466dec6809 Mon Sep 17 00:00:00 2001 From: jiandong Date: Tue, 28 Jul 2026 15:49:16 +0800 Subject: [PATCH 4/8] docs(release): expand pre-release implementation plan --- .../2026-07-28-release-installation-notes.md | 202 ++++++++++++++---- 1 file changed, 156 insertions(+), 46 deletions(-) diff --git a/docs/superpowers/plans/2026-07-28-release-installation-notes.md b/docs/superpowers/plans/2026-07-28-release-installation-notes.md index c20b2cac..7f2cea20 100644 --- a/docs/superpowers/plans/2026-07-28-release-installation-notes.md +++ b/docs/superpowers/plans/2026-07-28-release-installation-notes.md @@ -1,102 +1,212 @@ -# Release Installation Notes Implementation Plan +# Pre-release Documentation And Notes Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. -**Goal:** 让 RC 与 GA 自动生成包含安装、容器和 provenance 说明的 GitHub Release notes。 +**Goal:** 让 RC 与 GA 自动提供完整安装说明，并使发布相关文档和公开仓库入口与当前流程一致。 -**Architecture:** 一个纯 Bash 渲染器负责内容与输入校验，两个发布入口只负责调用并传给 `gh release create --notes-file`。Shell 契约直接验证渲染输出，workflow 契约验证接线。 +**Architecture:** 一个纯 Bash 渲染器集中生成 Release notes，RC 与 GA 工作流只负责精确检出源码、调用渲染器和创建 Release。README、部署指南、开发指南各自只描述其受众需要的信息；治理文件链接到现有事实源，不复制长篇规则。 -**Tech Stack:** Bash、GitHub Actions、GitHub CLI。 +**Tech Stack:** Bash、GitHub Actions、GitHub CLI、Markdown。 ## Global Constraints -- 不改变 release 制品、签名、安装或 provenance 构建逻辑。 -- RC 与 GA 使用同一个 notes 渲染器。 -- 不再使用 `--generate-notes`。 -- 版本、仓库和发布类型必须严格校验。 +- 不改变 release 制品、签名、安装器或 provenance 构建逻辑。 +- RC 与 GA 使用同一个 notes 渲染器，且不再使用 `--generate-notes`。 +- 版本、仓库和发布类型必须严格校验，错误退出码为 2。 +- 英文保持简洁产品语气，中文保持仓库现有技术说明风格。 +- 不修改历史验收报告、设计历史和版本解析 fixture，不新增 `CHANGELOG.md`。 +- `v0.1.0-rc.2` 必须完成 fresh medium 与三镜像公开验收后才可作为 GA 基线。 --- -### Task 1: Release Notes Renderer +### Task 1: Release Notes Renderer And Workflow Integration **Files:** - Create: `deployments/packages/render-github-release-notes.sh` - Create: `test/suites/product/endpoint/release-notes.sh` -- Modify: `test/Makefile:131-140` +- Modify: `test/Makefile` +- Modify: `test/suites/product/endpoint/release-workflow-contract.sh` +- Modify: `.github/workflows/release-candidate.yml` +- Modify: `.github/workflows/release-stable.yml` **Interfaces:** - Consumes: `render-github-release-notes.sh VERSION REPOSITORY rc|ga`。 -- Produces: 标准输出 Markdown；非法输入退出 2。 +- Produces: 标准输出 Markdown；非法输入或参数数量错误时退出 2。 + +- [ ] **Step 1: 写 renderer 失败契约** -- [ ] **Step 1: 写失败测试** + 创建 Shell 测试，分别执行： + + ```bash + deployments/packages/render-github-release-notes.sh v0.1.0-rc.2 PKU-ASAL/sysarmor rc + deployments/packages/render-github-release-notes.sh v0.1.0 PKU-ASAL/sysarmor ga + ``` - 测试 `v0.1.0-rc.2 PKU-ASAL/sysarmor rc` 和 `v0.1.0 PKU-ASAL/sysarmor ga`，要求输出包含 - `install.sh`、`--profile linux-container`、`gh attestation verify` 和 changelog URL；错误版本、 - 仓库或类型必须失败。 + 断言输出包含精确版本、`install.sh`、`--profile linux-container`、容器运行约束、 + `gh attestation verify` 和 `/commits/` 变更列表 URL；`v0.1`、`owner only`、`beta` 以及 + RC/GA 类型不匹配均退出 2。 -- [ ] **Step 2: 确认 RED** +- [ ] **Step 2: 运行测试并确认 RED** Run: `bash test/suites/product/endpoint/release-notes.sh` - Expected: FAIL，缺少 `deployments/packages/render-github-release-notes.sh`。 + Expected: 非零退出，提示缺少 `render-github-release-notes.sh`。 -- [ ] **Step 3: 实现最小渲染器** +- [ ] **Step 3: 实现最小 renderer** - 使用 Bash 正则分别校验 RC/GA 版本，仓库匹配 `owner/name` 安全字符；通过单个 heredoc 输出 - 完整 Markdown，不执行用户输入。 + Bash 脚本使用 `set -euo pipefail`，校验参数数量、`owner/name` 和类型对应的 SemVer；从 + `GITHUB_SHA` 读取源码提交，未设置时使用 `unknown`。用单个 heredoc 输出在线安装、容器 + Dockerfile、运行要求、provenance 命令和当前 tag 的提交列表链接，不执行输入内容。 -- [ ] **Step 4: 确认 GREEN** +- [ ] **Step 4: 扩展 workflow 失败契约** - Run: `bash test/suites/product/endpoint/release-notes.sh` + 在 `release-workflow-contract.sh` 要求两个 workflow 都检出 `SOURCE_SHA`、调用 renderer、 + 使用 `--notes-file`，且都不含 `--generate-notes`。 + + Run: `bash test/suites/product/endpoint/release-workflow-contract.sh` + + Expected: 非零退出，旧 workflow 仍使用 `--generate-notes`。 + +- [ ] **Step 5: 接入 RC 与 GA workflow** + + release job 在下载资产前使用固定 revision 的 `actions/checkout`，设置： + + ```yaml + with: + ref: ${{ needs.build.outputs.source_sha }} + ``` + + 调用 renderer 输出 `$RUNNER_TEMP/release-notes.md`，并将 `gh release create` 参数替换为： + + ```bash + --notes-file "$RUNNER_TEMP/release-notes.md" + ``` - Expected: `[release-notes] ok`。 +- [ ] **Step 6: 验证并提交** -### Task 2: Workflow Integration + ```bash + bash test/suites/product/endpoint/release-notes.sh + bash test/suites/product/endpoint/release-workflow-contract.sh + go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.7 .github/workflows/release-candidate.yml .github/workflows/release-stable.yml + git diff --check + git add deployments/packages/render-github-release-notes.sh test/suites/product/endpoint/release-notes.sh test/suites/product/endpoint/release-workflow-contract.sh test/Makefile .github/workflows/release-candidate.yml .github/workflows/release-stable.yml + git commit -m "fix(release): restore installation notes" + ``` + + Expected: 两个契约输出 `ok`，actionlint 和 diff 检查退出 0。 + +### Task 2: User And Maintainer Documentation **Files:** -- Modify: `.github/workflows/release-candidate.yml:81-94` -- Modify: `.github/workflows/release-stable.yml:100-112` -- Modify: `test/suites/product/endpoint/release-workflow-contract.sh` +- Modify: `README.md` +- Modify: `README.zh-CN.md` +- Modify: `docs/operations/deployment.md` +- Modify: `docs/development/development.md` **Interfaces:** -- Consumes: Task 1 渲染器标准输出。 -- Produces: `$RUNNER_TEMP/release-notes.md` 和 `gh release create --notes-file`。 +- Consumes: 当前 RC/GA workflow、`linux-systemd` 与 `linux-container` 安装契约。 +- Produces: 面向用户的安装入口和面向维护者的单一发布顺序。 -- [ ] **Step 1: 扩展 workflow 契约并确认 RED** +- [ ] **Step 1: 写文档契约检查并确认 RED** - 要求 RC/GA 都包含 `render-github-release-notes.sh`、`--notes-file`，并拒绝任一文件出现 - `--generate-notes`。运行契约，预期因旧接线失败。 + 使用 `rg` 确认活跃文档不再包含 `v0.1.0-dev.20260724+097acdae`、`从 dev 构建` 或把 + GitHub 安装限定为“开发预发布”，并要求开发指南包含 `--notes-file`、`main`、 + `production-release` 和三镜像验收语义。 -- [ ] **Step 2: 接入两个工作流** +- [ ] **Step 2: 精准更新四个文档入口** - 在 release job checkout 精确 `SOURCE_SHA`，调用： + README 只说明从 GitHub Releases 选择目标版本并执行页面中的固定命令；部署指南将表格和章节 + 统一为“GitHub 发行包”，使用 ``，说明 RC/GA 与 profile；开发指南按 + `dev -> release/vX.Y.Z -> RC -> 验收 -> main -> GA` 的顺序补齐操作和前置条件。 + +- [ ] **Step 3: 验证并提交** ```bash - deployments/packages/render-github-release-notes.sh \ - "$VERSION" "$GITHUB_REPOSITORY" rc >"$RUNNER_TEMP/release-notes.md" + ! rg -n 'v0\.1\.0-dev\.20260724\+097acdae|从 `dev` 构建的可追溯' README.md README.zh-CN.md docs/operations/deployment.md docs/development/development.md + git diff --check + git add README.md README.zh-CN.md docs/operations/deployment.md docs/development/development.md + git commit -m "docs(release): align installation and publishing guides" ``` - GA 使用 `ga`，`gh release create` 使用 - `--notes-file "$RUNNER_TEMP/release-notes.md"`。 + Expected: 过期表述扫描无输出，diff 检查退出 0。 -- [ ] **Step 3: 验证 GREEN 和语法** +### Task 3: Public Repository Governance + +**Files:** +- Create: `SECURITY.md` +- Create: `CONTRIBUTING.md` + +**Interfaces:** +- Consumes: GitHub private vulnerability reporting、`docs/development/development.md`、 + `docs/development/testing.md`。 +- Produces: GitHub 自动识别的安全报告与贡献入口。 + +- [ ] **Step 1: 新增最小治理文档** + + `SECURITY.md` 明确 `0.1.x` 为当前受支持系列，要求通过 GitHub Security Advisories 的 + “Report a vulnerability” 私密报告，并列出复现、影响、版本和缓解信息。`CONTRIBUTING.md` + 说明 Issue、从 `dev` 建分支、PR 回 `dev`、Conventional Commits 和按范围验证，并链接已有 + 开发与测试指南。 + +- [ ] **Step 2: 验证链接、内容和提交** + + ```bash + rg -n 'Report a vulnerability|0\.1\.x' SECURITY.md + rg -n 'dev|Conventional Commits|development\.md|testing\.md' CONTRIBUTING.md + git diff --check + git add SECURITY.md CONTRIBUTING.md + git commit -m "docs: add security and contribution guidance" + ``` + + Expected: 所有扫描命中，diff 检查退出 0。 + +### Task 4: Integrated Verification And RC2 + +**Files:** +- Modify: GitHub repository description through `gh repo edit`。 +- Create after acceptance: RC2 acceptance report/evidence assets outside the committed source tree。 + +**Interfaces:** +- Consumes: Tasks 1-3 的提交和 GitHub release workflow。 +- Produces: 已发布并公开验收的 `v0.1.0-rc.2`。 + +- [ ] **Step 1: 运行发布相关回归** ```bash bash test/suites/product/endpoint/release-notes.sh bash test/suites/product/endpoint/release-workflow-contract.sh - go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.7 .github/workflows/release-candidate.yml .github/workflows/release-stable.yml + bash test/suites/product/endpoint/standalone-github-assets.sh + bash test/suites/product/endpoint/standalone-release-package.sh git diff --check ``` - Expected: 全部 exit 0。 + Expected: 全部 exit 0，工作区仅包含已知的计划文档改动或保持干净。 -- [ ] **Step 4: 提交并发布 rc.2** +- [ ] **Step 2: 更新仓库简介并推送 release 分支** ```bash - git add deployments/packages/render-github-release-notes.sh test/suites/product/endpoint/release-notes.sh test/suites/product/endpoint/release-workflow-contract.sh test/Makefile .github/workflows/release-candidate.yml .github/workflows/release-stable.yml - git commit -m "fix(release): restore installation notes" + gh repo edit PKU-ASAL/sysarmor --description "Linux endpoint security and correlation system with standalone detection and centralized investigation." git push github release/v0.1.0 - gh workflow run release-candidate.yml --ref release/v0.1.0 -f rc_number=2 ``` - Expected: `v0.1.0-rc.2` 为 Pre-release，描述包含三类用户说明并指向新提交。 + Expected: GitHub 仓库简介非空，远端 release 分支指向本地 HEAD。 + +- [ ] **Step 3: 发布并核验 RC2** + + ```bash + gh workflow run release-candidate.yml --repo PKU-ASAL/sysarmor --ref release/v0.1.0 -f rc_number=2 + ``` + + 等待 workflow 成功；确认 `v0.1.0-rc.2` 是 Pre-release，target 为 release 分支 HEAD，资产完整， + Release body 自动包含安装、容器、provenance 和 changelog。 + +- [ ] **Step 4: 完成公开验收** + + 对 RC2 的公开 `install.sh` 运行 fresh medium 和 Ubuntu 22.04、Ubuntu 24.04、Debian 12 + 三镜像矩阵；要求 dropped/parse/watcher errors 为 0，三镜像各 5/5 场景、16 Signal、 + Precision/Recall 1，并将报告与证据上传到 RC2 Assets。 + +- [ ] **Step 5: 最终发布就绪检查** + + 确认 `production-release` Environment、审批人和三个签名配置已建立；在此之前不触发 GA。 + 汇报提交、RC2、验收结果以及唯一剩余的正式发布门禁。 From 11abe32101d9e0c1d386b6624993958cc1f3d12e Mon Sep 17 00:00:00 2001 From: jiandong Date: Tue, 28 Jul 2026 15:53:09 +0800 Subject: [PATCH 5/8] fix(release): restore installation notes --- .github/workflows/release-candidate.yml | 8 +- .github/workflows/release-stable.yml | 8 +- .../packages/render-github-release-notes.sh | 79 +++++++++++++++++++ test/Makefile | 1 + test/suites/product/endpoint/release-notes.sh | 51 ++++++++++++ .../endpoint/release-workflow-contract.sh | 16 ++++ 6 files changed, 161 insertions(+), 2 deletions(-) create mode 100755 deployments/packages/render-github-release-notes.sh create mode 100755 test/suites/product/endpoint/release-notes.sh diff --git a/.github/workflows/release-candidate.yml b/.github/workflows/release-candidate.yml index da75856c..d2a06c1f 100644 --- a/.github/workflows/release-candidate.yml +++ b/.github/workflows/release-candidate.yml @@ -72,6 +72,11 @@ jobs: permissions: contents: write steps: + - name: Check out release source + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.build.outputs.source_sha }} + - name: Download release assets uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 with: @@ -86,9 +91,10 @@ jobs: ASSET_DIR: ${{ github.workspace }}/dist/github-release run: | set -euo pipefail + deployments/packages/render-github-release-notes.sh "$VERSION" "$GITHUB_REPOSITORY" rc >"$RUNNER_TEMP/release-notes.md" gh release create "$VERSION" "$ASSET_DIR"/* \ --repo "$GITHUB_REPOSITORY" \ --target "$SOURCE_SHA" \ --title "SysArmor $VERSION" \ - --generate-notes \ + --notes-file "$RUNNER_TEMP/release-notes.md" \ --prerelease diff --git a/.github/workflows/release-stable.yml b/.github/workflows/release-stable.yml index c9e47ef3..6c66773d 100644 --- a/.github/workflows/release-stable.yml +++ b/.github/workflows/release-stable.yml @@ -92,6 +92,11 @@ jobs: permissions: contents: write steps: + - name: Check out release source + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ needs.build.outputs.source_sha }} + - name: Download release assets uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 with: @@ -106,8 +111,9 @@ jobs: ASSET_DIR: ${{ github.workspace }}/dist/github-release run: | set -euo pipefail + deployments/packages/render-github-release-notes.sh "$VERSION" "$GITHUB_REPOSITORY" ga >"$RUNNER_TEMP/release-notes.md" gh release create "$VERSION" "$ASSET_DIR"/* \ --repo "$GITHUB_REPOSITORY" \ --target "$SOURCE_SHA" \ --title "SysArmor $VERSION" \ - --generate-notes + --notes-file "$RUNNER_TEMP/release-notes.md" diff --git a/deployments/packages/render-github-release-notes.sh b/deployments/packages/render-github-release-notes.sh new file mode 100755 index 00000000..d86900d0 --- /dev/null +++ b/deployments/packages/render-github-release-notes.sh @@ -0,0 +1,79 @@ +#!/usr/bin/env bash +set -euo pipefail + +usage() { + echo "usage: render-github-release-notes.sh VERSION OWNER/REPOSITORY rc|ga" >&2 +} + +if [[ $# -ne 3 ]]; then + usage + exit 2 +fi + +version="$1" +repository="$2" +release_type="$3" +source_sha="${SOURCE_SHA:-${GITHUB_SHA:-unknown}}" + +[[ "$repository" =~ ^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$ ]] || { + echo "[release-notes][ERROR] invalid repository: $repository" >&2 + exit 2 +} + +case "$release_type" in + rc) + [[ "$version" =~ ^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[1-9][0-9]*$ ]] || { + echo "[release-notes][ERROR] invalid RC version: $version" >&2 + exit 2 + } + release_label="release candidate" + ;; + ga) + [[ "$version" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || { + echo "[release-notes][ERROR] invalid GA version: $version" >&2 + exit 2 + } + release_label="release" + ;; + *) + echo "[release-notes][ERROR] release type must be rc or ga" >&2 + exit 2 + ;; +esac + +cat < +\`\`\` + +## Verify build provenance + +\`\`\`bash +gh attestation verify sysarmor-agent-linux-amd64-$version.tar.gz --repo $repository +\`\`\` + +## What's changed + +[View commits for $version](https://github.com/$repository/commits/$version) +EOF diff --git a/test/Makefile b/test/Makefile index 49096a92..cbec0647 100644 --- a/test/Makefile +++ b/test/Makefile @@ -135,6 +135,7 @@ product-endpoint-standalone: bash suites/product/endpoint/standalone-release-package.sh bash suites/product/endpoint/container-entrypoint.sh bash suites/product/endpoint/standalone-github-assets.sh + bash suites/product/endpoint/release-notes.sh bash suites/product/endpoint/release-workflow-contract.sh bash suites/product/endpoint/release-container-e2e-contract.sh diff --git a/test/suites/product/endpoint/release-notes.sh b/test/suites/product/endpoint/release-notes.sh new file mode 100755 index 00000000..fd14a1a4 --- /dev/null +++ b/test/suites/product/endpoint/release-notes.sh @@ -0,0 +1,51 @@ +#!/usr/bin/env bash +set -euo pipefail + +REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)" +renderer="$REPO/deployments/packages/render-github-release-notes.sh" +work="$(mktemp -d)" +trap 'rm -rf "$work"' EXIT + +require_text() { + local file="$1" + local text="$2" + grep -Fq -- "$text" "$file" || { + echo "[release-notes][ERROR] missing text: $text" >&2 + exit 1 + } +} + +expect_invalid() { + local name="$1" + shift + set +e + "$renderer" "$@" >"$work/$name.out" 2>"$work/$name.err" + local status=$? + set -e + [[ "$status" -eq 2 ]] || { + echo "[release-notes][ERROR] $name exited $status, expected 2" >&2 + exit 1 + } +} + +GITHUB_SHA=0123456789abcdef "$renderer" v0.1.0-rc.2 PKU-ASAL/sysarmor rc >"$work/rc.md" +require_text "$work/rc.md" 'SysArmor `v0.1.0-rc.2` release candidate from commit `0123456789abcdef`.' +require_text "$work/rc.md" 'releases/download/v0.1.0-rc.2/install.sh' +require_text "$work/rc.md" '--profile linux-container' +require_text "$work/rc.md" '--privileged --cgroupns=host --restart unless-stopped' +require_text "$work/rc.md" 'gh attestation verify sysarmor-agent-linux-amd64-v0.1.0-rc.2.tar.gz' +require_text "$work/rc.md" 'https://github.com/PKU-ASAL/sysarmor/commits/v0.1.0-rc.2' + +GITHUB_SHA=fedcba9876543210 "$renderer" v0.1.0 PKU-ASAL/sysarmor ga >"$work/ga.md" +require_text "$work/ga.md" 'SysArmor `v0.1.0` release from commit `fedcba9876543210`.' +require_text "$work/ga.md" 'releases/download/v0.1.0/install.sh' +require_text "$work/ga.md" 'https://github.com/PKU-ASAL/sysarmor/commits/v0.1.0' + +expect_invalid bad-version v0.1 PKU-ASAL/sysarmor ga +expect_invalid bad-repository v0.1.0 'owner only' ga +expect_invalid bad-type v0.1.0 PKU-ASAL/sysarmor beta +expect_invalid rc-as-ga v0.1.0-rc.2 PKU-ASAL/sysarmor ga +expect_invalid ga-as-rc v0.1.0 PKU-ASAL/sysarmor rc +expect_invalid missing-argument v0.1.0 PKU-ASAL/sysarmor + +echo "[release-notes] ok" diff --git a/test/suites/product/endpoint/release-workflow-contract.sh b/test/suites/product/endpoint/release-workflow-contract.sh index 153598c0..10da1f50 100755 --- a/test/suites/product/endpoint/release-workflow-contract.sh +++ b/test/suites/product/endpoint/release-workflow-contract.sh @@ -5,6 +5,7 @@ REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)" build="$REPO/.github/workflows/release-build.yml" candidate="$REPO/.github/workflows/release-candidate.yml" stable="$REPO/.github/workflows/release-stable.yml" +renderer="$REPO/deployments/packages/render-github-release-notes.sh" dependabot="$REPO/.github/dependabot.yml" require_file() { @@ -17,6 +18,7 @@ require_file() { require_file "$build" require_file "$candidate" require_file "$stable" +require_file "$renderer" test ! -e "$REPO/.github/workflows/dev-prerelease.yml" grep -Fq 'workflow_call:' "$build" @@ -55,6 +57,13 @@ grep -Fq 'uses: ./.github/workflows/release-build.yml' "$candidate" grep -Fq 'release_type: rc' "$candidate" grep -Fq 'contents: write' "$candidate" grep -Fq -- '--target "$SOURCE_SHA"' "$candidate" +grep -Fq 'ref: ${{ needs.build.outputs.source_sha }}' "$candidate" +grep -Fq 'render-github-release-notes.sh "$VERSION" "$GITHUB_REPOSITORY" rc' "$candidate" +grep -Fq -- '--notes-file "$RUNNER_TEMP/release-notes.md"' "$candidate" +if grep -Fq -- '--generate-notes' "$candidate"; then + echo "[release-workflow-contract][ERROR] candidate release must use rendered notes" >&2 + exit 1 +fi grep -Fq -- '--prerelease' "$candidate" grep -Fq 'actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1' "$candidate" @@ -70,6 +79,13 @@ grep -Fq 'uses: ./.github/workflows/release-build.yml' "$stable" grep -Fq 'release_type: ga' "$stable" grep -Fq 'contents: write' "$stable" grep -Fq -- '--target "$SOURCE_SHA"' "$stable" +grep -Fq 'ref: ${{ needs.build.outputs.source_sha }}' "$stable" +grep -Fq 'render-github-release-notes.sh "$VERSION" "$GITHUB_REPOSITORY" ga' "$stable" +grep -Fq -- '--notes-file "$RUNNER_TEMP/release-notes.md"' "$stable" +if grep -Fq -- '--generate-notes' "$stable"; then + echo "[release-workflow-contract][ERROR] stable release must use rendered notes" >&2 + exit 1 +fi if grep -Fq -- '--prerelease' "$stable"; then echo "[release-workflow-contract][ERROR] stable release must not be a prerelease" >&2 exit 1 From 5bf858b401026a7a2637878ce298ccc700564544 Mon Sep 17 00:00:00 2001 From: jiandong Date: Tue, 28 Jul 2026 15:54:57 +0800 Subject: [PATCH 6/8] docs(release): align installation and publishing guides --- README.md | 9 +++++---- README.zh-CN.md | 5 +++-- docs/development/development.md | 13 +++++++++---- docs/operations/deployment.md | 21 +++++++++++---------- 4 files changed, 28 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index b50f8a35..1bb339c7 100644 --- a/README.md +++ b/README.md @@ -50,10 +50,11 @@ sudo sysarmorctl event watch --include-recent sudo sysarmorctl signal watch --include-recent ``` -You can also select a development pre-release on GitHub Releases and run the exact install command shown -on that release. Public pre-releases install in standalone mode by default and expose a `linux-container` -profile for image builds. See [Deployment](docs/operations/deployment.md) -for verification, platform limits, and offline distribution constraints. +You can also select a release on GitHub Releases and run the exact install command shown on that release. +Release candidates are marked as pre-releases and become stable releases after acceptance. Public packages +install in standalone mode by default and expose a `linux-container` profile for image builds. See +[Deployment](docs/operations/deployment.md) for verification, platform limits, and offline distribution +constraints. See [Quickstart](docs/quickstart.md) for prerequisites, verification, and next steps. diff --git a/README.zh-CN.md b/README.zh-CN.md index d7b92d59..3f08008c 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -50,8 +50,9 @@ sudo sysarmorctl event watch --include-recent sudo sysarmorctl signal watch --include-recent ``` -也可以从 GitHub Releases 选择一个开发预发布版本，执行其页面提供的一键安装命令。公开预发布包 -默认安装为 standalone；详细的校验、平台限制和离线分发边界见[部署指南](docs/operations/deployment.md)。 +也可以从 GitHub Releases 选择目标版本，执行其页面提供的一键安装命令。候选版本标记为 +Pre-release，验收通过的版本发布为正式版本；公开发行包默认安装为 standalone。详细的校验、 +平台限制和离线分发边界见[部署指南](docs/operations/deployment.md)。 完整前置条件、验证步骤和下一步见[快速开始](docs/quickstart.md)。 diff --git a/docs/development/development.md b/docs/development/development.md index 29e18090..717ec2d7 100644 --- a/docs/development/development.md +++ b/docs/development/development.md @@ -65,16 +65,21 @@ make web-build ### GitHub 发布 发布使用短生命周期 `release/vX.Y.Z` 分支。先将功能分支通过 PR 合入 `dev`，再从冻结的 -`dev` 创建 release 分支；不要直接提交到 `dev` 或 `main`。 +`dev` 创建 release 分支；不要直接提交到 `dev` 或 `main`。首次引入或修改发布入口时， +对应 workflow 必须先存在于默认分支，否则 GitHub 不提供 `workflow_dispatch` 入口。 从 `release/vX.Y.Z` 手动触发 `.github/workflows/release-candidate.yml`，输入正整数 `rc_number`，创建 `vX.Y.Z-rc.N` Pre-release。RC 使用 runner 临时生成的 RSA manifest key -和 Ed25519 content key。RC 发布后，必须使用公开 GitHub Release URL 完成 fresh medium 和 -Ubuntu 22.04、Ubuntu 24.04、Debian 12 三镜像验收，再冻结 release 分支。 +和 Ed25519 content key。工作流从同一提交生成安装说明、容器示例、provenance 验证命令和 +变更链接，并通过 `--notes-file` 创建 Release，不使用只生成变更列表的默认说明。RC 发布后， +必须使用公开 GitHub Release URL 完成 fresh medium 和 Ubuntu 22.04、Ubuntu 24.04、 +Debian 12 三镜像验收，再冻结 release 分支。 验收通过后，将 release 分支通过 PR 合入 `main`。从 `main` 手动触发 `.github/workflows/release-stable.yml`，输入不带 `v` 的 `version` 和已验收的 -`accepted_rc_tag`。工作流仅在 `main` 与 RC tag 的 Git tree 完全一致时继续。 +`accepted_rc_tag`。工作流仅在 `main` 与 RC tag 的 Git tree 完全一致时继续，并使用同一 +Release notes 渲染器生成正式版本说明。GitHub Releases 是发行变更记录的事实来源，不另行 +维护重复的 changelog。 正式发布前，仓库必须配置受保护的 `production-release` Environment、审批人，以及： diff --git a/docs/operations/deployment.md b/docs/operations/deployment.md index 2849f183..daadcefe 100644 --- a/docs/operations/deployment.md +++ b/docs/operations/deployment.md @@ -7,7 +7,7 @@ | 目标 | 入口 | 适用场景 | |---|---|---| | 单机 Agent | `make install-agent` | 无平台连接的主机采集、检测和本地调查 | -| GitHub 开发预发布 | Release 页面中的 `install.sh` | 从 `dev` 构建的可追溯 standalone 体验版本 | +| GitHub 发行包 | Release 页面中的 `install.sh` | 可追溯的 standalone 候选版本或正式版本 | | 本地管理平台 | `make deploy` | 端云链路、集中管理和开发验证 | 当前 Compose 配置面向单机开发和验证，默认凭据、无安全插件的 OpenSearch 以及宿主机暴露的基础设施端口不应直接用于生产环境。 @@ -46,18 +46,19 @@ sudo sysarmorctl agent health 默认配置运行 managed Tetragon、host scope 和 observe-only 模式，不连接平台。注册信息由 enrollment 写入本地状态，不应手工添加到 YAML。自定义安装路径和配置项见[配置参考](../reference/configuration.md)。 -### 安装 GitHub 开发预发布 +### 安装 GitHub 发行包 -在 GitHub Releases 页面选择标记为 Pre-release 的版本，使用该版本说明中的固定 URL： +在 GitHub Releases 页面选择目标版本，使用该版本说明中的固定 URL。候选版本标记为 +Pre-release；正式版本不带该标记： ```bash -curl -fsSL https://github.com/PKU-ASAL/sysarmor/releases/download//install.sh | sudo bash +curl -fsSL https://github.com/PKU-ASAL/sysarmor/releases/download//install.sh | sudo bash ``` -开发预发布支持 Linux x86_64；默认 `linux-systemd` profile 安装主机服务， -`linux-container` profile 用于容器镜像。版本号同时包含构建时间与 Git commit，例如 -`v0.1.0-dev.20260724+097acdae`。安装脚本下载同一 Release 的归档，校验固定 SHA-256， -安装后等待 Agent 健康检查通过。重复安装会更新程序和 systemd unit，但保留已有配置、策略和本地数据。 +公开发行包支持 Linux x86_64；默认 `linux-systemd` profile 安装主机服务， +`linux-container` profile 用于容器镜像。RC tag 采用 `vX.Y.Z-rc.N`，正式版本采用 +`vX.Y.Z`。安装脚本下载同一 Release 的归档，校验固定 SHA-256，安装后等待 Agent 健康检查 +通过。重复安装会更新程序和 systemd unit，但保留已有配置、策略和本地数据。 GitHub 公开归档只包含 SysArmor。安装时从 Tetragon 官方 Release 下载锁定版本并校验固定 SHA-256，从而避免在第三方许可证清单完成前重新分发其二进制。需要完全离线的一体包时，仍须先完成 @@ -66,7 +67,7 @@ SHA-256，从而避免在第三方许可证清单完成前重新分发其二进 可使用 GitHub CLI 验证构建来源： ```bash -gh attestation verify sysarmor-agent-linux-amd64-.tar.gz --repo PKU-ASAL/sysarmor +gh attestation verify sysarmor-agent-linux-amd64-.tar.gz --repo PKU-ASAL/sysarmor ``` ### 安装到容器镜像 @@ -168,7 +169,7 @@ make release RELEASE_VERSION=v1.0.0 产物写入 `dist/release/`。Package 服务提供不可变字节，Manager 管理 artifact 元数据、channel、一次性 enrollment 和安装脚本。 -本地平台 Agent bundle 还包含 Tetragon、bpftool、gops 和 BPF 对象等第三方资产。仓库根目录的 MulanPSL-2.0 只覆盖 SysArmor，不改变第三方组件的许可证。在完成逐项许可证清单、LICENSE/NOTICE 携带和全部打包文件完整性校验前，该一体 bundle 只用于开发与评估，不能作为已经完成外部分发合规的制品发布。GitHub 开发预发布使用不携带 Tetragon 二进制的 thin 包，不属于该一体 bundle。 +本地平台 Agent bundle 还包含 Tetragon、bpftool、gops 和 BPF 对象等第三方资产。仓库根目录的 MulanPSL-2.0 只覆盖 SysArmor，不改变第三方组件的许可证。在完成逐项许可证清单、LICENSE/NOTICE 携带和全部打包文件完整性校验前，该一体 bundle 只用于开发与评估，不能作为已经完成外部分发合规的制品发布。GitHub 发行包使用不携带 Tetragon 二进制的 thin 包，不属于该一体 bundle。 推荐从 Manager Console 的 Deploy 页面选择 artifact、channel 和安装 profile，然后在目标端执行生成的安装命令。完整流程为： From d7cd2624fa4062ac9d0726f78113a6be87bd87b0 Mon Sep 17 00:00:00 2001 From: jiandong Date: Tue, 28 Jul 2026 15:55:56 +0800 Subject: [PATCH 7/8] docs: add security and contribution guidance --- CONTRIBUTING.md | 31 +++++++++++++++++++++++++++++++ SECURITY.md | 17 +++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..e9400bb9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,31 @@ +# Contributing To SysArmor + +SysArmor welcomes focused bug reports and pull requests. Before starting a larger change, open an issue +to confirm the problem, intended outcome, and ownership boundary. Report security vulnerabilities through +the private process in [SECURITY.md](SECURITY.md), not through a public issue. + +## Development Workflow + +Create feature and fix branches from `dev`, then open pull requests back to `dev`. Release branches are +short-lived and are merged into `main` only after release-candidate acceptance. Do not commit directly to +`dev` or `main`. + +Keep changes narrow and follow the surrounding code style. Use Conventional Commits such as `feat:`, +`fix:`, `docs:`, and `test:`; keep each commit focused on one concern. The +[development guide](docs/development/development.md) describes repository boundaries, build commands, and +contracts that must stay synchronized. + +## Verification + +Add or update tests for behavior changes and run the smallest suite that fully covers the change. Shared +contracts and user-facing workflows require broader regression coverage. See the +[testing guide](docs/development/testing.md) for Product, Effectiveness, and Performance suites. + +At minimum, run: + +```bash +make test-unit +git diff --check +``` + +Document any relevant test that cannot be run and explain the remaining risk in the pull request. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..31ce8233 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,17 @@ +# Security Policy + +## Supported Versions + +SysArmor is preparing its first stable release. Security fixes currently target the latest `0.1.x` +release candidate and, once published, the latest stable `0.1.x` release. Older development builds and +release candidates are not maintained after a replacement is available. + +## Reporting A Vulnerability + +Please do not disclose suspected vulnerabilities in a public issue. Use GitHub's +[Report a vulnerability](https://github.com/PKU-ASAL/sysarmor/security/advisories/new) form so the report +and follow-up discussion remain private. + +Include the affected version, deployment profile, reproduction steps, expected impact, and any known +mitigation. Maintainers will acknowledge the report through the advisory and coordinate validation, +remediation, and disclosure there. From d44b62a86a4e11938d0ddfa920326f19a590316e Mon Sep 17 00:00:00 2001 From: jiandong Date: Tue, 28 Jul 2026 16:59:49 +0800 Subject: [PATCH 8/8] fix(test): proxy Tetragon release downloads --- test/release/config.sh | 12 ++++++++++++ test/release/images/debian12/Dockerfile | 4 +++- test/release/images/ubuntu2204/Dockerfile | 4 +++- test/release/images/ubuntu2404/Dockerfile | 4 +++- test/release/run.sh | 7 ++++++- .../endpoint/release-container-e2e-contract.sh | 5 +++++ 6 files changed, 32 insertions(+), 4 deletions(-) diff --git a/test/release/config.sh b/test/release/config.sh index b68e8aa2..333ec0f1 100755 --- a/test/release/config.sh +++ b/test/release/config.sh @@ -55,3 +55,15 @@ resolve_download_url() { echo " 代理: $proxied_url" >&2 return 1 } + +resolve_tetragon_url() { + local bundle_env="$TEST_ROOT/../deployments/sensors/tetragon/bundle.env" + local TETRAGON_URL="" + [[ -f "$bundle_env" ]] || { + echo "[release][ERROR] 缺少 Tetragon bundle 配置: $bundle_env" >&2 + return 1 + } + # shellcheck source=/dev/null + source "$bundle_env" + resolve_download_url "$TETRAGON_URL" +} diff --git a/test/release/images/debian12/Dockerfile b/test/release/images/debian12/Dockerfile index a55159c5..bcc61ce5 100644 --- a/test/release/images/debian12/Dockerfile +++ b/test/release/images/debian12/Dockerfile @@ -1,13 +1,15 @@ FROM debian:12 ARG SYSARMOR_INSTALL_URL +ARG SYSARMOR_TETRAGON_URL RUN apt-get update \ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends bash ca-certificates curl jq nodejs procps sqlite3 util-linux \ && rm -rf /var/lib/apt/lists/* RUN test -n "$SYSARMOR_INSTALL_URL" \ && base_url="${SYSARMOR_INSTALL_URL%/*}" \ && curl -fsSL "$SYSARMOR_INSTALL_URL" \ - | SYSARMOR_RELEASE_BASE_URL="$base_url" bash -s -- --profile linux-container + | SYSARMOR_RELEASE_BASE_URL="$base_url" SYSARMOR_TETRAGON_URL="$SYSARMOR_TETRAGON_URL" \ + bash -s -- --profile linux-container COPY fixtures /opt/sysarmor-release-test diff --git a/test/release/images/ubuntu2204/Dockerfile b/test/release/images/ubuntu2204/Dockerfile index c62d891a..ab35e9b3 100644 --- a/test/release/images/ubuntu2204/Dockerfile +++ b/test/release/images/ubuntu2204/Dockerfile @@ -1,13 +1,15 @@ FROM ubuntu:22.04 ARG SYSARMOR_INSTALL_URL +ARG SYSARMOR_TETRAGON_URL RUN apt-get update \ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends bash ca-certificates curl jq nodejs procps sqlite3 util-linux \ && rm -rf /var/lib/apt/lists/* RUN test -n "$SYSARMOR_INSTALL_URL" \ && base_url="${SYSARMOR_INSTALL_URL%/*}" \ && curl -fsSL "$SYSARMOR_INSTALL_URL" \ - | SYSARMOR_RELEASE_BASE_URL="$base_url" bash -s -- --profile linux-container + | SYSARMOR_RELEASE_BASE_URL="$base_url" SYSARMOR_TETRAGON_URL="$SYSARMOR_TETRAGON_URL" \ + bash -s -- --profile linux-container COPY fixtures /opt/sysarmor-release-test diff --git a/test/release/images/ubuntu2404/Dockerfile b/test/release/images/ubuntu2404/Dockerfile index ab08f71a..fbf365e9 100644 --- a/test/release/images/ubuntu2404/Dockerfile +++ b/test/release/images/ubuntu2404/Dockerfile @@ -1,13 +1,15 @@ FROM ubuntu:24.04 ARG SYSARMOR_INSTALL_URL +ARG SYSARMOR_TETRAGON_URL RUN apt-get update \ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends bash ca-certificates curl jq nodejs procps sqlite3 util-linux \ && rm -rf /var/lib/apt/lists/* RUN test -n "$SYSARMOR_INSTALL_URL" \ && base_url="${SYSARMOR_INSTALL_URL%/*}" \ && curl -fsSL "$SYSARMOR_INSTALL_URL" \ - | SYSARMOR_RELEASE_BASE_URL="$base_url" bash -s -- --profile linux-container + | SYSARMOR_RELEASE_BASE_URL="$base_url" SYSARMOR_TETRAGON_URL="$SYSARMOR_TETRAGON_URL" \ + bash -s -- --profile linux-container COPY fixtures /opt/sysarmor-release-test diff --git a/test/release/run.sh b/test/release/run.sh index 0977284d..3fa26d3c 100755 --- a/test/release/run.sh +++ b/test/release/run.sh @@ -10,6 +10,7 @@ source "$HERE/scenarios.sh" RESULT_ROOT="" INSTALL_URL="" +TETRAGON_URL="" ACTIVE_BUSINESS="" ACTIVE_ATTACKER="" ACTIVE_ATTACKER_HOST="" @@ -50,7 +51,9 @@ cleanup() { trap cleanup EXIT build_image() { - local args=(--network host -f "$HERE/images/$1/Dockerfile" --build-arg "SYSARMOR_INSTALL_URL=$INSTALL_URL") + local args=(--network host -f "$HERE/images/$1/Dockerfile" + --build-arg "SYSARMOR_INSTALL_URL=$INSTALL_URL" + --build-arg "SYSARMOR_TETRAGON_URL=$TETRAGON_URL") [[ "$FRESH_DOWNLOAD" != "1" ]] || args+=(--no-cache) docker build "${args[@]}" -t "$2" "$HERE" >"$3/build.log" 2>&1 } @@ -133,7 +136,9 @@ run_image() { main() { prepare_result_root "$TEST_ROOT/.results/release" "$RUN_ID" INSTALL_URL="$(resolve_download_url "$(resolve_install_url)")" + TETRAGON_URL="$(resolve_tetragon_url)" printf '%s\n' "$INSTALL_URL" >"$RESULT_ROOT/install-url.txt" + printf '%s\n' "$TETRAGON_URL" >"$RESULT_ROOT/tetragon-url.txt" for image in $IMAGES; do case "$image" in ubuntu2204|ubuntu2404|debian12) run_image "$image" ;; diff --git a/test/suites/product/endpoint/release-container-e2e-contract.sh b/test/suites/product/endpoint/release-container-e2e-contract.sh index d5dd2700..e630cf51 100755 --- a/test/suites/product/endpoint/release-container-e2e-contract.sh +++ b/test/suites/product/endpoint/release-container-e2e-contract.sh @@ -21,6 +21,8 @@ for image in ubuntu2204 ubuntu2404 debian12; do dockerfile="$RELEASE/images/$image/Dockerfile" test -f "$dockerfile" grep -Fq 'ARG SYSARMOR_INSTALL_URL' "$dockerfile" + grep -Fq 'ARG SYSARMOR_TETRAGON_URL' "$dockerfile" + grep -Fq 'SYSARMOR_TETRAGON_URL="$SYSARMOR_TETRAGON_URL"' "$dockerfile" grep -Fq -- '--profile linux-container' "$dockerfile" grep -Fq 'nodejs' "$dockerfile" grep -Fq 'COPY fixtures /opt/sysarmor-release-test' "$dockerfile" @@ -37,6 +39,9 @@ grep -Fq 'assert.sh' "$RELEASE/run.sh" grep -Fq 'FRESH_DOWNLOAD="${FRESH_DOWNLOAD:-1}"' "$RELEASE/config.sh" grep -Fq 'RELEASE_PROXY_URL="${RELEASE_PROXY_URL-https://gh-proxy.org}"' "$RELEASE/config.sh" grep -Fq -- '--no-cache' "$RELEASE/run.sh" +grep -Fq -- '--build-arg "SYSARMOR_TETRAGON_URL=$TETRAGON_URL"' "$RELEASE/run.sh" +grep -Fq 'TETRAGON_URL="$(resolve_tetragon_url)"' "$RELEASE/run.sh" +grep -Fq 'deployments/sensors/tetragon/bundle.env' "$RELEASE/config.sh" grep -Fq -- '--privileged' "$RELEASE/run.sh" grep -Fq -- '--cgroupns=host' "$RELEASE/run.sh" grep -Fq '/sys/kernel/btf/vmlinux:/sys/kernel/btf/vmlinux:ro' "$RELEASE/run.sh"