migrate-from-gha

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Quick Reference

快速参考

Read the cheat sheet before starting: GHA Cheat Sheet

开始前请阅读速查表：GHA速查表

Migration Procedure

迁移步骤

You are migrating a GitHub Actions workflow to RWX. Follow these steps exactly.

你正在将GitHub Actions工作流迁移至RWX，请严格遵循以下步骤操作。

Step 1: Read the source workflow

步骤1：读取源工作流

Read the GitHub Actions workflow file at

$ARGUMENTS

. If no path is provided, look for

.github/workflows/

and list the available workflow files for the user to choose from.

读取位于

$ARGUMENTS

的GitHub Actions工作流文件。如果未提供路径，则查找

.github/workflows/

目录并列出可用的工作流文件供用户选择。

Step 2: Analyze the workflow structure

步骤2：分析工作流结构

Identify:

All jobs and their
```
needs:
```
dependencies
All steps within each job
Triggers (
```
on:
```
events)
Secrets referenced (
```
${{ secrets.* }}
```
)
Environment variables (
```
env:
```
blocks at workflow, job, and step level)
Matrix strategies
Services
Composite action references (
```
uses: ./.github/actions/*
```
)
Reusable workflow calls (
```
uses: org/repo/.github/workflows/*
```
)
Artifact upload/download steps
Cache steps (these will be removed — RWX handles caching natively)

Before continuing, tell the user what you found: how many jobs, the dependency graph between them, which triggers are configured, and anything notable (matrix strategies, services, composite actions, reusable workflows). Keep it brief — a few sentences, not a full listing.

识别以下内容：

所有任务及其
```
needs:
```
依赖关系
每个任务中的所有步骤
触发器（
```
on:
```
事件）
引用的密钥（
```
${{ secrets.* }}
```
）
环境变量（工作流、任务和步骤级别的
```
env:
```
块）
矩阵策略
服务
复合动作引用（
```
uses: ./.github/actions/*
```
）
可复用工作流调用（
```
uses: org/repo/.github/workflows/*
```
）
制品上传/下载步骤
缓存步骤（这些将被移除——RWX原生支持缓存功能）

在继续操作前，告知用户你发现的内容：任务数量、任务间的依赖关系图、配置的触发器，以及任何值得注意的内容（矩阵策略、服务、复合动作、可复用工作流）。请保持简洁，只需几句话，无需完整列表。

Step 3: Follow local composite action references

步骤3：处理本地复合动作引用

For steps using

uses: ./.github/actions/foo

Read that action's
```
action.yml
```
Inline its logic into the translated RWX config

