dsh-github-publish

dsh-github-publish · 插件发布

把本地做好的 DSH 插件一键上传到 GitHub 仓库：自动初始化仓库、提交改动、按需建仓、推送，可选打标签并发布 Release。整个操作在 DSH 的图形界面里完成，不需要记 git 命令，也不需要 gh CLI。

• 界面位置：设置 → 插件发布
• 宿主半区（Node）：本地 git 操作 + GitHub REST 调用
• 浏览器半区（Web）：设置分区 UI，只通过本机 HTTP 与宿主通信，永远看不到令牌明文

---

目录

• 一分钟上手
• 安装
• 界面说明
• 一键上传做了什么
• GitHub 凭据
• 安全设计
• 设置项
• 目录结构
• 自检
• 故障排查
• 已知边界

---

一分钟上手

1. 安装本插件并重启 DSH（见下一节）。
2. 打开 设置 → 插件发布。
3. 在「GitHub 凭据」里粘贴一个 Personal Access Token，点「保存并验证」。令牌会被校验（读一次 /user）后存到本机。
4. 在「本地插件」里找到你的插件（默认自动发现 profile 中 link: 安装的插件与 node_modules 下的软链插件），点 一键上传。
5. 右侧/下方出现任务面板：准备 → 初始化仓库 → 提交 → 确认仓库 → 设置远端 → 推送 → 校验。完成后给出仓库链接。

没有令牌也能先点 预检：它只做只读检查（目录、git 状态、仓库是否存在），不写盘、不建仓、不推送。

---

安装

# 默认装官方桌面端 profile（%USERPROFILE%\.dsh\profiles\desktop）
pwsh -File install.ps1

# 指定 profile
pwsh -File install.ps1 -ProfileDir "D:\some\profile"

# 不用软链，直接拷贝一份（改了源码要重装才生效）
pwsh -File install.ps1 -Copy

脚本做两件事：在 <profile>\node_modules\dsh-github-publish 建一个指向本包目录的 junction，并把包名写进 <profile>\package.json 的 dependencies 与 dsh.profile.bundles。

如果系统禁止运行未签名脚本（about_Execution_Policies 报错），在命令前加一段进程级放行： Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force（只影响当前窗口，不改机器策略）。

装完必须重启 DSH 客户端：profile 未启用 HMR 时，新 bundle 只在启动时装载。

卸载：

pwsh -File uninstall.ps1              # 保留设置与令牌
pwsh -File uninstall.ps1 -PurgeData   # 连设置与令牌一起删

---

界面说明

---

一键上传做了什么

任何一个步骤失败都会：把该步骤标红、把错误与建议写进任务面板与日志文件，且不回滚已完成的本地工作（重试即可继续）。

---

GitHub 凭据

解析顺序（第一个命中者生效）：

1. 插件设置里保存的令牌 —— <DSH_HOME>\dsh-github-publish\token（0600）
2. 环境变量 GITHUB_TOKEN
3. 环境变量 GH_TOKEN
4. 系统凭据管理器：git credential fill（Git Credential Manager 已登录过 GitHub 时可直接复用；用 credential.interactive=false + GCM_INTERACTIVE=never 调用，任何情况下都不会弹出登录窗口；本机没有存凭据时会立刻返回“无令牌”，可用设置项关闭这条回退）
5. 都没有 —— 只能对已存在的仓库尝试推送，建仓一定会失败并提示配置令牌

需要什么权限

• classic token：勾选 repo（要发 Release / 写 topics 也在这个范围内）
• fine-grained token：Contents: Read and write；要自动建仓还需 Administration: Read and write，并授权目标账号/组织

令牌只用于两处：GitHub REST 调用（Authorization: Bearer …）与 git push（http.extraheader 一次性注入）。

---

安全设计

令牌

