What the agent does
A CI config is a list of commands somebody stopped reading years ago, so the agent reads it as a claim to be tested. In a project like bukosabino/ta, .circleci/config.yml is a version 2 file with six jobs. test_py36 is a YAML anchor, and test_py35, test_py37 and test_py38 reuse it with <<: *test-template and a different circleci/python image. Two more jobs, coverage and doc, run on the 3.7 image. The build workflow at the bottom starts only test_py36, coverage and doc; the other three test jobs are commented out, one with the note not working yet. The repository has no .github/workflows directory at all, and the first line of README.md is a CircleCI badge.
The translation itself is mechanical. The anchor and its three copies become one test job with a python-version matrix, each docker image becomes actions/setup-python, checkout becomes actions/checkout, and the working_directory and the hand-made virtual environment go away because a runner job starts clean. What takes judgment is that the file cannot be translated as written. The only enabled test job targets Python 3.6, and requirements-test.txt cannot install there: it includes pandas==1.3.5, which requires Python 3.7.1, and black==23.10.1, which requires 3.8. GitHub's runners no longer offer Python 3.6 on current Ubuntu images either. The agent reads those bounds from PyPI and from the actions/python-versions manifest and builds the matrix from versions on which the file can install: 3.8, 3.9 and 3.10.
Then it runs every step in the sandbox on those versions before writing them into a workflow. The test step, python -m unittest discover, passes all 134 tests on 3.8 and 3.10. The lint step does not: pycodestyle --max-line-length=119 ta exits 1 on five E203 reports, the slice spacing Black produces, so the isort command chained after it with && never runs. That isort call would fail on its own with a current release, since --recursive is no longer an option. Neither tool is named in a requirements file; both arrive as dependencies of prospector. The coverage commands pass and report 98 percent. The docs job fails at import: Sphinx==2.2.1 needs pkg_resources, which current setuptools no longer ships.
One line needs more than translation. The coverage job exports COVERALLS_REPO_TOKEN with the token written in the file. The agent replaces it with ${{ secrets.COVERALLS_REPO_TOKEN }}, never copies the value into the workflow or the pull request, and says that the old token is in git history and should be rotated. It finishes by running actionlint on the new workflow, swapping the README badge, and leaving .circleci/config.yml in place until the maintainers have seen a run.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate this repository's CI from CircleCI to GitHub Actions. Read .circleci/config.yml in full, including anchors, aliases, commented-out jobs and the workflows section, and list every job with its image, its steps, and whether a workflow starts it. Read every file the steps install from or run. For each job, work out which language versions its dependencies can install on by reading Requires-Python on PyPI for each pinned package, and which versions GitHub's runners offer; build the matrix from versions that satisfy both, and say which CircleCI versions were dropped and why. Before writing a step into a workflow, run its commands here on each matrix version and record pass or fail with the first error line. Translate every step faithfully, including ones that fail: do not fix lint errors, change tool versions or delete a failing step, but list each failure, whether it is caused by the migration or was already there, and the smallest fix. Write one workflow under .github/workflows with a top-level permissions block limited to contents: read, a matrix in place of copied jobs, and dependency caching keyed on the requirement files. Replace any credential written in the CircleCI file with a reference to a repository secret of the same name; never print or copy its value, and tell me it must be rotated and added as a secret. Run actionlint on the result. Update the README badge. Leave .circleci/config.yml in place and say so. Open a pull request whose description has a table of old job, new job, versions, and expected result per step.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request with one new file, .github/workflows/ci.yml, and a one-line change to the README badge. The workflow has three jobs where CircleCI had six: test with a Python matrix, coverage and doc. It passes actionlint, declares permissions: contents: read, and caches pip downloads keyed on the requirement files.
The description is a table a maintainer can check against the first Actions run. Each row is a step, with the command, the versions it was tried on in the sandbox and the result. For a repository like the one above the table predicts a red build and says exactly where: the lint step on every version and the docs build, both for reasons that predate the migration, with a proposed fix for each as a separate follow-up. A green install and test step on three Python versions is the part the migration itself is responsible for.
Two actions are left to a person, stated at the top. Add COVERALLS_REPO_TOKEN as a repository secret after rotating it, because a secret is a repository setting and not a file, and the old value is public in history. And delete .circleci/config.yml and disconnect the project in CircleCI once the new workflow has run, so two systems do not report on the same commit.
Run it on every repository still on CircleCI
This is a job someone hands off once per repository. A developer sends this body to POST /o/{org}/sessions with a request_id that is a UUID made for the job and carries on with other work; the pull request is on the session when the run completes. When the first Actions run disagrees with the table, a follow-up to POST /o/{org}/sessions/{id}/messages with the failing log wakes the same sandbox, where every Python version is already installed.
An organisation leaving CircleCI sends the same body for each repository from a script, with a request_id that is a UUID v5 of the repository's full name. A key runs a limited number of sessions at once and queues the others, so the script needs no pacing, and the key's webhook_url receives run.completed for each run it started. Sorting the returned tables by predicted result shows which repositories will be green on day one.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A translated workflow is a guess until its commands have run. The usual way to find out is to push, wait for the runner, read the log, and push again, once per mistake. In its own sandbox the agent installs each Python version, runs every step on each, and learns in one pass which failures are real, which are old, and which the new file introduced. Every command and its output is kept in the transcript at GET /o/{org}/sessions/{id}/messages, so the table in the pull request can be checked line by line.
It also keeps a credential out of the wrong places. The agent reads the old config inside the sandbox and writes a secret reference in its place; the value does not need to pass through a chat window or a laptop clipboard on the way.
Frequently asked questions
Will the new workflow be green on the first run?
Only if the old pipeline's commands still work, and the agent tells you before you merge. It runs each step in the sandbox and reports the result per version. In bukosabino/ta the install and test steps pass and the lint and docs steps fail for reasons unrelated to the migration.
What happens to CircleCI contexts and environment variables?
Values stored in CircleCI's project settings or contexts are not in the repository, so the agent cannot read them. It lists every variable the config references and writes each as a secrets reference; you create the secrets in the repository settings. A value committed in the config file is treated as leaked and flagged for rotation.
Does it convert orbs?
An orb is a packaged set of steps, so the agent replaces each use with the action or the plain commands that do the same work, and names the mapping in the pull request. The fixture above uses no orbs. Where no equivalent action exists, the step is written out as shell commands.
Why keep steps that fail?
Because deleting them would hide what the pipeline was meant to check. A migration that also fixes lint rules and upgrades the docs toolchain is three changes in one diff. The agent keeps the migration faithful and lists each fix as its own follow-up, which you can hand back as a second request.
More jobs like this: Hand off a long task
- Migrate a Click CLI to Typer (Click)
- Migrate a Node.js App from CommonJS to ESM (Node.js)
- Migrate a Create React App Project to Vite (Create React App)
- Replace dotenv With Node's --env-file Flag in an Express App (dotenv)
- Migrate Enzyme Tests to React Testing Library (Enzyme)
- Migrate From ESLint and Prettier to Biome (ESLint)