migrate-from-gha

Migration Procedure

You are migrating a GitHub Actions workflow to RWX. Follow these steps exactly. Do NOT use TodoWrite — this procedure is your task list.

Step 1: Read and analyze the source workflow

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.

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, reusable workflow calls, artifact upload/download steps, and cache steps (these will be removed — RWX handles caching natively).

For steps using uses: ./.github/actions/foo, read that action's action.yml and 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 what you found: how many jobs, the dependency graph between them, which triggers are configured, which composite actions you inlined, and which cross-repo references will need TODO comments. Keep it brief.

Then write a migration inventory to .rwx/.migration-inventory.md. This file is a structured checklist that will be used during the review step to verify nothing was dropped. Keep it compact — names and keys only, not full details:

## 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)

Omit any sections that have no entries.

Step 2: Write the optimized RWX config

Fetch the full reference documentation now. Do NOT use WebFetch — it summarizes and drops critical details. Instead, use Bash to run rwx docs pull for each doc and read stdout directly. Run all three in a single turn as parallel Bash calls:

• rwx docs pull /docs/rwx/migrating/gha-cheat-sheet — action-to-package mapping and DAG pattern (read this first)
• rwx docs pull /docs/rwx/migrating/rwx-reference — full RWX config syntax
• rwx docs pull /docs/rwx/migrating/gha-reference — GHA-to-RWX concept mapping

If you encounter a question not covered by these references, use rwx docs search "<query>" to find the relevant documentation page, then rwx docs pull the result.

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.

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:

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

After writing the file, validate the generated config:

rwx lint .rwx/<name>.yml

If there are diagnostics, fix the issues and re-check until the file is clean. You can also initiate test runs locally without pushing the code — see rwx run --help for documentation.

Step 3: Review and summarize

Tell the user: "Now reviewing the migration to check for gaps."

Re-read .rwx/.migration-inventory.md (written in Step 1) and the generated RWX config. Use the inventory as your checklist — verify every item in it is accounted for in the config. This is more reliable than working from memory of the source workflow.

Then follow the review procedure from review-gha-migration/SKILL.md. You already have the reference docs from Step 2 — do not re-fetch them.

If the review found blocking issues, fix them before continuing.

Then 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 /review-gha-migration.