不用先建数仓：用 Steampipe 把 GitHub 配置审计变成可复用的 SQL 查询
团队想回答“有哪些公开仓库”“哪些仓库的默认分支不是 main”“哪些项目已归档却仍在自动化清单中”时，常见做法是写一次性 API 脚本、导出 CSV，再在表格中筛选。这个流程并非不能用，但它把认证、分页、字段映射和结果保存都散落在不同脚本里；下一次审计时，又得重新确认 API 版本、重写筛选条件。更麻烦的是，导出的快照很快过期，读者也难以分辨某个结论来自哪次采集。
Steampipe 提供了另一条路径：它是一个本地运行的 CLI，通过插件把外部 API 映射为 SQL 表，在查询时获取实时数据，而不是要求先把数据同步进一套独立数据库。官方仓库将这种方式称为 zero-ETL：SQL 仍是查询接口，数据源仍由各自 API 提供，CLI 则负责连接、并发请求和表结构映射。对临时盘点、持续合规检查或 CI 中的只读核查而言，这比维护一批专用脚本更容易复用和审阅。
本文以 GitHub 为例，演示如何把“检查仓库配置”变成几条可保存、可在下次直接重跑的 SQL。Steampipe 本身采用 AGPL-3.0 许可证；它不是 GitHub 的镜像或替代品，查询结果的可见范围仍由你的 GitHub Token 权限决定。
先理解边界：SQL 是接口，不是离线副本
Steampipe 的 GitHub 插件把 GitHub API 的对象组织成表。查询 github_my_repository 时，CLI 会在运行时向 GitHub 请求当前凭据可见的仓库数据，再把响应暴露为列。这样做有两个直接后果。
第一，结果更接近执行时的状态。有人刚把仓库改为私有、归档或改了默认分支，下一次查询能反映变化；不需要先安排一轮 ETL。第二，查询性能与 API 限额仍然相关。大范围 select * 既不利于阅读，也可能带来不必要的请求。实际使用时应只选需要的列，并用 where 条件尽早收窄范围。
这也意味着它不适合替代长期分析仓库。若目标是保存多年历史、跨系统做复杂聚合，仍应选择专门的数据管道或数据仓库。Steampipe 更适合“把本来要写 API 脚本的现场查询，收敛成版本化 SQL”的场景。
安装 CLI 与 GitHub 插件
官方 README 提供 macOS、Linux 与 WSL 的安装方式。macOS 可通过 Homebrew 安装；Linux/WSL 使用官方安装脚本。随后安装 GitHub 插件，并把 Token 留在环境变量中，而非写进 SQL 文件或提交到仓库。
brew install turbot/tap/steampipe
sudo /bin/sh -c "$(curl -fsSL https://steampipe.io/install/steampipe.sh)"
steampipe plugin install github
export GITHUB_TOKEN="${GITHUB_TOKEN}"
最后一行假定你已经通过密钥管理工具、shell profile 或 CI secret 注入了 GITHUB_TOKEN。不要把真实 Token 放在 shell 历史、截图、Markdown 示例或 .spc 配置中。Token 的权限决定可见仓库范围：只需审计公开仓库时，不应为方便而授予不必要的组织写权限。
执行 steampipe query 后可进入交互式查询界面；也可将 SQL 保存为文件并放进代码审查流程。先从一个很小的查询确认认证与插件连接正常：
select full_name, visibility, is_private, archived, default_branch from github_my_repository order by full_name;
这里刻意只返回仓库名、可见性、私有标记、归档状态和默认分支。它足够回答大部分配置盘点问题，也避免把描述、语言统计或其他未使用字段一并取回。
把策略写成可读的异常清单
SQL 的价值不只是“能查到数据”，而是能把团队规则写成审计对象。以下查询列出尚未归档的公开仓库，并按最近更新时间排序。它适合做人工复核的起点：公开并不代表错误，但你至少能得到一份有确定条件的候选清单。
select full_name, default_branch, updated_at from github_my_repository where visibility = 'public' and archived = false order by updated_at desc;
下一步可以把默认分支策略明确表达出来。许多团队约定新仓库使用 main，但历史仓库可能仍为 master 或自定义分支。不要把查询结果直接当作整改命令；更合理的方式是先输出例外清单，与迁移计划和受保护分支规则一起审阅。
select full_name, default_branch, visibility, updated_at from github_my_repository where archived = false and default_branch <> 'main' order by updated_at desc;
这条查询的边界同样重要：默认分支名称不是安全强度指标。它只能发现“不符合约定”的配置，不能证明仓库是否开启了分支保护、是否存在泄露密钥，或是否满足发布流程。不要用一个字段替代完整的安全审计。
让查询成为工程资产，而不是一次性终端记录
建议把稳定的查询保存为 .sql 文件，并在文件头写明用途、负责人和例外规则。例如可把“公开且未归档仓库”保存为 audit/public_active_repositories.sql，由 CI 以只读凭据定期运行，并把输出发送到受控的审阅渠道。这样，规则变更会留下 diff，排查某条结果时也能定位当时使用的筛选条件。
不过，接入 CI 前要先处理三个失败模式。其一是 Token 失效或权限变化：应让任务明确失败，而不是把空结果解释为“没有仓库”。其二是 GitHub API 限流或网络故障：应区分暂时失败与确实没有匹配项，并为重试设置上限。其三是组织规模扩大：先用精确列和条件验证请求量，再决定是否拆分组织、仓库类型或时间窗口。实时查询省去了同步层，不会自动消除外部 API 的配额和可用性边界。
对于需要留档的合规结论，还应保存执行时间、Steampipe 与插件版本、SQL 原文及输出摘要。因为数据是实时读取的，同一条 SQL 在仓库设置被修改后理应产生不同结果；可复现的目标不是让结果永远不变，而是让变化能被解释为“数据变了”还是“规则变了”。
从交互查询走向可审阅的自动化
把 SQL 放进自动化前，先在本地为每条规则建立一个可解释的基线。比如第一次运行“公开且未归档仓库”查询时，人工确认每一行是否确实符合团队对公开项目的定义；有意公开的文档仓库、镜像仓库或开源组件可以记录为例外，而不是在 SQL 中悄悄排除。之后再把例外条件显式写入查询或相邻说明文件，避免后来的人把“没有出现在报表中”误解为“从未存在过”。
CI 的输出也不宜直接作为处置指令。较稳妥的模式是：定时任务只生成候选清单和执行元数据；审阅者确认业务上下文；真正的改动仍通过 GitHub 的正常变更、审批与审计链完成。这样即使查询逻辑、插件版本或 Token 可见范围发生变化，也不会让一次只读盘点意外演变成批量修改。对需要告警的规则，建议将“查询执行失败”“返回零行”和“发现异常行”作为三个不同状态分别处理，不能把前两者混在一起。
当规则逐渐增多时，可以按主题拆分文件，例如仓库可见性、归档状态和默认分支各自一条查询，再用一个说明文档记录它们的目的、例外和触发频率。小而明确的 SQL 更易审查，也比一条混合几十个条件的大查询更容易定位错误。
何时选择 Steampipe，何时不要选
当工作重心是跨 API 的临时查询、工程盘点、只读检查和以 SQL 复用团队规则时，Steampipe 的表模型很合适。GitHub 之外，官方插件目录还覆盖多种云服务、Kubernetes 和 Hacker News 等来源，便于在同一个 SQL 工作流中组合不同系统的数据。
如果你需要高频大规模分析、长期历史存储、离线报表或严格的事务语义，则应选择数据仓库、事件管道或服务自身的 API 集成。Steampipe 不应被包装成“用 SQL 就解决所有治理问题”的工具。它真正降低的是查询与审计表达的成本：把零散脚本中的判断条件变成可读 SQL，再将认证、权限、限流和例外处理保留在工程流程中。
从一条只读仓库清单开始最稳妥。先验证 Token 权限和结果范围，再把经过团队确认的规则保存下来。这样，SQL 才不是一次性命令，而是能够在下一次盘点中继续提供证据的配置审计资产。