For cross-repo references (

uses: org/repo@ref

Add a
```
# TODO:
```
comment explaining what the action does and that the user needs to translate it manually or find an RWX package equivalent

Tell the user which composite actions you inlined and which cross-repo references will need TODO comments.

对于使用

uses: ./.github/actions/foo

的步骤：

读取该动作的
```
action.yml
```
文件
将其逻辑内联到转换后的RWX配置中

对于跨仓库引用（

uses: org/repo@ref

）：

添加
```
# TODO:
```
注释，说明该动作的功能，并提示用户需要手动转换或寻找对应的RWX包替代

告知用户哪些复合动作已被内联，哪些跨仓库引用需要添加TODO注释。

Step 4: Use MCP tools if available

步骤4：使用MCP工具（如有可用）

MCP tools specific to this migration are not yet available, so for now you can skip this step.

目前暂无针对此迁移的专属MCP工具，因此可跳过此步骤。

Step 5: Apply RWX optimization rules

步骤5：应用RWX优化规则

Fetch the full reference documentation now. Read these reference files and then fetch their contents:

RWX Reference
GHA-to-RWX Mapping

This is the core of the migration. Do NOT produce a 1:1 mapping. Apply the optimization rules from the reference documentation — including DAG decomposition, content-based caching, package substitution, trigger mapping, secret mapping, and environment variable translation.

Before writing the file, tell the user your planned DAG structure: which tasks you'll create, what runs in parallel vs sequentially, and any notable optimization decisions (packages substituted, caches removed, jobs decomposed). This lets the user course-correct before you write the config.

立即获取完整的参考文档，阅读以下参考文件并获取其内容：

RWX参考文档
GHA到RWX映射文档

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

在编写文件前，告知用户你规划的DAG结构：将创建哪些任务，哪些任务并行运行、哪些顺序运行，以及任何值得注意的优化决策（替换的包、移除的缓存、分解的任务）。这能让用户在你编写配置前进行方向校正。

Step 6: Write the output

步骤6：生成输出文件

Write the generated RWX config to

.rwx/<name>.yml

, where

<name>

is derived from the source workflow filename (e.g.,

ci.github.yml

→

.rwx/ci.yml

Structure the file in this order:

```
on:
```
triggers
```
base:
```
image and config
```
tool-cache:
```
(if needed)
```
tasks:
```
array, ordered by DAG level (independent tasks first, then their dependents)

将生成的RWX配置写入

.rwx/<name>.yml

，其中

<name>

源自源工作流文件名（例如：

ci.github.yml

→

.rwx/ci.yml

）。

文件结构需遵循以下顺序：

```
on:
```
触发器
```
base:
```
镜像和配置
```
tool-cache:
```
（如有需要）
```
tasks:
```
数组，按DAG层级排序（独立任务优先，然后是依赖任务）

Step 7: Validate

步骤7：验证

After writing the file, validate the generated config:

rwx lint .rwx/<name>.yml

If there are diagnostics:

Read the diagnostic messages
Fix the issues in the generated config
Re-check diagnostics after each fix until the file is clean

Common issues the validator will catch:

Invalid YAML structure
Unknown task keys or properties
Outdated package versions (the validator will suggest updates)
Missing required fields

You can also initiate test runs locally without pushing the code. See

rwx run --help

for documentation.

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

rwx lint .rwx/<name>.yml

如果存在诊断问题：

读取诊断消息
在生成的配置中修复问题
每次修复后重新检查诊断，直到文件无问题

验证器常见的检查项：

无效的YAML结构
未知的任务键或属性
过时的包版本（验证器会建议更新）
缺失必填字段

你也可以在本地启动测试运行，无需推送代码。查看

rwx run --help

获取文档说明。

Step 8: Automated review

步骤8：自动化审查

Tell the user: "Launching a review of the migration. This reviewer has no knowledge of the decisions made during migration — it will read both files from scratch and check for gaps."

First, read the reference docs and the review procedure so you can include them:

Fetch the contents from the URLs in RWX Reference and GHA-to-RWX Mapping
Read the review procedure at review-gha-migration/SKILL.md

If you have the ability to spawn a subagent (e.g., Claude Code's Task tool), do so for an independent review with fresh context. Spawn the reviewer using a general-purpose subagent with a prompt that includes:

The full contents of the review procedure (from the SKILL.md you just read)
The full contents of both reference docs (from the fetches you just ran)
The file paths to review

Structure the prompt like this:

You are reviewing an RWX config that was migrated from a GitHub Actions workflow.
Your job is to catch problems the implementer missed. Approach this as a skeptical
reviewer, not as someone defending prior work.

告知用户："启动迁移审查。此审查者对迁移过程中做出的决策一无所知——它将从头读取两个文件并检查是否存在遗漏。"

首先，读取参考文档和审查步骤，以便将其包含在内：

从RWX参考文档和GHA到RWX映射文档中的URL获取内容
读取review-gha-migration/SKILL.md中的审查步骤

如果你具备生成子代理的能力（例如Claude Code的Task工具），请生成一个独立的子代理进行独立审查，确保上下文全新。使用通用子代理并提供包含以下内容的提示词：

刚刚读取的SKILL.md中的完整审查步骤
刚刚获取的两份参考文档的完整内容
待审查的文件路径

提示词结构如下：

你正在审查一个从GitHub Actions工作流迁移而来的RWX配置。
你的任务是发现实现者遗漏的问题。请以持怀疑态度的审查者身份进行，而非为之前的工作辩护。

Review Procedure

审查步骤

<在此处粘贴SKILL.md中的审查步骤>

RWX Reference

RWX参考文档

<在此处粘贴RWX参考文档>

GHA-to-RWX Mapping Reference

GHA到RWX映射参考文档

<在此处粘贴GHA映射文档>

Files to Review

待审查文件

Source GHA workflow: <path from step 1>
Generated RWX config: <path from step 6>


Replace the placeholders with the actual content and paths.

**Otherwise**, perform the review inline by reading and following the review procedure from
[review-gha-migration/SKILL.md](../review-gha-migration/SKILL.md).

Wait for the review to complete. If the review found blocking issues, fix them before
continuing.

源GHA工作流：<步骤1中的路径>
生成的RWX配置：<步骤6中的路径>


将占位符替换为实际内容和路径。

**如果不具备该能力**，则通过读取并遵循[review-gha-migration/SKILL.md](../review-gha-migration/SKILL.md)中的审查步骤，在本地完成审查。

等待审查完成。如果审查发现阻塞性问题，请在继续前修复这些问题。

Step 9: Summarize

步骤9：总结

Provide a final summary to the user that covers both the migration and the review:

What the original workflow did
How the RWX version is structured differently (and why it's better)
The DAG shape: which tasks run in parallel vs sequentially
The review verdict and any issues found (or confirmation that it passed)
Any
```
# TODO:
```
items that need manual attention
Secrets that need to be configured in RWX Cloud
Estimated parallelism improvement (e.g., "6 sequential steps → 3-level DAG")

Let the user know they can re-run the review independently at any time with

/rwx:review-gha-migration

向用户提供涵盖迁移和审查的最终总结：

原工作流的功能
RWX版本的结构差异（以及更优的原因）
DAG形态：哪些任务并行运行、哪些顺序运行
审查结论及发现的问题（或确认通过审查）
需要手动处理的
```
# TODO:
```
项
需要在RWX Cloud中配置的密钥
预估的并行性提升（例如："6个顺序步骤 → 3层级DAG"）

告知用户他们可随时通过

/rwx:review-gha-migration

独立重新运行审查。