mcpField
M
migrate-from-gha

migrate-from-gha

github.com/rwx-cloud云与 DevOps368 次安装1 周前更新
代码仓库

关于 migrate-from-gha

migrate-from-gha 是将 GitHub Actions 工作流迁移到 RWX 的技能，涵盖工作流分析、配置生成、验证和清单式审查。

主要功能

  1. 01分析任务、依赖关系与触发条件
  2. 02生成优化的 RWX 任务图
  3. 03记录迁移清单
  4. 04检查并审查生成的配置

适用场景

  1. 01将现有 GitHub Actions 工作流迁移到 RWX
  2. 02核对工作流步骤和密钥是否纳入迁移
  3. 03识别可并行任务与缓存机会

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rwx-cloud/skills --skill migrate-from-gha

安装后在 Claude Code 中输入/migrate-from-gha确认已加载。

详细介绍

迁移流程

你正在将 GitHub Actions 工作流迁移到 RWX。请严格按照以下步骤操作。 请勿使用 TodoWrite — 本流程就是你的任务清单。

步骤 1：读取并分析源工作流

读取 $ARGUMENTS 指定的 GitHub Actions 工作流文件。如果未提供路径， 请查找 .github/workflows/，并列出可供用户选择的工作流文件。

识别所有作业及其 needs: 依赖项、每个作业中的所有步骤、触发器（on: 事件）、引用的密钥（${{ secrets.* }}）、环境变量（工作流、作业和步骤级别的 env: 块）、矩阵策略、服务、复合操作引用、可复用工作流调用、工件上传／下载步骤，以及缓存步骤（这些步骤会被移除 — RWX 原生处理缓存）。

对于使用 uses: ./.github/actions/foo 的步骤，读取该操作的 action.yml，并将其逻辑内联到转换后的 RWX 配置中。对于跨仓库引用（uses: org/repo@ref），添加 # TODO: 注释，说明该操作的用途，以及用户需要手动迁移或查找等效的 RWX 软件包。

告知用户你发现的内容：作业数量、作业间的依赖关系图、已配置的触发器、已内联的复合操作，以及哪些跨仓库引用需要添加 TODO 注释。简要说明即可。

然后将迁移清单写入 .rwx/.migration-inventory.md。此文件是结构化检查清单，将在审查步骤中用于确认没有遗漏任何内容。保持精简 — 仅列出名称和键，不写完整详情：

## Jobs

- lint (needs: [])
- test (needs: [])
- build (needs: [lint, test])
- deploy (needs: [build], if: github.ref == 'refs/heads/main')

## Secrets

- DEPLOY_TOKEN

## Environment Variables

- DATABASE_URL (job: test)

## Services

- postgres (job: test)

## Matrix Strategies

- go-version: [1.22, 1.26] (job: test)

## Notable Steps

- golangci-lint-action (job: lint)
- upload-artifact coverage.out (job: test)
- download-artifact app-binary (job: deploy)

省略没有条目的部分。

第 2 步：编写优化后的 RWX 配置

现在获取完整的参考文档。不要使用 WebFetch——它会总结内容并遗漏关键细节。请改用 Bash，对每份文档运行 rwx docs pull，并直接阅读标准输出。在同一轮中并行调用 Bash，运行以下三个命令：

  • rwx docs pull /docs/rwx/migrating/gha-cheat-sheet — 操作到包的映射和 DAG 模式（先阅读此文档）
  • rwx docs pull /docs/rwx/migrating/rwx-reference — 完整的 RWX 配置语法
  • rwx docs pull /docs/rwx/migrating/gha-reference — GHA 到 RWX 的概念映射

如果遇到这些参考文档未涵盖的问题，请使用 rwx docs search "<query>" 查找相关文档页面，然后对结果运行 rwx docs pull。

这是迁移的核心。不要进行一对一映射。请应用参考文档中的优化规则，包括 DAG 分解、基于内容的缓存、包替换、触发器映射、密钥映射和环境变量转换。

如果源工作流使用 on: workflow_run（在另一个工作流完成后触发），请将其转换为 RWX 嵌入式运行——即嵌套在父工作流配置中的运行配置。请查阅参考文档了解嵌入式运行语法。此情况下不要改用 dispatch 触发器或条件式 push 触发器。

不仅要关注不同 GHA 作业之间的并行机会，也要寻找单个 GHA 作业内的并行机会。如果单个作业包含多个相互独立的步骤（例如，"lint" 作业中的 eslint、prettier 和 openapi 验证），请将它们拆分为可并行运行的独立 RWX 任务，而不是合并到一个顺序执行的 run: 块中。

将安装和构建拆分为不同任务。如果 GHA 作业先运行 npm ci（或类似命令），随后执行构建步骤（例如，为共享包运行 npm run build），则应将其拆分为两个独立的 RWX 任务，以便单独缓存构建。如果多个 GHA 作业中出现相同的构建命令，请在 DAG 中生成一个共享构建任务，而不是重复创建。

如果源工作流包含 docker build 步骤，请使用 AskUserQuestion 询问用户是否愿意改用 RWX OCI 镜像。请说明其中的权衡：OCI 镜像利用 RWX 的原生镜像构建功能，支持基于内容的缓存，且不依赖 Docker 守护进程，但需要采用 RWX 专属配置。请查阅速查表了解 OCI 镜像的详细信息。尊重用户的选择——如果用户希望保留 docker build，则直接进行转换。

将生成的 RWX 配置写入 .rwx/<name>.yml，其中 <name> 根据源工作流文件名确定（例如，ci.github.yml → .rwx/ci.yml）。

按以下顺序组织文件：

  1. on: 触发器
  2. base: 镜像和配置
  3. tool-cache:（如需要）
  4. tasks: 数组，按依赖深度排序（先列出无依赖任务，再列出其依赖任务）

写入文件后，验证生成的配置：

rwx lint .rwx/<name>.yml

如果有诊断信息，请修复问题并重新检查，直到文件无误。你也可以在本地启动测试运行，而无需推送代码——请参阅 rwx run --help 文档。

第 3 步：审核并总结

告知用户：“现在正在审核迁移，检查是否存在遗漏。”

重新阅读 .rwx/.migration-inventory.md（在第 1 步中编写）和生成的 RWX 配置。将清单用作检查表，确认其中的每一项都已纳入配置。与凭记忆回想源工作流相比，这种方式更可靠。

然后按照 review-gha-migration/SKILL.md 中的审核流程操作。第 2 步中已经获取了参考文档，不要重新获取。

如果审核发现阻塞性问题，请先修复再继续。

然后向用户提供最终总结，涵盖迁移和审核两方面：

  • 原始工作流的作用
  • RWX 版本的结构有何不同（以及为何更好）
  • DAG 形态：哪些任务并行运行，哪些按顺序运行
  • 审核结论及发现的问题（或确认审核通过）
  • 需要人工处理的任何 # TODO: 项
  • 需要在 RWX Cloud 中配置的密钥
  • 预计的并行度提升（例如，“6 个顺序步骤 → 3 个并行阶段”）

告知用户，他们可以随时使用 /review-gha-migration 独立重新运行审核。

评论

支持 Markdown