shpak-e/Actionsplane

## 为什么需要 如果你的团队拥有 30 个以上的仓库，GitHub Actions 无法为你提供全局视图。你将面临： - **状态碎片化** — 需要 N 个浏览器标签页才能知道构建是否成功。 - **供应链盲区** — 未 pin 的 actions 和过于宽泛的 `GITHUB_TOKEN` scope，在发生安全事件之前都处于隐形状态（如 tj-actions, trivy-action 等）。 - **Workflow 偏差** — 到处复制粘贴的同一个 workflow，逐渐产生差异。 - **修复苦差事** — 每次废弃或 pin 操作都意味着需要手动进行 N 次 checkout、N 次编辑和 N 个 PR。 现有工具都只能覆盖其中一部分：扫描器用于发现单个仓库中的问题，机器人用于升级版本，仪表盘用于展示指标。而 ActionsPlane 将**观察 + 审计 + 修复**结合在一个闭环中 —— 并且它所做的每一次更改都通过 pull request 落地，绝不直接 push。 ## 功能介绍 **🔭 观察** — 一个 GitHub App 会将 `workflow_run`/`workflow_job` webhooks 流式传输到 Postgres 中（经过 HMAC 验证、去重，并以轮询 reconciler 作为兜底方案）。一个仪表盘即可展示跨所有仓库的实时运行情况，包含每个 workflow 的指标（成功率、p50/p95 耗时、flakiness）以及一个 **Pipelines** 图谱，用于映射跨仓库的 trigger 链（`workflow_run`、可复用 workflows、dispatch）—— 精确到出错的 pipeline 中失败的步骤。 **🔍 审计** — workflows 会被解析为带类型的 AST 并进行持续检查：未 pin 的 actions、缺失或过于宽泛的 `permissions:`、已废弃的 actions、缺失的 `concurrency:`、未经验证的发布者。发现的问题具有生命周期，会汇总成每个仓库的安全态势记分卡，并作为 SARIF 上传至 GitHub Code Scanning（已解决的问题会自动关闭其对应的告警）。 **🛡️ 安全公告监控** — 轮询 GitHub Advisory Database (GHSA) 中关于 `actions` 生态系统的信息，并将其与你的整个机群实际使用的 actions 进行关联。因此，当你依赖的某个 action 出现新披露的漏洞时，它会以按严重程度排序的、按仓库分类的影响列表呈现 —— 并在首次发现时向你的通知渠道发送告警。 **📐 偏差控制** — 注册一个标准的 workflow 模板，将仓库绑定到该模板，即可获得基于 AST 的结构差异对比（完全相同 → 轻微差异 → 内容差异 → 结构差异），而不是嘈杂的文本差异。你可以准确查看 120 个仓库中有哪些偏离了黄金发布 workflow，以及偏离的严重程度。 **🔧 修复** — 批量 **campaigns**：选择一个操作（例如 *将每个 action pin 到其 commit SHA*），预览每个仓库的 **dry-run diff**，然后应用 —— ActionsPlane 会为每个仓库创建一个分支和 PR，并进行保留注释和格式的 YAML 编辑（通过 `ruamel` 往返处理）。应用过程受到双重门禁保护（opt-in 标志 + operate token），并复用 dry-run 中解析出的 SHA，确保经过审查的 diff 与最终落地的内容完全一致。每一次写入都会记录在只能追加的审计日志中。 **✅ 验证闭环** — 一个 campaign 不仅会打开 PR，它还会**证明修复已落地**。在创建时，它会快照所针对的发现结果；在 PR 合并后，重新审计这些仓库可以确认哪些问题得到了实际解决 —— campaign 会报告*“已解决 41/47”*并附带每个仓库的明细，让你看到的是全局安全态势的转变，而不仅仅是 PR 数量。**导出证据**功能可以为任何 campaign 下载一个防篡改的合规证据包（可打印的 HTML 报告 + 机器可读的 JSON + SHA-256 清单）。 **没有 GitHub App？离线模式** 可以通过公共 API 拉取任何公共仓库列表的 workflows/runs —— 享受完整的仪表盘功能，且无需 webhooks。此外，`actionsplane audit local .` 可作为 CI 门禁扫描本地的 checkout 代码（发现问题时以非零状态码退出）。 ## 快速开始 **最快方式 — 使用预构建镜像，无需构建。** 从 GHCR 拉取四个组件镜像，并（默认情况下） 随着新版本的发布保持自动更新： ``` docker compose -f deploy/docker-compose.ghcr.yml pull docker compose -f deploy/docker-compose.ghcr.yml up -d open http://localhost:3001 # dashboard open http://localhost:8000/docs # API ``` **或者从源码构建**（开发沙箱环境）： ``` # 完整本地栈：Postgres + Redis + API + ingestor + worker，自动迁移 docker compose -f deploy/docker-compose.full.yml up --build # 演示数据，无需 GitHub App： PYTHONPATH=src python scripts/seed_local.py ``` **或者用于迭代代码：** ``` make install # uv sync make up # Postgres + Redis make migrate && make test && make lint make api # + make ingestor / make worker (host-run, fast reload) ``` 要接收**真实仓库**的数据，请创建一个 GitHub App 并将其安装到你想要的仓库中（权限和 webhook 设置已在 `.env.example` 中记录）—— 或者对于公共仓库使用离线模式，无需 App。 ``` # CLI 亮点 actionsplane audit local . # scan a local repo, CI-gate friendly actionsplane audit all # fleet audit via the API actionsplane campaign preview --op pin-shas --file # what would change, before anything changes actionsplane campaign create / status # run the campaign ``` ## 部署 提供四种途径 — Compose（从源码构建或预构建+自动重载），通过 kustomize 部署的 Kubernetes（`deploy/k8s/`）或 Helm（`deploy/helm/actionsplane/`）— 所有内容均在 **[deploy/README.md](deploy/README.md)** 中详细说明， 包括 GHCR 镜像的构建方式（每次 `master` push 时构建 `edge`，打 tag 时构建 semver）以及如何 启用自动更新（Compose 使用 Watchtower，k8s 使用 Keel）。默认采用安全加固：非 root 只读容器、 默认拒绝的 NetworkPolicies、Redis 认证、ingress TLS、双层 API token （operate/read-only）。 ## 构建方式 FastAPI + SQLAlchemy (async) + Postgres + Redis/arq worker；React + Vite + TanStack Query 前端并支持 SSE 实时更新；Typer CLI；端到端可选的 OpenTelemetry 追踪。包含 340 多项封闭式测试，其中包括针对 YAML 编辑引擎的 hypothesis 属性测试。 **设计原则：** 使用 GitHub App，绝不用 PAT · 以 webhooks 为优先，仅将轮询作为数据对账手段 · **所有编辑均通过 PR 进行**，绝不直接 push · 基于 AST 而非正则 —— 编辑会保留注释和格式 · 失败即拒绝的写入门禁 · 自托管，无 SaaS 依赖。 ## 项目状态与路线图 v1 功能已完整并在本地沙箱中完成安全加固，且已针对真实的 GitHub 组织进行实时验证，证明了端到端的能力。近期工作：**验证闭环**（campaigns 证明其修复已落地）、带有优化建议的全局 **Cost/time** 视图、**SHA-pin readiness** 通道、应用内的 **Activity** 轨迹、**Drift → template-sync** campaigns、通知功能（Slack/webhook/email），以及带有自动重载的 GHCR 镜像流水线。下一步计划：持续安全公告监控、consumer-graph/blast-radius 事件模式和合规证据导出。 ## 贡献指南 在项目退出预览阶段后，欢迎提交 Issues 和 PRs。在此之前：必须通过 `make test && make lint`；CI 会 dogfood ActionsPlane 自身的规则（所有第三方 actions 均通过 SHA pin）。 ## 许可证 Apache-2.0 — 详见 [`LICENSE`](LICENSE)。

标签：DevSecOps, GitHub Actions, 上游代理, 子域名突变, 搜索引擎查询, 测试用例, 用户代理, 网络调试, 自动化, 自动笔记, 请求拦截, 运维, 逆向工具