assembly-automation-hub/repo-governance

## 目录 - [标题与描述](#yml_helper) - [功能](#features) - [技术栈与架构](#tech-stack--architecture) - [核心技术栈](#core-stack) - [项目结构](#project-structure) - [各 YAML 文件的作用](#what-each-yaml-file-does) - [关键设计决策](#key-design-decisions) - [快速开始](#getting-started) - [前置条件](#prerequisites) - [安装](#installation) - [测试](#testing) - [部署](#deployment) - [使用](#usage) - [配置](#configuration) - [GitHub Actions Secrets](#github-actions-secrets) - [Workflow 触发器与输入](#workflow-triggers-and-inputs) - [赞助元数据](#funding-metadata) - [Issue 模板配置](#issue-template-configuration) - [License](#license) - [联系方式与社区支持](#contacts--community-support) ## 功能 - 以可审计的 YAML 清单形式，集中管理日志库项目的 GitHub 仓库自动化。 - 通过针对 Python 和 GitHub Actions 生态系统的计划内 `Dependabot` 更新，强制执行依赖项规范。 - 自动批准并合并安全的 `Dependabot` 补丁及次要版本升级，以减少维护开销。 - 运行面向 lint 的 pull request 检查，包括 Node.js 引导、可选的 package-lock 生成以及 JavaScript 语法验证。 - 针对JavaScript 和 TypeScript 的攻击面分析，执行计划性和按需的 `CodeQL` SAST 扫描。 - 提供一个 AI 辅助的 issue 生成 workflow，能够检查 push 和 pull request 并执行 Python 分析入口点。 - 通过结构化的 bug 报告和 feature request 表单，标准化 issue 收集流程。 - 提供一个可复用的 pull request 模板，用于捕捉变更类型、验证步骤和审查规范。 - 通过兼容 GitHub Sponsors 的元数据发布维护者赞助渠道。 - 保持仓库操作具有声明性、可审查性，并易于 fork 或移植到其他与日志相关的项目中。 ## 技术栈与架构 ### 核心技术栈 - `YAML`：GitHub Actions workflow、issue 表单、赞助配置和依赖自动化的主要配置语言。 - `Markdown`：面向人类的项目文档和 pull request 模板内容。 - `GitHub Actions`：CI/CD 编排与策略执行引擎。 - `Node.js 20`：被 lint workflow 用于安装依赖并运行可选的 lint 或语法检查。 - `Python 3.11`：被 AI 分析 workflow 用于在 GitHub 事件上下文中执行 `trigger action/trigger_action.py`。 - `CodeQL`：用于 JavaScript/TypeScript 分析的静态应用安全测试 (SAST) 引擎。 - `Dependabot`：用于包和 GitHub Action 依赖漂移的自动化更新管理。 ### 项目结构 ``` . ├── .github/ │ ├── FUNDING.yml │ ├── dependabot.yml │ ├── pull_request_template.md │ ├── ISSUE_TEMPLATE/ │ │ ├── bug_report.yml │ │ └── feature_request.yml │ └── workflows/ │ ├── ai-issue.yml │ ├── dependabot-auto-merge.yml │ ├── lint.yml │ └── sast.yml ├── LICENSE ├── README.md └── trigger action/ └── trigger_action.py ``` ### 各 YAML 文件的作用 该代码库规模很小，因此每个 YAML 文件都有特定的操作角色： | 文件 | 目的 | 操作影响 | | --- | --- | --- | | `.github/FUNDING.yml` | 声明 GitHub 认可的赞助平台和自定义捐赠链接。 | 在仓库 UI 中展示支持链接，并集中管理维护者的赞助元数据。 | | `.github/dependabot.yml` | 配置针对 `pip` 和 `github-actions` 的每周更新扫描。 | 防止 Python 依赖项和 workflow action 版本发生漂移或遗漏安全补丁。 | | `.github/workflows/ai-issue.yml` | 在向 `main` 分支 `push` 及选定的 pull request 事件上运行 AI 辅助的分析流水线。 | 安装 Python 依赖项，注入 GitHub 事件元数据，并执行 `trigger action/trigger_action.py` 以创建或丰富 issue。 | | `.github/workflows/dependabot-auto-merge.yml` | 审查由 `dependabot[bot]` 开启的 pull request。 | 自动批准并为安全的补丁/次要依赖项更新启用合并自动化。 | | `.github/workflows/lint.yml` | 执行 pull request lint 和静态验证。 | 引导 Node.js，在缺失时创建 `package-lock.json`，可选择运行仓库 lint 脚本，并验证 `api/` 下的 JavaScript 语法。 | | `.github/workflows/sast.yml` | 执行 `CodeQL` 静态分析。 | 在 PR、手动调度和每周计划任务中扫描 JavaScript/TypeScript 代码，以呈现安全发现。 | | `.github/ISSUE_TEMPLATE/bug_report.yml` | 结构化的 bug 报告表单。 | 强制要求提供复现细节、预期行为、实际堆栈追踪和环境上下文。 | | `.github/ISSUE_TEMPLATE/feature_request.yml` | 结构化的 feature 提案表单。 | 捕捉问题上下文、建议的解决方案和替代方案，用于路线图筛选。 | ### 关键设计决策 1. `优先使用 GitHub 原生自动化而非自定义基础设施` - 该项目依赖于内置的 GitHub 原语，例如 Actions、issue 表单、计划内 workflow、仓库赞助和 PR 模板。 - 这使得操作层面尽可能精简，并避免了维护独立的 CI 编排器。 2. `策略即代码` - 维护行为被编码在版本控制的 YAML 中，而不是隐式的仓库设置中。 - 每个 workflow 的更改都可以像应用程序代码一样进行审查、对比和审计。 3. `关注点分离` - 依赖更新、安全扫描、lint 和 AI 辅助分类各自存在于独立的 workflow 文件中。 - 这提高了可调试性，并减少了维护任务之间的意外耦合。 4. `安全默认的自动化` - 自动合并仅限于非破坏性的 `Dependabot` 补丁/次要版本更新。 - 高风险更改仍需人工审查。 5. `混合 runtime 支持` - 该仓库同时考虑了以 Python 为中心的自动化（`trigger action/trigger_action.py`）以及 JavaScript/TypeScript 代码的扫描/lint。 - 对于可能会跨多个 runtime 暴露 SDK、CLI、仪表板或集成的日志项目来说，这是一种实用的设计。 #### Workflow 拓扑 ``` flowchart TD A[Developer Push / Pull Request] --> B[GitHub Actions Triggers] B --> C[Lint Workflow] B --> D[CodeQL SAST Workflow] B --> E[AI Issue Workflow] F[Dependabot Update] --> G[Dependabot Metadata] G --> H[Auto-Approve Safe Updates] H --> I[Enable Auto-Merge] C --> J[Node.js Setup and Validation] D --> K[Security Findings] E --> L[Python Analysis Entry Point] L --> M[Generated or Enriched Issues] ``` #### 日志库交付上下文 ``` sequenceDiagram participant Dev as Maintainer participant GH as GitHub participant CI as Actions Runner participant Sec as CodeQL participant Bot as Dependabot Dev->>GH: Open pull request GH->>CI: Trigger lint.yml GH->>Sec: Trigger sast.yml Sec-->>GH: Upload security results CI-->>GH: Publish validation status Bot->>GH: Open dependency PR GH->>CI: Trigger dependabot-auto-merge.yml CI-->>GH: Approve and enable auto-merge when safe ``` ## 快速开始 ### 前置条件 要在本地使用此仓库，您应该具备： - `git`，用于克隆和版本控制操作。 - `Node.js 20` 和 `npm`，用于在本地模拟 lint workflow。 - `Python 3.11` 和 `pip`，用于模拟 AI workflow 的依赖安装。 - 一个启用了 Actions 的 GitHub 仓库（如果您希望 workflow 端到端执行）。 - 可选：`gh` CLI，用于测试 Dependabot 自动化使用的 PR 审查或合并命令。 ### 安装 1. 克隆该仓库。 2. 进入项目目录。 3. 安装本地 workflow 模拟所需的运行时依赖。 ``` git clone cd yml_helper npm install --no-audit --no-fund pip install PyGithub requests ``` 如果您的日志库位于单独的仓库中，请将 `.github/` 目录复制或作为第三方依赖放入该项目中，然后根据实际的代码布局调整 workflow 假设。 ## 测试 该仓库目前不提供应用程序测试套件。验证主要以配置和 workflow 为导向。 ### 推荐的本地检查 ``` # Markdown 和仓库维护 cat README.md # 当 yq 可用时验证 YAML 语法 yq '.' .github/dependabot.yml > /dev/null yq '.' .github/FUNDING.yml > /dev/null yq '.' .github/workflows/ai-issue.yml > /dev/null yq '.' .github/workflows/dependabot-auto-merge.yml > /dev/null yq '.' .github/workflows/lint.yml > /dev/null yq '.' .github/workflows/sast.yml > /dev/null yq '.' .github/ISSUE_TEMPLATE/bug_report.yml > /dev/null yq '.' .github/ISSUE_TEMPLATE/feature_request.yml > /dev/null # 重现基于 Node 的 lint 工作流行为 npm install --no-audit --no-fund npm run lint --if-present # 如果存在 api/ 目录，则验证 JavaScript 语法 find api -type f -name '*.js' -print0 | xargs -0 -I{} node --check "{}" ``` ### GitHub 端检查 - 打开一个 pull request 以触发 `lint.yml` 和 `sast.yml`。 - 使用 `workflow_dispatch` 手动执行 `lint.yml` 或 `sast.yml`。 - 打开一个测试性的 `Dependabot` PR 或修改 `dependabot.yml` 计划以验证更新自动化。 - 向 `main` 分支 push 或打开一个 pull request，以使用 `trigger action/trigger_action.py` 验证 `ai-issue.yml`。 ## 部署 对于此仓库，“部署”意味着将 workflow 和治理更改推广到日志库使用的 GitHub 仓库中。 ### 生产发布模型 1. 将 workflow 更改合并到默认分支。 2. 在启用依赖于它们的 workflow 之前，确保已填充仓库 secrets。 3. 确认 GitHub Actions 权限与 workflow 声明一致。 4. 观察首次计划内或手动调度的运行，检查是否存在权限和路径不匹配的情况。 ### CI/CD 集成指南 - 将 `.github/workflows/*.yml` 视为生产基础设施代码。 - 要求对 workflow 更改进行 pull request 审查。 - 使用受保护分支，以便自动合并仅在所需检查成功后运行。 - 保持启用 CodeQL 计划任务，以进行基线安全漂移检测。 - 将 workflow 逻辑与日志库代码一起进行版本控制，以便发布分支继承正确的自动化姿态。 ### 容器化 当前的仓库快照中不包含 Dockerfile 或 Compose stack。如果您的日志库在其他地方进行了容器化，请将此 `.github/` 配置挂载或复制到该源码仓库中，而不是尝试将此仓库作为独立服务进行“部署”。 ## 使用 由于该项目是自动化优先的，因此其使用主要是操作性的，而非 API 驱动的。 ### 示例：在日志库仓库中采用 workflow 集合 ``` # 克隆你的日志库仓库 cd /path/to/logging-library # 将自动化资源复制到目标仓库 cp -R /path/to/yml_helper/.github . cp /path/to/yml_helper/README.md ./docs/repo-automation.md ``` ### 示例：自定义 Dependabot 计划 ``` version: 2 updates: - package-ecosystem: "pip" directory: "/" schedule: interval: "daily" # Increase scan frequency for security-sensitive projects labels: - "dependencies" - "python" ``` ### 示例：调用 AI workflow 前置条件 ``` # 安装 ai-issue.yml 所需的 Python 依赖 pip install PyGithub requests # 提供在 GitHub Actions 中使用的相同环境变量 export GITHUB_TOKEN="" export REPOSITORY="owner/repo" export EVENT_NAME="pull_request" export COMMIT_SHA="" export PR_NUMBER="123" export GH_MODELS_TOKEN="" export ALLOWED_USER="" # 运行分析入口点 python "trigger action/trigger_action.py" ``` ### 示例：lint workflow 行为 ``` # 在本地镜像 GitHub Actions lint 作业 npm install --no-audit --no-fund npm run lint --if-present # 当仓库包含 api/ 目录时验证 JavaScript 文件 if [ -d api ]; then find api -type f -name '*.js' -print0 | xargs -0 -I{} node --check "{}" fi ``` ## 配置 ### GitHub Actions Secrets 该仓库引用了以下 secrets 和环境变量： | 名称 | 被需求于 | 目的 | | --- | --- | --- | | `GITHUB_TOKEN` | 多个 workflow | 使用仓库范围的 token 对 GitHub API 和 CLI 操作进行身份验证。 | | `GH_MODELS_TOKEN` | `ai-issue.yml` | 为 `trigger action/trigger_action.py` 使用的 AI 模型提供商提供凭证。 | | `ALLOWED_USER` | `ai-issue.yml` | 限制或验证哪些执行者可以使用 AI 辅助的 workflow 行为。 | | `REPOSITORY` | `ai-issue.yml` | 将当前的 `owner/name` 仓库标识符传递给 Python 入口点。 | | `EVENT_NAME` | `ai-issue.yml` | 提供正在处理的 GitHub 事件类型。 | | `COMMIT_SHA` | `ai-issue.yml` | 提供正在分析的 commit。 | | `PR_NUMBER` | `ai-issue.yml` | 在可用时提供 pull request 编号。 | | `GH_TOKEN` | `dependabot-auto-merge.yml` | 对 `gh pr review` 和 `gh pr merge` 操作进行身份验证。 | ### Workflow 触发器与输入 | Workflow | 触发器 | 关键运行时假设 | | --- | --- | --- | | `ai-issue.yml` | 向 `main` 分支 `push`；PR 事件 `opened`、`synchronize`、`labeled` | 需要 `trigger action/trigger_action.py`、Python 3.11、GitHub 和模型 token。 | | `dependabot-auto-merge.yml` | Dependabot PR 的 `opened`、`reopened`、`synchronize`、`ready_for_review` 事件 | 需要 runner 上安装有 `gh` CLI 以及写入 PR 元数据的权限。 | | `lint.yml` | 任何 pull request；手动调度 | 假定仓库支持 Node并且具有可选的 `api/` 目录。 | | `sast.yml` | 任何 pull request；手动调度；每周一的定时任务 (cron) | 假定存在可供 CodeQL 分析的 JavaScript/TypeScript 代码。 | ### 赞助元数据 `.github/FUNDING.yml` 目前公布以下支持渠道： - `GitHub Sponsors`: `OstinUA` - `Patreon`: `OstinFCT` - `Ko-fi`: `fctostin` - `Boosty`: 自定义 URL - `Telegram`: 自定义 URL - `YouTube`: 自定义 URL ### Issue 模板配置 这些 issue 表单具有明确的导向，对提升运营成熟度非常有用： - `bug_report.yml` 强调重复检查、准确的环境细节、可复现的步骤、预期行为和堆栈追踪捕捉。 - `feature_request.yml` 强调问题框架、建议的解决方案描述以及替代方案。 ## 许可证 该仓库采用 Apache License 2.0 授权。完整文本请参见 [`LICENSE`](LICENSE)。 ## 联系方式与社区支持 ## 支持该项目 [](https://www.patreon.com/OstinFCT) [](https://ko-fi.com/fctostin) [](https://boosty.to/ostinfct) [](https://www.youtube.com/@FCT-Ostin) [](https://t.me/FCTostin) 如果您觉得此工具有用，请考虑在 GitHub 上点 star，或直接支持作者。

标签：CI/CD, DevOps, GitHub Actions, 代码治理, 依赖管理, 自动笔记, 静态代码扫描