# OrgRepoKanban

**Repository Path**: NEVSTOP-LAB/OrgRepoKanban

## Basic Information

- **Project Name**: OrgRepoKanban
- **Description**: 1. 管理组织中仓库权限; 2. 管理私有仓库的Secrets; 3. action 监控看板
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: https://nevstop-lab.github.io/OrgRepoKanban/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-30
- **Last Updated**: 2026-08-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OrgRepoKanban — GitHub 组织仓库治理工具集

基于 React + TypeScript + Vite 的前端单页应用，面向 GitHub 组织管理员，提供统一入口管理组织仓库的**权限**、**Actions Secret** 与 **Actions Runner 运行情况**。

- 🏠 **首页统一认证**：在首页一次输入 PAT 与组织名称，三个看板共享连接；断开即清除内存凭据。
- 📋 **权限看板**：看板式拖拽界面，管理团队或个人协作者的仓库权限。
- 🔐 **Secret 管理**：为私有仓库批量配置 Actions Secret，支持拖拽匹配与待执行队列。
- 🏃 **Runner 看板**：监控自托管 Runner 的在线/忙碌状态，追踪排队等待执行的 workflow。

## 页面结构

访问 `https://nevstop-lab.github.io/OrgRepoKanban/` 进入首页，通过功能卡片选择：

| 页面 | 功能 | 路径 |
|------|------|------|
| 🏠 首页 | 统一认证入口 + 功能卡片跳转 | `/` |
| 📋 权限看板 | 仓库权限拖拽管理 | 从首页进入 |
| 🔐 Secret 管理 | 私有仓库 Actions Secret 配置 | 从首页进入 |
| 🏃 Runner 看板 | Runner 状态与排队 workflow 监控 | 从首页进入 |

每个功能页面均有「← 返回首页」按钮。

## 功能概览

### 权限看板

- 输入 GitHub 个人访问令牌和组织名称，校验当前令牌是否是该组织管理员。
- 支持团队与直接授权个人协作者两类主体。
- 团队按父子层级展示，可直接管理父团队或子团队。
- 直接协作者仅展示至少被一个仓库直接授权的用户。
- 看板按权限列展示仓库：`Read`、`Triage`、`Write`、`Maintain`、`Admin`、`未授权`。
- 每个仓库只会显示在该主体的最高有效权限列。
- 支持仓库名实时过滤，支持包含与模糊匹配。
- 支持 `全部 / Public / Private / Forked` 预置过滤按钮，便于快速定位仓库。
- 支持 Ctrl 或 Cmd 多选卡片，并批量拖拽修改权限。
- 批量修改前会弹出确认框，执行后会展示成功/失败清单，并按真实结果回滚失败项。
- 支持重新从 GitHub 拉取数据刷新当前看板。

### Runner 看板

