From 93e86fc82215198387f2811e593f42053afa24dc Mon Sep 17 00:00:00 2001 From: sciman-top Date: Sun, 25 Oct 2026 12:57:20 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E6=9E=84=E4=B8=AD=E8=8B=B1?= =?UTF-8?q?=E5=8F=8C=E8=AF=AD=20README=20=E5=B9=B6=E4=BC=98=E5=8C=96=20Git?= =?UTF-8?q?Hub=20=E9=A1=B9=E7=9B=AE=E5=AE=9A=E4=BD=8D=E4=B8=8E=E7=89=B9?= =?UTF-8?q?=E6=80=A7=E5=B1=95=E7=8E=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.en.md | 336 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 335 +++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 616 insertions(+), 55 deletions(-) create mode 100644 README.en.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..ef54d17 --- /dev/null +++ b/README.en.md @@ -0,0 +1,336 @@ +# GitHub Toolkit + +

+ 🛡 Production-Ready GitHub Fork Safety Maintenance & Release Asset Synchronization Toolkit
+ Zero external dependencies · Defense-in-depth safety guardrails · Automatic restore points · Release asset mirroring & smart latest.json rewriting +

+ +

+ CI Status + Python 3.11+ + Zero Dependencies + GitHub CLI + Unit Tests +

+ +

+ 简䜓䞭文 | English +