• 只在宿主进程内存里流转，接口与界面只返回掩码（ghp_…abcd）与来源；
• 推送时用环境变量 GIT_CONFIG_COUNT/GIT_CONFIG_KEY_0/GIT_CONFIG_VALUE_0 注入 HTTP 头，不进 argv、不写 .git/config，进程退出即消失；
• 带令牌的 git 调用（push / ls-remote / tags）与发布期间的每一次 git 调用都指向一个空 hooks 目录（<DSH_HOME>/dsh-github-publish/no-hooks）：仓库自带的 pre-push/pre-commit、仓库级 core.hooksPath 都不会执行（命令行 -c 优先级最高，实测压得住仓库本地配置）；
• git 子进程的环境会被剃掉机密：删除 GITHUB_TOKEN/GH_TOKEN 等常见变量名，并删除任何取值等于已登记令牌的变量——仓库里的 filter.*.clean、core.fsmonitor 这类"必然要执行"的程序即使跑了，也拿不到令牌；
• 所有写进日志/错误信息的文本都过 redact()：既抹当前令牌（含其 base64 形式），也按模式抹掉 任何 URL userinfo、ghp_/github_pat_ 形态、Authorization 头与 password= 行——origin 里残留的别的令牌同样不会被打印；
• 令牌单独存放（token 文件），删文件即撤销，不需要动设置；
• 自检里有专门断言：.git/config、.git 目录全量文件、发布日志、任务响应里都不允许出现令牌明文。

参数与远端安全

