# Migrate a Python Project from CircleCI to GitHub Actions

Yes. The agent translates each job and step, runs every command first to learn which will pass, moves secrets out of the file, and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-circleci-to-github-actions/circleci/). Opens the console with this prompt ready to send, in a Project that has your repository.

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

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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](https://getrush.ai/run/migrate-click-to-typer/click/)
- [Migrate a Node.js App from CommonJS to ESM](https://getrush.ai/run/migrate-commonjs-to-esm/nodejs/)
- [Migrate a Create React App Project to Vite](https://getrush.ai/run/migrate-create-react-app-to-vite/create-react-app/)
- [Replace dotenv With Node's --env-file Flag in an Express App](https://getrush.ai/run/migrate-dotenv-to-env-file/dotenv/)
- [Migrate Enzyme Tests to React Testing Library](https://getrush.ai/run/migrate-enzyme-to-testing-library/enzyme/)
- [Migrate From ESLint and Prettier to Biome](https://getrush.ai/run/migrate-eslint-and-prettier-to-biome/eslint/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
