Migration Wizard
Migrate your workflows to Monk CI runners from the dashboard - select repositories, pick runners per job, and open the pull requests.
The Migration Wizard scans your workflow files, suggests a Monk CI runner for every job, and opens one pull request per repository with the runs-on changes. Use it instead of editing your YAML by hand.
The wizard opens pull requests. It never commits to your default branch - review and merge each PR yourself.
Before You Start
- The Monk CI GitHub App must be installed on your organization, with access to the repositories you want to migrate. See QuickStart.
- Nothing is changed on GitHub until you click Generate Pull Request in step 3.
Open the Wizard
In your Monk CI dashboard sidebar, click Migration Wizard at the top.
Press Esc or click the close icon to leave at any point before you generate pull requests.
Migrate Your Workflows
Repository
Select the repositories you want to migrate. Use the search box to filter the list, or select all at once.
If a repository is missing, click Adjust permissions here to grant the Monk CI GitHub App access to it on GitHub, then reopen the wizard.
Click Next.
Runners
The wizard reads the workflow files in your selected repositories and lists every job it finds, grouped by repository and workflow.
Each job is pre-selected with a suggested Monk CI runner:
| Current runner | Pre-selected as |
|---|---|
ubuntu-latest, other Linux, or self-hosted | monkci-ubuntu-latest |
A label encoding a core count, such as ubuntu-latest-4-cores | The matching Monk CI size |
| Windows or macOS | Nothing - pick a runner yourself, or leave the job unselected |
Change any job's runner from its dropdown, or clear it to leave that job on its current runner. The footer shows how many jobs will be migrated.
Click Next.
Check the 'No GitHub runners detected' list
Expand this section to see jobs the wizard could not read - typically a runs-on built from a matrix, a dynamic expression, or a runner group - plus any workflow it failed to inspect. These are not migrated. Update them using Manual Migration.
Pull Request
Review the summary, then click Generate Pull Request. Monk CI opens one pull request per repository, containing every job you selected in that repository.
Each repository reports one of these outcomes:
| Outcome | What it means | What to do |
|---|---|---|
| Pull request opened | The runs-on values were changed. | Review and merge the PR. |
| Already on Monk CI | The jobs already use the target runner. | Nothing. |
| Skipped | The job has no runs-on to change, or no longer exists. | Nothing - retrying will not help. |
| Failed | A real error blocked the migration. | Click Retry failed. |
Click Done when every repository has settled.
After the Wizard
- Open each pull request from the wizard, or from your repository on GitHub.
- Review the
runs-onchanges. - Merge. The next workflow run uses the Monk CI runner.
To revert, change runs-on back to your previous runner and push. No other changes are needed.
Choosing a Runner Size
| Tag | vCPU | RAM |
|---|---|---|
monkci-ubuntu-latest | 32 | 124 GB |
monkci-ubuntu-24.04-2 | 2 | 7 GB |
monkci-ubuntu-24.04-4 | 4 | 15 GB |
monkci-ubuntu-24.04-8 | 8 | 31 GB |
monkci-ubuntu-24.04-16 | 16 | 62 GB |
monkci-ubuntu-24.04-32 | 32 | 124 GB |
Use monkci-ubuntu-latest for the fastest builds. If you need a fixed size, start with monkci-ubuntu-24.04-4 - it matches the default GitHub-hosted runner.