改动一个仓库时，看看哪些仓库会受影响。

你正准备改动某个共享的基础镜像、Terraform module、CI workflow 或 library。哪些仓库在用它？哪些还停留在旧版本？通常答案只存在于某个人的脑子里，或者一个早就过时的 wiki 页面上。

ripplemap 读取你仓库里已有的文件，几秒内就能给出答案：Dockerfiles、Terraform、GitHub Actions、Kubernetes、Helm、Compose、npm、Go 和 Python 都支持。不用编写目录清单，不用运行服务器，所有数据都不会离开你的机器。

两条命令即可。需要 Node.js 22 或更新版本，无需 clone：

npx ripplemap scan --org your-org npx ripplemap report --open

如果你已通过 GitHub CLI 登录（gh auth login），配置就到此为止，私有仓库也能用。否则，把 GITHUB_TOKEN 设为任意 token。不设置的话，GitHub 每小时只允许约 50 个仓库的请求量。

npx ripplemap impact <repo> # 改动 <repo> 会影响到的所有内容 npx ripplemap drift # 以不同版本使用的共享内容 npx ripplemap unpinned # 未锁定任何版本的引用

$ ripplemap impact base-images base-images ├─ api image ghcr.io/acme/base:1.4 Dockerfile:1 │ └─ frontend image ghcr.io/acme/api:latest docker-compose.yml:3 └─ web image ghcr.io/acme/base:1.2 Dockerfile:1 3 repos affected: 2 direct, 1 indirect.

frontend 从未提到 base-images。它运行的是 api 镜像，而 api 镜像构建在 base-images 之上。ripplemap 会沿着这条链追踪下去。

扫描速度快且有缓存。Cloud Posse 的 163 个 Terraform 仓库首次扫描用了 25 秒；重复扫描约需 5 秒，因为只有有新 push 的仓库会被重新拉取。已经 clone 了仓库？改用 npx ripplemap scan ~/code/your-org。

在 Azure DevOps 上？直接用具有 Code (read) 权限的 personal access token 扫描组织：

AZURE_DEVOPS_TOKEN=<your PAT> npx ripplemap scan --azure-org your-org npx ripplemap report --open

公共项目无需 token：npx ripplemap scan --azure-org your-org --project YourProject。Module source 和 remote 无论怎么写都能匹配：https://dev.azure.com/...、git@ssh.dev.azure.com:v3/... 或 *.visualstudio.com。

也可以用 npm install -g ripplemap 全局安装。

GitHub Action 会在 pull request 上评论，指出该改动可能影响哪些仓库。把它加到其他仓库所依赖的仓库里，比如共享 module、基础镜像、可复用 workflow 和 library：

.github/workflows/ripplemap.yml

name: ripplemap on: pull_request_target permissions: contents: read pull-requests: write jobs: impact: runs-on: ubuntu-latest steps:

• uses: Zintrivious/ripplemap@v0

with:

token: ${{ secrets.RIPPLEMAP_TOKEN }} # 私有仓库用，见下文

下面是它被告知某个 pull request 改动了 Cloud Posse 的 terraform-aws-security-group 后发布的评论（有删减）：

它会随着 pull request 的变化保持一条评论为最新状态，把同样的报告写入 job summary，而在没有任何影响时完全不评论。

权限与安全。该 Action 通过 API 读取 pull request 的文件列表，从不 checkout 或运行 pull request 的代码。正因如此，这里使用 pull_request_target 是安全的，也正是这一点让它能对来自 fork 的 pull request 发表评论。不要在同一个 job 里加入对 pull request 代码的 checkout。默认的 job token 可以读取公共仓库。要扫描私有仓库，需传入一个对组织中每个仓库都有读权限的 token，可以是具有 Contents: read 权限的 fine-grained personal access token，也可以是 GitHub App token。

输出：affected（该改动可能影响的仓库）、direct 和 complete（当每个文件都能读取时为 "true"）。该 Action 会为它所在的 job 安装 Node 24，所以请像上面那样给它单独一个 job。

要在开 pull request 之前检查改动，可以在本地运行同样的分析：

git diff --name-only main | npx ripplemap affected <repo> --files -

命令

ripplemap scan --org <name> / ripplemap scan <dir> 通过 API 扫描一个 GitHub 组织或用户，或扫描一个已 clone 仓库的文件夹（或单个仓库），并写入 ripplemap.json。

ripplemap affected <repo> / --files <path|-> 所有依赖 <repo> 的仓库，无论是直接依赖还是通过其他仓库间接依赖，并给出每个引用的文件和行号。加 --json 便于脚本处理。

ripplemap impact <repo> [--files <path|->] 对 <repo> 的某个具体改动可能影响什么，如「On every pull request」一节所述。--files 接收一个每行一个路径的文件，或用 - 表示 stdin。加 --markdown 输出 pull request 评论，或加 --json 便于脚本处理。

ripplemap drift 以不止一个版本使用的共享内容。下面是它在 Cloud Posse 全部 163 个 Terraform module 仓库上的结果，排除了 examples 和 tests。他们是一个管理良好的组织，使用 Renovate，但他们自己的 module 中仍有 16 个以不匹配的版本被使用：

$ ripplemap scan --org cloudposse --match 'terraform-*' --exclude examples --exclude test $ ripplemap drift --internal cloudposse/security-group/aws module · built in terraform-aws-security-group · 3 versions across 12 repos 2.2.0 terraform-aws-ec2-client-vpn, terraform-aws-ec2-instance-group, terraform-aws-efs +5 more 1.0.1 terraform-aws-elastic-beanstalk-environment, terraform-aws-mwaa 0.3.3 terraform-aws-ec2-bastion-server, terraform-aws-ec2-instance cloudposse/utils/aws module · built in terraform-aws-utils · 2 versions across 3 repos 1.4.0 terraform-aws-config, terraform-aws-dynamic-subnets unpinned terraform-aws-github-action-token-rotator

Option --internal 仅显示在你扫描的仓库中构建的内容（隐藏 actions/checkout 之类） --kind <kind> image、terraform-module、workflow、action、npm、helm-chart、go 或 python。可重复指定。 --fail 发现 drift 时以退出码 1 退出，便于在 CI 中运行 --json 完整输出，便于脚本处理

ripplemap unpinned 不锁定任何版本的引用：FROM ghcr.io/acme/base（latest）、uses: acme/ci/.github/workflows/build.yml@main、没有 ref 或 version 的 Terraform module。构建它们的仓库每次发布，都会在无人开 pull request 的情况下直接到达这些使用方。

$ ripplemap unpinned cloudposse/utils/aws module · built in terraform-aws-utils unpinned terraform-aws-github-action-token-rotator main.tf:11

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）