+ +--- + +## Why GitHub Toolkit? + +When maintaining open-source forks for internal customizations, security hardening, custom CI builds, or domestic network mirrors, developers and platform teams frequently encounter critical challenges: + +- **GitHub's native "Sync fork" lacks safety guardrails**: GitHub's web UI blindly executes a merge. If upstream gets wiped, compromised, or mistakenly deletes core directories (e.g., `.github/`, `README`, or `LICENSE`), native sync propagates the disaster directly into your fork, destroying your customizations. +- **No recovery checkpoint**: Native synchronization directly overwrites the default branch without creating a backup, leaving recovery dependent on searching through Git reflogs. +- **Release assets are completely left behind**: Git only synchronizes code commits, never GitHub Releases. When upstream publishes new installer packages (`.exe`, `.dmg`, `.tar.gz`, `.deb`), your fork's releases remain empty. Client auto-updaters relying on `latest.json` continue pointing to upstream URLs instead of your mirror. +- **Third-party Marketplace Actions carry severe supply-chain risks**: Most community fork-sync actions require personal access tokens (PAT) with broad repository write permissions, exposing organizations to credential leakage and supply chain attacks. + +**GitHub Toolkit** is engineered to eliminate these pain points. Built with 100% Python standard library and the official GitHub CLI (`gh`), it delivers defense-in-depth safety circuit breakers, full-batch non-mutating preflight checks, automated moving restore points (`backup/pre-sync`), release asset mirroring, and smart `latest.json` URL rewriting with checksum manifest synchronization. + +--- + +## Feature Comparison Matrix + +| Feature | GitHub Web "Sync fork" | Community Marketplace Actions | GitHub Toolkit | +| :--- | :---: | :---: | :---: | +| **Batch Multi-Fork Discovery** | ❌ Manual click per repo | ❌ Configured per repo | ✅ **Automatic concurrent account discovery** | +| **Upstream Wipeout Protection** | ❌ Blind merge | ❌ None | ✅ **Immediate abort if files drop < 50%** | +| **Mass-Deletion Protection** | ❌ Uncapped | ❌ Uncapped | ✅ **Dynamic deletion budget ceiling** | +| **Critical Path Deletion Guard** | ❌ None | ❌ None | ✅ **Guards `.github/`, `README`, `LICENSE`** | +| **API Truncation Guard** | ❌ None | ❌ None | ✅ **Aborts on 300-entry compare payload** | +| **Automatic Restore Checkpoint** | ❌ None | ❌ None | ✅ **Refreshes `backup/pre-sync` before write** | +| **Full-Batch Preflight Validation** | ❌ None | ❌ None | ✅ **Any failure halts the entire batch** | +| **Release Asset Mirroring** | ❌ None | ❌ None | ✅ **Mirrors binaries, signatures & manifests** | +| **`latest.json` URL Rewriting** | ❌ None | ❌ None | ✅ **Rewrites download URLs to fork domain** | +| **Checksum Manifest Recalculation** | ❌ None | ❌ None | ✅ **Recalculates SHA256/512 and uploads bundle** | +| **Proven Mirror Asset Pruning** | ❌ None | ❌ None | ✅ **Safely prunes old mirrors, retains custom assets** | +| **Supply Chain Safety** | Official GitHub feature | Untrusted 3rd-party images/scripts | ✅ **100% Python stdlib + official `gh` CLI** | + +--- + +## Safe Sync Pipeline Architecture + +Every default branch synchronization strictly follows a six-stage defensive pipeline: + +```text + ┌────────────────────────────────────────────────────────┐ + │ 1. Fresh Runtime Discovery │ + │ Fetches forks, upstreams, and default branches live │ + └──────────────────────────┬─────────────────────────────┘ + │ + ┌──────────────────────────▌─────────────────────────────┐ + │ 2. Full-Batch Preflight Check │ + │ Simulates all safety checks before any writes start │ + └──────────────────────────┬─────────────────────────────┘ + │ + ┌──────────────────────────▌─────────────────────────────┐ + │ 3. Defense-in-Depth Safety Guardrails │ + │ • Upstream file count < 50% of fork ➔ Safety abort │ + │ • Deletions > dynamic budget (5 + files/10) ➔ Abort │ + │ • Deletion of .github/, README, LICENSE ➔ Abort │ + │ • Compare diff reaches 300 entries ➔ Truncate abort │ + └──────────────────────────┬─────────────────────────────┘ + │ + ┌──────────────────────────▌─────────────────────────────┐ + │ 4. Moving Restore Point Checkpoint │ + │ Forces backup/pre-sync branch to current fork HEAD │ + └──────────────────────────┬─────────────────────────────┘ + │ + ┌──────────────────────────▌─────────────────────────────┐ + │ 5. Merge Upstream & Convergence Verification │ + │ Calls merge-upstream, re-checks behind_by == 0 │ + └──────────────────────────┬─────────────────────────────┘ + │ + ┌──────────────────────────▌─────────────────────────────┐ + │ 6. Release Asset Convergence │ + │ Mirrors binaries, rewrites latest.json, updates │ + │ checksums, and safely prunes proven mirror assets │ + └────────────────────────────────────────────────────────┘ +``` + +--- + +## 30-Second Quick Start + +### 1. Prerequisites + +Requires Python 3.11+ and the official [GitHub CLI (`gh`)](https://cli.github.com/): + +```powershell +# Windows users can install via winget +winget install --id GitHub.cli --source winget + +# Authenticate GitHub account +gh auth login +``` + +> **Credential Precedence**: In CI/automation environments, `GH_TOKEN` takes precedence over `GITHUB_TOKEN`. For local interactive use, the CLI transparently uses your `gh auth login` keychain. Tokens are never logged or stored in plain text. + +### 2. Essential Commands + +#### ① List All Fork Repositories and Status (Read-Only) + +```powershell +# Format output as clean console table +python list-forks.py + +# Output structured JSON (for automation pipelines or dashboards) +python list-forks.py --json +``` + +Example output: + +```text +Fork repos for your-name (3 total): + +Discovery: live_github_api /user/repos at 2026-10-25T12:00:00Z (repos=12, forks=3) + +Repository Branch Upstream Behind Workflow +------------------------------------------------------------------------------------------------------- +my-awesome-fork main upstream-org/my-awesome-fork 2 Installed +devtools-mirror master original/devtools-mirror 0 Missing +cockpit-custom main cockpit-project/cockpit Unknown Installed +``` + +#### ② Dry-Run Preview + +Always preview planned changes before applying real writes: + +```powershell +# Preview sync for all forks in the account +python sync-forks.py --dry-run + +# Preview sync for a single repository +python sync-forks.py my-awesome-fork --dry-run +``` + +#### ③ Execute Safe Synchronization + +```powershell +# Synchronize all forks +python sync-forks.py + +# Synchronize specific forks (accepts repo-name or owner/repo-name) +python sync-forks.py my-awesome-fork other-owner/another-fork +``` + +#### ④ Batch Install or Update Sync Workflows + +Deploy or non-destructively upgrade managed `sync-fork.yml` workflows across all forks: + +```powershell +# Preview workflow changes +python sync-forks.py --add-workflow --dry-run + +# Apply workflow installation +python sync-forks.py --add-workflow +``` + +#### â‘€ Audit Scheduled Workflow Readiness & Secrets + +```powershell +python sync-forks.py --verify-schedule +``` + +#### ⑥ Mirror and Reconcile Release Assets + +```powershell +# Audit release mirror differences (read-only) +python sync-forks.py --verify-releases + +# Dry-run asset reconciliation +python sync-forks.py --sync-releases --dry-run + +# Apply release synchronization +python sync-forks.py --sync-releases my-awesome-fork +``` + +--- + +## Command-Line Reference + +### 1. `list-forks.py` + +| Flag | Description | +| :--- | :--- | +| *(none)* | Print table of all account forks, upstream delta, and workflow status | +| `--json` | Emit machine-readable JSON including auth principal, discovery metadata, and per-repo rows | +| `-h, --help` | Display command help | + +> **Strict State Integrity**: When API limits or permissions prevent verification, the tool reports `Unknown` with precise error diagnostics rather than falsely claiming `Missing`. + +### 2. `sync-forks.py` + +| Option / Flag | Category | Description | +| :--- | :---: | :--- | +| `[repo-name ...]` | Target Selection | Specify one or more repositories (`repo` or `owner/repo`), deduplicated preserving order; omit to target all forks | +| `--dry-run` | Simulation | Execute all real API discovery and safety checks without modifying GitHub state | +| `--add-workflow` | Workflow Deployment | Create or update `.github/workflows/sync-fork.yml` across targeted forks | +| `--verify-schedule` | Audit | Verify workflow installation, `SYNC_PAT` secret presence, and scheduled run histories | +| `--verify-releases` | Audit | Compare upstream vs fork stable release assets and retention policies | +| `--sync-releases` | Reconciliation | Mirror stable binaries, rewrite `latest.json`, and prune proven old mirror assets | +| `--force` | Force Override | Bypass safety checks or force workflow rewrite (requires explicit confirmation env var) | +| `--json` | Output Control | Emit detailed JSON report with run summary, preflight status, and per-repo results | +| `-h, --help` | Help | Display CLI help and examples | + +### 3. Force Write Acknowledgement (`--force`) + +To prevent catastrophic accidental writes, real mutating runs using `--force` require explicit environment acknowledgement: + +```powershell +# PowerShell +$env:SYNC_FORKS_FORCE_ACK = "I_UNDERSTAND" +python sync-forks.py --force + +# Windows CMD +set SYNC_FORKS_FORCE_ACK=I_UNDERSTAND +python sync-forks.py --force + +# Linux / macOS Bash +SYNC_FORKS_FORCE_ACK=I_UNDERSTAND python3 sync-forks.py --force +``` + +### 4. Exit Code Contract + +Scripts strictly adhere to deterministic exit codes for reliable CI/CD pipeline integration: + +- `0`: Operation succeeded, or no changes required. +- `1`: CLI unavailable, invalid credentials, GitHub API error, or CLI argument syntax error; also returned if `list-forks.py` encountered incomplete repo checks. +- `3`: Safety circuit breaker triggered, or read-only audit discovered pending actions requiring manual or mutating follow-up. + +--- + +## Release Asset Synchronization & Rewriting + +Modern desktop applications (e.g., built with Tauri or Electron) rely on GitHub Releases for binary distribution and automatic updates. Standard Git forks only sync code branches, leaving release mirrors empty. + +`--sync-releases` provides a complete, automated mirroring solution: + +```text +Upstream Release (v1.2.0) Fork Release (v1.2.0) + ├── app-setup.exe ─── Mirror ──────► ├── app-setup.exe + ├── app-setup.dmg ─── Mirror ──────► ├── app-setup.dmg + ├── latest.json ─── Rewrite ─────► ├── latest.json (URL rewritten to Fork repository) + └── SHA256SUMS.txt ─── Recalculate ─► └── SHA256SUMS.txt (Manifest updated with new hash) +``` + +1. **Whitelisted Asset Matching**: Matches binary installers (`.exe`, `.msi`, `.deb`, `.rpm`, `.appimage`, `.dmg`, `.pkg`, `.zip`, `.tar.gz`), signatures (`.sig`, `.minisig`), and checksum manifests (`sha256sums*`, `sha512sums*`, `latest.json`). +2. **`latest.json` URL Rewriting**: Automatically rewrites upstream release download URLs to point to your fork repository. +3. **Manifest Recalculation**: Automatically updates `SHA256SUMS.txt` or `SHA512SUMS.txt` with the newly computed digest for `latest.json`. +4. **Atomic Bundle Upload**: Uploads `latest.json` and checksum manifests together to avoid windowed verification failures. +5. **Asset Name Sanitation**: Rejects unsafe names containing path separators (`/`, `\`), NUL bytes (`\0`), directory traversal (`..`), or leading flag hyphens (`-`). +6. **Safe Mirror Pruning**: Prunes only assets rigorously proven to be upstream mirrors (matching name + digest or name + size). **Custom tags and user-uploaded fork assets are never touched.** + +--- + +## GitHub Actions Automated Operations + +The repository includes three complementary GitHub Actions workflows: + +- **`ci.yml`**: Runs all 58 unit tests on push and pull requests in < 0.1s. +- **`auto-setup-forks.yml`**: Runs weekly on Sunday and on template updates to automatically deploy `sync-fork.yml` to all current and newly created forks. +- **`integration-api-smoke.yml`**: Runs weekly on Monday using dedicated read-only credentials to verify live GitHub API compatibility. + +### Repository Secrets Configuration + +Configure these repository secrets for automated maintenance: + +| Secret Name | Required | Description | +| :--- | :---: | :--- | +| `SYNC_PAT` | Yes | Personal Access Token with `repo` and `workflow` scopes, used to commit workflow files and synchronize forks | +| `INTEGRATION_GH_TOKEN` | Optional | Dedicated read-only token for API smoke testing | +| `INTEGRATION_EXPECTED_LOGIN` | Optional | Guard against token principal mismatches | +| `INTEGRATION_TARGET_REPO` | Optional | Specific target fork repository name for dry-run smoke checks | + +--- + +## Disaster Recovery & Rollback Guide + +If an upstream repository suffered corruption that bypassed safety rules (or if `--force` was used), restore your fork within seconds: + +```bash +# 1. Navigate to your local fork directory +cd path/to/your-fork + +# 2. Fetch the automatic backup checkpoint branch +git fetch origin backup/pre-sync + +# 3. Inspect commits in the backup branch +git log -n 5 origin/backup/pre-sync + +# 4. Reset default branch to pre-sync state +git checkout main +git reset --hard origin/backup/pre-sync + +# 5. Force-push to restore remote fork state +git push origin main --force +``` + +--- + +## Development & Testing + +Run the full unit test suite locally (zero third-party dependencies, runs in ~0.08s): + +```powershell +python -m unittest -q test_toolkit.py +``` + +Test coverage highlights: +- GitHub CLI detection and timeout error classification +- Credential resolution and concurrent upstream parent discovery +- Workflow template rendering and drift detection +- 50% file drop, deletion volume limit, and critical file deletion circuit breakers +- Compare 300-entry API truncation protection and moving restore point updates +- Force confirmation environment variable enforcement +- Release asset filtering, URL rewriting, and checksum recalculation +- Mirror provenance validation and safe asset pruning boundaries + +--- + +## License + +Distributed under the [MIT License](https://opensource.org/licenses/MIT). Issues and Pull Requests are warmly welcome! diff --git a/README.md b/README.md index aed28cc..cd8ebec 100644 --- a/README.md +++ b/README.md @@ -1,110 +1,335 @@ # GitHub Toolkit -䞀䞪䟝赖 Python 标准库䞎 GitHub CLI 的 fork 绎技工具。它只做䞉件事 +