• branch / owner / repo 全部走白名单校验（lib/validate.js）：非法直接 400。git 会解析位置参数之后的选项，不做这层校验时 branch: "--mirror" 会变成真正的 --mirror（删远端引用）；
• 纵深防御：所有 refspec 都放在 -- 之后，git push origin -- <branch>、git fetch/ls-remote ... -- <branch>；
• 推送前清掉仓库里能"把带令牌的请求引到别处"的配置：remote.origin.pushurl / receivepack / uploadpack / proxy、http.proxy / https.proxy / http.sslVerify、core.gitProxy、url.*.insteadOf / pushInsteadOf（git remote set-url 只改 url，不会动 pushurl）；清掉哪些键会写进任务告警，清理失败直接中止推送；同样的中和也内建在 lib/git.js 的 push() 里，直接调用内层 API 同样受保护；
• 强制推送的预期值来自 git ls-remote 的实时 sha，并按 refs/heads/<branch> 精确比对（ls-remote 的 pattern 是后缀匹配，远端同时有 a/b 与 b 时取错行会让 lease 失真）；远端没有该分支时用「期望不存在」；换 origin 时会清掉旧的 refs/remotes/origin/*；
• GitHub API 只跟随同源重定向；跨主机或降级到 http:// 的重定向直接报错，不把 Bearer 令牌交出去。

发布行为

• 位于更大仓库内部的插件目录默认拒绝发布（否则 git add -A 会把整个仓库推上去），需要显式勾选「只发布这个子目录（在插件目录内单独 git init）」；
• 默认不做强制推送；开启后只覆盖「读取到的那个远端快照」（--force-with-lease=<branch>:<sha>）；
• 不删除远端任何内容，不做 push --delete，不 remote prune；
• git add -A 之后扫描将要提交的文件名，命中 .env、*.pem、id_rsa*、credentials* 等形态时在界面与日志里告警（默认可见性是 public，误推代价很大）；
• 默认 .gitignore 只忽略 node_modules/、*.log 与系统垃圾文件；dist/、build/ 不再被静默排除——发布的是成品，是否包含由你决定；
• 远端默认分支与本次推送分支不一致时给出提示（否则 GitHub 首页看起来"没更新"）；
• 每次发布的完整日志落在 <DSH_HOME>\dsh-github-publish\logs\publish-*.log。

Windows 说明：token/日志目录按 POSIX 权限位创建（0600 / 0700），但 Windows 上 Node 的 mode 不生效，实际保护来自用户目录 ACL。需要更强的保护请使用系统凭据管理器（本插件支持回退）或自行给目录收紧 ACL。

HTTP 接口（/dsh-github-publish/api/*）

1. 只接受回环地址（127.0.0.1/::1）连接，其余 403；
2. 必须带 x-dsh-github-publish: 1 自定义头 —— 跨站表单/图片请求无法伪造，跨源 fetch 会先触发预检，而本路由不返回任何 CORS 头；
3. 带 Origin 时必须与 Host 同源；
4. 只接受 application/json，请求体上限 256 KB（超出回 413），响应一律 no-store。

---

设置项

保存在 <DSH_HOME>\dsh-github-publish\settings.json。

环境变量覆盖（不会写进磁盘，适合企业部署与自检）：

DSH_GITHUB_PUBLISH_API_BASE=http://127.0.0.1:8080   # GitHub API 基址
DSH_GITHUB_PUBLISH_REMOTE_BASE=https://ghe.corp     # 远端基址
DSH_GITHUB_PUBLISH_OWNER=some-org                   # 默认 owner
DSH_GITHUB_PUBLISH_NO_CREDENTIAL_HELPER=1           # 禁止回退系统凭据管理器

---

目录结构

dsh-github-publish/
  package.json          dsh.bundle.patch + dsh.client 声明
  cordis.patch.yml      插入 profile 配置树的挂载声明
  lib/
    index.js            宿主半区入口：HTTP 路由、请求防护、状态与发现接口
    publish.js          一键发布流水线（job/步骤/日志/失败提示）
    discover.js         插件发现（link: 依赖、node_modules 软链、扫描根、手动目录）
    git.js              git 调用封装（非交互、有界输出、一次性鉴权头）
    github.js           GitHub REST 客户端（零依赖 node:https）
    credentials.js      令牌解析（设置 → 环境变量 → git credential）与脱敏
    validate.js         分支/账号/仓库名白名单校验 + 机密文件名识别
    settings.js         路径推导、设置读写、令牌文件（0600）
    client.js           浏览器半区成品 bundle（设置分区 UI，手写无编译）
  test/
    harness.mjs         宿主半区端到端自检（假 GitHub + 本地裸仓库）
    client-smoke.mjs    浏览器半区冒烟测试（真 React + jsdom）
  install.ps1 / uninstall.ps1

依赖：只用 Node 内置模块（node:http(s)、node:child_process、node:fs…），零运行时依赖；浏览器半区只 require('react')（DSH 的 PLATFORM_MODULES 提供），无需构建步骤。

---

自检

宿主半区端到端（不需要真实 GitHub，会起一个假 REST 服务 + 本地裸仓库，并断言令牌不落盘）：

node test\harness.mjs          # 130 项断言
node test\harness.mjs --keep   # 保留临时目录便于排查

覆盖：环境状态、请求防护（缺头/错误 Content-Type/超大请求体）、无令牌失败路径、令牌保存/校验/清除、插件发现、预检不写盘、首次发布全链路（建仓+提交+推送+校验）、幂等二次发布、沿用既有 origin、远端分叉（拒绝→强制覆盖）、陈旧跟踪引用下的强制推送、嵌套仓库防护、设置持久化、并发 409 与取消、参数注入防护（--mirror/--dry-run/非法 owner 与仓库名）、远端校验不一致判失败、机密文件告警、钩子隔离（A/B 对照）、pushurl/insteadOf/http.proxy 重定向防护、a/b 与 b 同名后缀下的 lease 精确匹配、仓库级 filter.clean 环境脱敏、内层 push() 防护、脱敏与校验函数单测。

浏览器半区冒烟（真 React 18 + jsdom 渲染整个面板并点击按钮）：

# 一次性装上测试期依赖（不进插件包）
npm i --prefix ..\..\.testdeps react@18.3.1 react-dom@18.3.1 jsdom@24.1.3
node test\client-smoke.mjs     # 44 项断言

npm 默认缓存目录不可写时（EPERM: ...\_cacache），加 --cache ..\..\.npm-cache 指定一个工作区内的缓存目录。

---

故障排查

---

已知边界

• 一个插件一个仓库：<owner>/<repo> 由模板决定，不做 monorepo 子目录推送（需要的场景可以用「扫描根目录 + 手动目录」分别发布）。
• 不发 Release 资产：只创建标签与 Release 记录，不上传构建产物。
• 不建组织：组织必须已存在且令牌有建仓权限。
• 不做 submodule / subtree / LFS 特殊处理：按普通 Git 仓库推送；.gitattributes 里的 LFS 规则由本机 git-lfs 处理。
• 只服务本机回环：接口有意不接受非回环请求，即使 DSH 的 web server 绑定了 0.0.0.0。
• 不做自动重试与后台队列：一次点击一个任务（同一目录同时只允许一个任务，路径按 realpath 归一化比较，重复点击返回 409），失败后由人决定是否重试（可强制覆盖或取消）。
• 接口只防浏览器不防本机进程：回环 + 自定义头挡得住跨站请求，但本机任何进程都能调用这套 API（它本来就是本机工具）；因此参数校验与 -- 隔离是硬要求，而不是可选项。
• --force-with-lease 只保护「读到的那一刻」：读取远端 sha 与推送之间仍有极小窗口，中间人推送会被拒绝而不是被覆盖（这是设计取向）。