- 读取组织级自托管 Runner 列表，按 **空闲 / 忙碌 / 离线** 三列看板展示。
- 概览区展示 Runner 总数、各状态计数与在线负载百分比条。
- 每个 Runner 卡片显示名称、操作系统、标签与忙碌脉冲动画。
- 忙碌的 Runner 会显示当前正在执行的 workflow（运行标题），点击可打开新页面跳转到 GitHub Actions 对应的运行详情页。
- Runner 列表不可读（缺少 manage_runners:org 权限）时，忙碌卡片不显示 workflow 链接，队列监控不受影响。
- 排队队列汇总全部仓库中 status=queued 的 workflow run，默认按等待时长排序、等待最久的排在最前（创建时间升序、等待时长降序）；可通过「队列排序方式」下拉切换为按触发时间（最新优先）/ 仓库名 / 分支名排序，纯本地重排，不发起请求。
- 分支已被合并或删除的排队 workflow 会自动隐藏（按仓库 + 分支去重检查、全局并发受限、检查失败放行），并显示「已隐藏 N 个排队中的 workflow（对应分支已被合并或删除）」提示条。
- 每条排队记录展示仓库、workflow 名、分支、触发事件、发起人与等待时长，并提供等待条（相对最长等待）与 GitHub 详情链接。
- 最近 30 天运行记录默认展示全部运行，可用状态筛选下拉在「全部状态 / 运行中 / 成功 / 失败 / 取消」间切换；已取消（cancelled）的运行单独展示为「取消」并显示灰色，不再当作失败。
- 最近 30 天运行记录只统计**最近 30 天内有推送的仓库**的运行历史（与排队队列的 24 小时口径解耦，无需对全部仓库做全量历史拉取），仓库数量收敛到近期活跃范围；所在分支已被合并/删除的运行会被隐藏。
- 最近 30 天运行记录会把最近一次成功的数据按组织缓存到本地（localStorage），启动时先快速显示缓存再做全量刷新覆盖；刷新采用时间戳增量合并，较新的卡片状态覆盖旧值并更新缓存，刷新失败时保留上一次数据。
- 排队队列默认仅扫描 **24 小时内有推送的仓库**，可在工具栏切换为扫描全部仓库。注意：定时、手动或外部触发的 workflow 在仓库久未推送时同样可能排队，开启默认扫描范围时不会被发现；空队列提示中会注明此口径。
- 支持 30s / 1min / 3min / 5min 自动刷新（默认 3 分钟）与手动刷新，等待时长随本地时钟每 5 秒更新。
- 无法读取的仓库（未启用 Actions 或令牌缺 repo 权限）会被跳过并在界面提示。
- 纯只读监控，不提供任何写操作。

### Secret 管理

- 左侧面板列出组织级 Actions Secret（名称从 API 获取，值需手动输入）。
- 右侧面板列出私有仓库，标签显示已配置的 Secret。
- 右侧面板支持按仓库名或已配置 Secret 名称**实时过滤**，过滤时同步显示匹配数量，便于快速定位仓库。
- **双向拖拽**：拖拽 Secret 卡片到仓库，或反向拖拽仓库到 Secret，即可排入配置操作。
- 点击仓库标签上的 `×` 按钮可排入删除操作。
- **待执行操作面板**（底部）：
  - 列出所有排入操作及其中文描述。
  - 支持单条移除。
  - **确认执行**：以并发工作池异步调用 GitHub API，每个操作成功后就立即从待执行列表移除，列表实时缩减；失败操作保留在队列中供重试。
  - **取消全部**：清空所有待处理操作。
- Secret 值通过 **libsodium 密封盒加密**（`crypto_box_seal`）后传输至 GitHub API。
- 成功写入后自动清除明文值，不保留在内存中。

## 安全策略

- PAT 与 Secret 值只保存在当前页面内存中。
- 不会写入 `localStorage`、`sessionStorage`、`cookie` 或任何浏览器持久化存储。
- 页面刷新后，令牌、组织名称和 Secret 值会失效，需要重新输入。
- 首页的「断开连接」会立即清除内存中的令牌并锁定所有看板。
- Secret 值通过 libsodium 密封盒加密后传输，不在网络中明文暴露。

## 令牌权限要求

建议使用具备以下权限的 GitHub 个人访问令牌：

- `admin:org`
- `repo`
- `manage_runners:org`（Runner 看板读取组织 Runner 状态时需要；缺失时队列监控仍可用）

如果当前令牌不是目标组织管理员，页面会明确提示，并阻止任何权限修改或 Secret 写入操作。

## 交互说明

### 首页 — 统一认证与导航

1. 打开页面即进入首页，在顶部输入 PAT 和组织名称，点击"连接组织"。
2. 管理员校验通过后，三个功能卡片解锁；未连接时卡片保持锁定。
3. 点击卡片进入对应看板；各看板复用首页的共享连接，无需重复输入凭据。
4. 在功能页点击「← 返回首页」回到导航；点击「断开连接」立即清除内存中的令牌并锁定卡片。

### 权限看板 — 数据加载