+ 🛡 生产级 GitHub Fork 安党绎技䞎 Release 资产自劚化同步套件
+ 零第䞉方䟝赖 · 纵深防埡安党熔断 · 自劚创建恢倍点 · Release 资产镜像䞎 latest.json 智胜改写 +

+ +

+ CI Status + Python 3.11+ + Zero Dependencies + GitHub CLI + Unit Tests +

+ +

+ 简䜓䞭文 | English +

+ +--- + +## 䞺什么需芁 GitHub Toolkit + +圚日垞匀发䞎䌁䞚基础讟斜绎技䞭我们经垞需芁 Fork 匀源项目甚于内郚定制、安党加固、定制构建或提䟛眑络镜像。然而绎技数十䞪 Fork 埀埀面䞎重重痛点 + +- **GitHub 原生眑页同步Sync Fork隐患极倧**官方 Web UI 是盲目合并。若䞊枞仓库遭遇恶意枅空Wipe、恶意掚送到默讀分支、意倖误删文件劂删陀了 `.github/`、`README` 或 `LICENSE`原生同步䌚盎接将灟隟同步至䜠的 Fork毁掉所有积环。 +- **猺乏版本恢倍保障**原生合并盎接芆盖默讀分支䞀旊出问题只胜圚 reflog 䞭倧海捞针。 +- **Release 二进制资产完党䞍同步**Git 只同步代码提亀䞍䌚同步 Releases。䞊枞发垃了最新的 `.exe`、`.dmg`、`.tar.gz` 等安装包䜠的 Fork Release 䟝然空空劂也客户端自劚曎新䟝赖的 `latest.json` 䟝然硬猖码指向倖郚䞊枞地址。 +- **第䞉方 Marketplace Actions 䟛应铟风险高**垂面䞊的 fork-sync Action 倚由䞪人绎技需芁授予敏感的写权限 PAT存圚䞥重的凭据倖泄䞎䟛应铟投毒风险。 + +**GitHub Toolkit** 䞓䞺解决这些问题而讟计基于 100% Python 标准库䞎官方 GitHub CLI 构建提䟛倚层防埡性安党熔断、党批次无写入 Preflight 预挔、自劚倇仜恢倍点、Release 资产同步镜像以及 `latest.json` URL 改写䞎哈垌枅单联劚曎新。 + +--- + +## 栞心特性对比 + +| 功胜特性 | GitHub 眑页 Sync Fork | 垞见第䞉方 Action | GitHub Toolkit | +| :--- | :---: | :---: | :---: | +| **倚仓批量发现䞎状态䞀览** | ❌ 仅胜逐䞪点击 | ❌ 需逐仓配眮 | ✅ **自劚并发发现党莊号 Fork** | +| **枅空䞎删库熔断保技** | ❌ 盲目合并 | ❌ 无保技 | ✅ **文件数突降 50% 立即熔断** | +| **倧批量误删保技** | ❌ 无限制 | ❌ 无限制 | ✅ **劚态删陀预算䞊限拊截** | +| **关键路埄误删保技** | ❌ 无拊截 | ❌ 无拊截 | ✅ **保技 `.github/`、`README` 等** | +| **API 截断逃逞拊截** | ❌ 无校验 | ❌ 无校验 | ✅ **Compare 蟟 300 条自劚拊截** | +| **同步前自劚创建恢倍点** | ❌ 无倇仜 | ❌ 无倇仜 | ✅ **写入前曎新 `backup/pre-sync`** | +| **党批次 Preflight 预挔** | ❌ 䞍支持 | ❌ 䞍支持 | ✅ **任䞀目标匂垞即敎批䞭止** | +| **Release 二进制镜像同步** | ❌ 䞍支持 | ❌ 䞍支持 | ✅ **同步安装包、筟名䞎校验文件** | +| **`latest.json` 自劚曎新改写** | ❌ 䞍支持 | ❌ 䞍支持 | ✅ **改写䞋蜜 URL 䞺 Fork 地址** | +| **校验枅单联劚重算** | ❌ 䞍支持 | ❌ 䞍支持 | ✅ **自劚曎新 SHA256/512 并原子䞊䌠** | +| **旧镜像资产安党枅理** | ❌ 䞍支持 | ❌ 䞍支持 | ✅ **仅枅理已证镜像保留自定义资产** | +| **䟝赖安党性** | 官方服务 | 䟝赖第䞉方镜像/脚本 | ✅ **100% Python 标准库 + 官方 `gh`** | + +--- + +## 安党同步流氎线架构 + +每䞀次默讀分支同步均䞥栌遵埪六重防埡性流氎线 + +```text + ┌────────────────────────────────────────────────────────┐ + │ 1. 运行时劚态发现 (Fresh Discovery) │ + │ 通过 GitHub API 实时获取 Fork 䞎䞊枞默讀分支䞎元数据 │ + └──────────────────────────┬─────────────────────────────┘ + │ + ┌──────────────────────────▌─────────────────────────────┐ + │ 2. 党批次 Preflight 预挔检查 │ + │ 圚产生任䜕写操䜜前对目标仓库完成无写入安党比对 │ + └──────────────────────────┬─────────────────────────────┘ + │ + ┌──────────────────────────▌─────────────────────────────┐ + │ 3. 纵深防埡安党熔断 (Safety Guardrails) │ + │ • 䞊枞文件数 < Fork 50% ➔ 熔断䞭断 │ + │ • 误删文件数 > 劚态配额 (5 + Fork/10) ➔ 熔断䞭断 │ + │ • 删陀 .github/、README、LICENSE 等关键路埄 ➔ 熔断 │ + │ • GitHub Compare 差匂蟟 300 条疑䌌截断 ➔ 熔断 │ + └──────────────────────────┬─────────────────────────────┘ + │ + ┌──────────────────────────▌─────────────────────────────┐ + │ 4. 自劚创建移劚恢倍点 (Restore Point) │ + │ 圚真实 Merge 之前自劚曎新分支 backup/pre-sync │ + └──────────────────────────┬─────────────────────────────┘ + │ + ┌──────────────────────────▌─────────────────────────────┐ + │ 5. 䞊枞合并䞎收敛倍栞 (Merge & Convergence Verification)│ + │ 调甚 merge-upstream再次比对确保 behind_by == 0 │ + └──────────────────────────┬─────────────────────────────┘ + │ + ┌──────────────────────────▌─────────────────────────────┐ + │ 6. Release 资产镜像䞎枅理 (Release Convergence) │ + │ 拉取新安装包、改写 latest.json、重算摘芁、枅理旧镜像 │ + └────────────────────────────────────────────────────────┘ +``` -- `list-forks.py`只读列出圓前莊号的 fork、䞊枞差匂和同步 workflow 状态API 无法确讀时明确报告 `Unknown`䞍䌪装成 `Missing`。 -- `sync-forks.py`dry-run 或同步 fork并圚真实默讀分支写入前创建 `backup/pre-sync`。 -- `sync-forks.py --verify-schedule`只读栞对 workflow 暡板、`SYNC_PAT` 䞎自然定时运行状态。 -- `sync-forks.py --verify-releases/--sync-releases`栞对或收敛最新皳定版资产。 +--- -仓库状态、默讀分支、䞊枞和讀证均圚运行时从 GitHub 获取README 䞍保存易过期的成功快照。 +## 30 秒快速䞊手 -## 准倇 +### 1. 环境准倇 -需芁 Python 3.11+ 侎 [GitHub CLI](https://cli.github.com/)。Windows 可运行 +本工具仅䟝赖 Python 3.11+ 和官方 [GitHub CLI (`gh`)](https://cli.github.com/) ```powershell +# Windows 甚户可通过 winget 䞀键安装 GitHub CLI winget install --id GitHub.cli --source winget + +# 登圕 GitHub 莊号完成本地讀证 gh auth login ``` -自劚化䌘先䜿甚 `GH_TOKEN`其次 `GITHUB_TOKEN`本地亀互可䜿甚 `gh auth login`。脚本䞍䌚读取或保存明文密码。 +> **凭据䌘先级**自劚化环境䌘先读取环境变量 `GH_TOKEN`其次 `GITHUB_TOKEN`本地终端自劚倍甚 `gh auth login` 凭据。工具党皋䞍读取、䞍打印、䞍持久化明文密码。 -## 垞甚呜什 +### 2. 栞心操䜜呜什 + +#### ① 查看圓前所有 Fork 状态只读 ```powershell -# 只读状态 +# 打印栌匏化终端衚栌 python list-forks.py + +# 获取结构化 JSON䟛脚本集成或监控接入 python list-forks.py --json +``` + +终端将枅晰展瀺仓库名、分支、䞊枞源、萜后提亀数Behind、以及同步 Workflow 安装状态 + +```text +Fork repos for your-name (3 total): + +Discovery: live_github_api /user/repos at 2026-10-25T12:00:00Z (repos=12, forks=3) -# 先预览再同步 +Repository Branch Upstream Behind Workflow +------------------------------------------------------------------------------------------------------- +my-awesome-fork main upstream-org/my-awesome-fork 2 Installed +devtools-mirror master original/devtools-mirror 0 Missing +cockpit-custom main cockpit-project/cockpit Unknown Installed +``` + +#### ② 暡拟预览Dry-Run + +圚真实写入前区烈建议先执行 `--dry-run` 预览变曎 + +```powershell +# 暡拟党莊号党郚 Fork 同步 python sync-forks.py --dry-run -python sync-forks.py repo-name --dry-run + +# 暡拟单䞪仓库同步 +python sync-forks.py my-awesome-fork --dry-run +``` + +#### ③ 执行安党同步 + +```powershell +# 同步党郚 Fork python sync-forks.py -# 安装或曎新每䞪 fork 的 weekly sync-fork.yml +# 同步指定 Fork支持单䞪或倚䞪䌠 name 或 owner/name +python sync-forks.py my-awesome-fork other-owner/another-fork +``` + +#### ④ 批量安装 / 曎新自劚同步工䜜流 + +䞺所有 Fork 批量郚眲或无损升级受控的 `sync-fork.yml`每呚定时运行䞔支持手劚觊发 + +```powershell +# 先预览埅安装/埅曎新列衚 python sync-forks.py --add-workflow --dry-run + +# 真实郚眲 python sync-forks.py --add-workflow +``` -# 只读栞对 workflow、secret 和定时运行健康床 -python sync-forks.py --verify-schedule --json +#### â‘€ 巡检定时工䜜流䞎 Secret 健康床 -# 皳定版资产只读栞对䞎收敛 -python sync-forks.py --verify-releases --json -python sync-forks.py --sync-releases --dry-run --json -python sync-forks.py --sync-releases repo-name +```powershell +python sync-forks.py --verify-schedule ``` -仓库参数可写 `name` 或 `owner/name`。倚䞪仓库䌚去重并保持蟓入顺序。 +#### ⑥ Release 资产镜像䞎枅理 -## 安党语义 +```powershell +# 仅栞对资产差匂只读 +python sync-forks.py --verify-releases + +# 暡拟执行资产收敛 +python sync-forks.py --sync-releases --dry-run -默讀分支同步遵埪固定顺序 +# 真实执行资产收敛 +python sync-forks.py --sync-releases my-awesome-fork +``` -1. 从 GitHub API fresh discover fork 䞎䞊枞默讀分支。 -2. 即䜿䜿甚 `--dry-run`也䌚真实读取并比蟃 fork/upstream 文件数量䞎删陀内容dry-run 本身䞍写 GitHub。未星匏䜿甚 `--dry-run` 时工具也䌚先对党郚目标完成同样的无写入 preflight任䞀目标倱莥或安党阻断敎批 apply 郜䞍䌚匀始。 -3. 䞊枞文件数䜎于 fork 的 50%、删陀文件数过倧、compare 文件列衚蟟到 300 条而可胜截断或删陀 `.github/`、`README.md`、`LICENSE` 等关键路埄时䞭止。 -4. 真实同步前把圓前 fork HEAD 写入移劚恢倍分支 `backup/pre-sync`。 -5. 调甚 GitHub `merge-upstream`随后重新比蟃并确讀 fork 䞍再萜后无法倍栞时按安党阻断返回䞍把写入响应倖掚䞺已收敛。 +--- -`--dry-run` 䞍写 GitHub䜆䌚执行必芁的安党 API 读取。`--force` 䌚绕过郚分安党检查因歀真实写入还必须星匏确讀 +## 暡块䞎呜什党量参考 + +### 1. `list-forks.py` + +| 参数 | 诎明 | +| :--- | :--- | +| *(无参数)* | 终端衚栌蟓出党莊号 Fork 状态、萜后提亀数及 Workflow 安装状态 | +| `--json` | 蟓出机噚可读的结构化 JSON包含讀证身仜、Discovery 证据䞎逐仓明细 | +| `-h, --help` | 星瀺垮助信息 | + +> **状态䞥谚性保障**若因 API 限制或权限问题无法确讀状态脚本明确返回 `Unknown` 并附垊诊断原因绝䞍将未知状态䌪装䞺 `Missing`。 + +### 2. `sync-forks.py` + +| 参数 / 选项 | 暡匏分类 | 功胜诎明 | +| :--- | :---: | :--- | +| `[repo-name ...]` | 目标选择 | 指定䞀䞪或倚䞪仓库`repo` 或 `owner/repo`自劚去重并保持顺序省略则倄理党郚 Fork | +| `--dry-run` | 暡拟执行 | 完敎运行真实 API 读取䞎安党比对规则䞍产生任䜕 GitHub 写入 | +| `--add-workflow` | 工䜜流分发 | 圚目标 Fork 䞭创建或曎新 `.github/workflows/sync-fork.yml` | +| `--verify-schedule` | 只读审计 | 巡检各 Fork 的 Workflow 安装状态、`SYNC_PAT` 密钥配眮及最近定时运行历史 | +| `--verify-releases` | 只读审计 | 对比䞊枞䞎 Fork 最新皳定版资产差匂䞎保留策略 | +| `--sync-releases` | 资产收敛 | 镜像最新皳定版安装包、改写 `latest.json` 并枅理旧版本䞊枞镜像 | +| `--force` | 区制暡匏 | 绕过郚分安党限制或区制重写工䜜流暡板真实写入需二次确讀 | +| `--json` | 蟓出控制 | 打印包含运行摘芁、前眮检查结果䞎逐仓操䜜明细的 JSON | +| `-h, --help` | 垮助信息 | 打印完敎的呜什行䜿甚诎明 | + +### 3. 区制写入二次确讀机制`--force` + +䞺了防止自劚化流氎线或手误造成䞍可逆砎坏圓䜿甚 `--force` 䞔涉及真实远端写入时必须星匏配眮环境变量确讀 ```powershell +# PowerShell $env:SYNC_FORKS_FORCE_ACK = "I_UNDERSTAND" python sync-forks.py --force + +# Windows CMD +set SYNC_FORKS_FORCE_ACK=I_UNDERSTAND +python sync-forks.py --force + +# Linux / macOS Bash +SYNC_FORKS_FORCE_ACK=I_UNDERSTAND python3 sync-forks.py --force +``` + +### 4. 退出码契纊Exit Codes + +脚本圚 CLI 䞭䞥栌遵埪以䞋退出码规范方䟿 CI/CD 流氎线集成 + +- `0`操䜜成功或无需进行任䜕写入劚䜜。 +- `1`CLI 猺倱、凭据无效、GitHub API 眑络错误或参数语法解析错误若 `list-forks.py` 存圚任䞀仓状态未胜成功确讀也返回 1。 +- `3`安党防技规则觊发熔断阻断或只读巡检发现存圚需芁人工介入/倄理的埅办项。 + +--- + +## Release 资产同步䞎智胜改写诊解 + +讞倚现代匀源桌面应甚劂 Tauri、Electron 构建的客户端䟝赖 GitHub Releases 进行分发䞎自劚曎新。普通的 Git Fork 只胜同步源码分支无法镜像 Release。 + +`--sync-releases` 针对这䞀场景提䟛了端到端的镜像解决方案 + +```text +䞊枞 Release (v1.2.0) Fork Release (v1.2.0) + ├── app-setup.exe ─── 同步镜像 ───► ├── app-setup.exe + ├── app-setup.dmg ─── 同步镜像 ───► ├── app-setup.dmg + ├── latest.json ─── 智胜改写 ───► ├── latest.json (URL 改写䞺 Fork 铟接) + └── SHA256SUMS.txt ─── 联劚曎新 ───► └── SHA256SUMS.txt (重新计算校验倌) ``` -䞍芁圚日志、呜什记圕或仓库文件䞭打印 token。 +1. **癜名单资产粟准匹配**识别 `.exe`、`.msi`、`.deb`、`.rpm`、`.appimage`、`.dmg`、`.pkg`、`.zip`、`.tar.gz` 等安装包`.sig`、`.minisig` 筟名以及哈垌枅单䞎 `latest.json`。 +2. **`latest.json` 自劚改写**解析 JSON 内容自劚将䞋蜜地址从 upstream 域名前猀改写䞺圓前 fork 仓库的䞋蜜地址。 +3. **校验枅单联劚重算**若包内含 `SHA256SUMS.txt` 或 `SHA512SUMS.txt`自劚计算新 `latest.json` 的最新哈垌并替换对应行。 +4. **元数据原子䞊䌠**将 `latest.json` 䞎校验枅单䜜䞺同䞀批次元数据 bundle 䞊䌠避免因单文件䞊䌠时差造成校验倱莥。 +5. **资产名称安党枅掗**䞥犁包含路埄分隔笊`/`、`\`、NUL 字笊、父目圕逃逞`..`或 CLI 参数前猀`-`的匂垞文件名。 +6. **已证明镜像枅理策略**圓䞊枞发垃曎高版本时仅枅理通过“同 tag、同名䞔盞同 digest/size”䞥密证明来自䞊枞的旧镜像资产**绝对䞍䌚删陀甚户圚 Fork 䞊自行䞊䌠的䞪性化资产或自定义 Tag**。 + +--- + +## GitHub Actions 自劚化运绎 -## Release 收敛 +本项目自垊䞉套互补的 GitHub Actions 工䜜流可盎接接入持续亀付流皋 -圓䞊枞最新皳定版包含安装包、筟名、校验文件或 `latest.json` 时`--sync-releases` 可 +- **`ci.yml`**圚代码提亀或 PR 时自劚运行党郚 58 项单元测试。 +- **`auto-setup-forks.yml`**每呚日定时自劚扫描党莊号若发现了新创建的 Fork或 `sync-forks.py` 暡板发生升级将自劚䞺所有 Fork 安装/曎新最新的 `sync-fork.yml` 同步流氎线。 +- **`integration-api-smoke.yml`**每呚䞀䜿甚只读凭据针对真实 GitHub API 进行冒烟测试巡检接口兌容性䞎结构䜓变化。 -- 圚 fork 创建或补霐同 tag 的皳定版资产 -- 把 `latest.json` 䞋蜜地址改写到 fork并同步曎新 `SHA256SUMS.txt` -- 将 `latest.json` 侎 SHA-256/SHA-512 枅单䜜䞺䞀䞪元数据 bundle 芆盖䞊䌠避免只猺其䞭䞀䞪文件时留䞋䞍匹配校验倌 -- 拒绝包含路埄分隔笊、NUL 或 CLI 选项前猀的匂垞䞊枞资产名避免逃逞䞎时目圕或改变参数解析 -- 只删陀胜借甚同 tag、同名及盞同 digest无 digest 时䜿甚盞同 size证明来自䞊枞的旧皳定版镜像资产fork 自有 tag/资产默讀保留。 +### 仓库 Secret 配眮 -没有安装资产的䞊枞按 `source_only_release_notes` 跳过。本地 release 子呜什单次最长等埅 10 分钟生成的 workflow job 最长 30 分钟执行噚䌚圚写入后重新栞对未收敛时返回 safety 状态䞍把郚分成功报告䞺完成。 +圚运行自劚化运绎流氎线时按需配眮以䞋 GitHub Actions Secrets -## 蟓出䞎退出码 +| Secret 名称 | 必须 | 䜜甚䞎权限诎明 | +| :--- | :---: | :--- | +| `SYNC_PAT` | 是 | 具倇 `repo` 侎 `workflow` 权限的 Personal Access Token甚于向各 Fork 提亀工䜜流文件及执行跚仓同步 | +| `INTEGRATION_GH_TOKEN` | 吊 | 甚于 API 冒烟测试的䞓甚只读 Token | +| `INTEGRATION_EXPECTED_LOGIN` | 吊 | 甚于冒烟测试校验 Token 所属莊号䞻䜓防止凭据错配 | +| `INTEGRATION_TARGET_REPO` | 吊 | 冒烟测试时可选针对的指定测试 Fork 仓库党名 | -`--json` 蟓出包含讀证来源、fresh discovery 证据、逐仓结果和 summary。皳定错误码甚于区分 CLI、讀证、眑络/API 和发现倱莥。 +--- -- `0`成功或无需劚䜜。 -- `1`CLI、讀证、API 或执行错误`list-forks.py` 任䞀仓状态无法确讀时也返回 1并圚 JSON 䞭保留逐仓错误。 -- `3`安党检查阻断或只读栞对发现需芁人工/写入劚䜜。 +## 灟隟恢倍指南 -## GitHub Actions +劂果䞊枞仓库发生重倧砎坏䞔未被防技规则拊截或䜿甚了 `--force`悚可以借助自劚创建的恢倍分支进行䞀键秒级回退 -- `ci.yml`push/PR 只运行䞀套行䞺测试䞍重倍安装 lint/type/benchmark 工具。 -- `auto-setup-forks.yml`定时䞺新 fork 安装或曎新同步 workflow`main` 䞊暡板实现变化时也䌚立即投圱䞔 concurrency 防止安装任务并发。managed 文件䞎圓前暡板䞍完党䞀臎时䌚收敛避免保留未受管步骀。 -- `integration-api-smoke.yml`䜿甚独立只读凭据运行最薄 GitHub API 䞻铟包括 `--verify-schedule` 侎 release 栞对它是运营检查䞍是每次本地猖码闚犁。 +```bash +# 1. 切换到本地 Fork 仓库目圕 +cd path/to/your-fork -仓库 Secret +# 2. 从远端拉取自劚生成的恢倍分支 +git fetch origin backup/pre-sync -- `SYNC_PAT`安装 fork workflow以及 fork workflow 自身同步所需权限。 -- `INTEGRATION_GH_TOKEN`integration smoke 的只读 token。 -- `INTEGRATION_EXPECTED_LOGIN`甚于阻断 token 䞻䜓错配。 -- `INTEGRATION_TARGET_REPO`可选只验证䞀䞪指定 fork 的参数路埄。 +# 3. 检查倇仜点的状态䞎提亀记圕 +git log -n 5 origin/backup/pre-sync -## 匀发验证 +# 4. 将默讀分支硬重眮到同步前的安党状态 +git checkout main +git reset --hard origin/backup/pre-sync -本地䞎 CI 䜿甚同䞀条最䜎充分呜什 +# 5. 区制掚送到 Fork 远端完成恢倍 +git push origin main --force +``` + +--- + +## 本地匀发䞎测试 + +运行完敎的单元测试套件无倖郚䟝赖耗时通垞 < 0.1 秒 ```powershell python -m unittest -q test_toolkit.py ``` -测试芆盖讀证/API 错误、fork 发现、党批次 preflight、dry-run、删陀保技、恢倍点、force acknowledgement、schedule readiness、JSON 错误和 release 来源证明/安党结果。只有出现可倍现的独立倱莥时才增加针对性验证䞍绎技逐任务证据文件、合成 benchmark 或重倍 contract suite。 +测试集涵盖 +- GitHub CLI 探测䞎超时匂垞分类 +- 凭证解析䞎并发䞊枞父仓发现 +- 工䜜流暡板枲染䞎无损曎新比对 +- 50% 文件骀降、倧批量删陀䞎关键文件删陀熔断拊截 +- Compare 300 条 API 截断防技䞎恢倍点绎技 +- 区制写入确讀环境变量拊截 +- Release 资产癜名单过滀、URL 改写䞎 SHA256 联劚重算 +- 来源证明镜像比对䞎安党枅理蟹界 + +--- + +## 讞可证 + +本项目基于 [MIT 讞可证](https://opensource.org/licenses/MIT) 匀源。欢迎提亀 Issue 或 Pull Request 共同完善