1. 从首页连接组织后进入，系统会自动加载仓库、团队以及对应权限数据。
2. 页面内点击"刷新"可重新拉取数据。

### 权限看板 — 主体切换

1. 可在"团队"和"直接授权个人协作者"之间切换。
2. 团队列表会按层级缩进显示。
3. 个人协作者列表会在首次切换到该模式时按仓库聚合加载。

### 权限看板 — 看板拖拽

1. 单击卡片可选中当前仓库。
2. 按住 Ctrl 或 Cmd 再点击，可追加或取消多选。
3. 拖拽到目标权限列后，会先弹出确认框。
4. 拖到"未授权"列表示移除该主体对仓库的权限。

### 权限看板 — 过滤

1. 输入仓库关键字后，看板会实时过滤。
2. 支持不区分大小写的包含匹配，也支持按字符顺序的模糊匹配。
3. 点击"清空过滤"可以恢复完整视图。

### Secret 管理 — 数据加载

1. 从首页连接组织后进入，自动加载组织 Secret 列表和私有仓库列表。
2. 可点击"刷新"重新拉取最新数据。

### Secret 管理 — 配置 Secret

1. 在左侧 Secret 卡片的输入框中填入 Secret 值。
2. 拖拽 Secret 卡片到右侧仓库卡片（或反向拖拽），排入设置操作。
3. 点击仓库标签旁的 `×` 按钮排入删除操作。
4. 右侧仓库列表可按仓库名或 Secret 名称实时过滤，过滤后「全选」只作用于当前匹配的仓库。
5. 在底部面板查看所有待执行操作。
6. 点击「确认执行」并发写入 GitHub，已完成的操作会从列表中动态移除，可直接观察执行进度；点击「取消全部」清空队列。
7. 失败操作会保留在队列中，修正后重新确认即可。

### Runner 看板 — 数据加载

1. 从首页连接组织后进入，自动加载组织仓库与自托管 Runner 列表。
2. 随后并发扫描各仓库的排队 workflow（默认仅扫描 24 小时内有推送的仓库）；扫描时按 (仓库, 分支) 去重检查分支是否仍存在，分支已被合并或删除的排队 workflow 会自动隐藏，并显示「已隐藏 N 个排队中的 workflow」提示条。
3. 可点击"刷新"重拉数据，或选择自动刷新周期。
4. 切换"仅扫描 24 小时内有推送的仓库"开关会立即按新范围重新扫描。
5. 排队队列可通过「队列排序方式」下拉在等待时长（最久优先，默认）/ 触发时间（最新优先）/ 仓库名 / 分支名之间本地重排，不发起请求、不重新连接。
6. 最近 30 天运行记录默认展示全部，可用状态筛选下拉在「全部状态 / 运行中 / 成功 / 失败 / 取消」间切换；取消（cancelled）运行单独显示为「取消」灰色，不与失败混同。记录只来自最近 30 天内有推送的仓库（与排队队列的 24 小时范围独立），所在分支已合并/删除的运行会被隐藏。最近一次数据按组织缓存到本地，启动先显示缓存再做全量刷新（时间戳增量合并），效果与全量刷新一致。

## Docker 部署

仓库已包含 `Dockerfile`、`.dockerignore` 与 `nginx.conf`，可直接构建镜像并部署。

### 构建镜像

```bash
docker build -t org-repo-kanban:latest .
```

### 运行容器

```bash
docker run --rm -p 8080:80 org-repo-kanban:latest
```

启动后可通过 `http://localhost:8080` 访问。

## 技术架构

- 前端框架：React 19
- 构建工具：Vite 8
- 语言：TypeScript（strict 模式）
- 测试：Vitest + Testing Library
- 加密：libsodium-wrappers（Secret 密封盒加密）
- 部署：GitHub Pages（静态文件）或 Docker + Nginx
- 后端：无自定义后端，所有 API 调用直连 `https://api.github.com`

## 开发者

如需参与开发，请参阅 [开发指南](CONTRIBUTING.md)。