> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate an existing Go app to Forge with Move to Forge

> Port a Go codebase into a new Forge project with the Move to Forge workflow: approve a plan, then agents port it one component at a time behind green gates.

You point the built-in **Move to Forge** workflow at an existing Go codebase. It plans the port, waits for your approval, then builds a new [Forge](https://docs.reliantlabs.io/forge/overview.md) project beside the original and ports your code into it one component at a time. Each component has to pass `forge generate`, `forge lint --contract`, `go build` and your tests before the next one starts. Your source repository is left as it was, and the cutover stays with you.

Use it when you want your app on Forge's Go stack: Connect RPC, schema from SQL migrations, typed config and the generated store. If you only want to deploy an app as it is, in any language, [adopt it from its Dockerfile](https://docs.reliantlabs.io/guides/forge/bring-existing-app-any-language.md) instead. That path changes no code and takes about an hour.

## Before you begin

* The `reliant` CLI, v1.21 or later, signed in ([Sign in and tokens](https://docs.reliantlabs.io/cli/sign-in.md)), with a [machine](https://docs.reliantlabs.io/guides/machines/connect-computer-as-machine.md) that holds the source repository. The workflow uses the Forge built into Reliant (v1.6.1 or later) and pins it in the new project.
* A Go codebase in git, with tests that pass. This example is a 340-line `net/http` API over a Postgres `tasks` table, with a `Store` interface, five JSON routes and a table test.
* Model credit. A run takes hours on a flagship model, not minutes. In an organization, `reliant workflow funding` shows whether a run asks before it uses your own AI account.

**1. Start the workflow**

In the app, choose **Move to Forge** in a new chat's workflow selector and describe what you want. From the terminal, the built-in's id is `forge-migrate`:

```bash terminal theme={null}
cd tasks-api
reliant workflow run forge-migrate --project-path "$PWD" -i ask=false \
  -m "Move this tasks API to Forge. Keep the same tasks table and the same five operations; a Connect RPC API in place of the hand-written JSON routes is fine. No frontend needed."
```

```text Output theme={null}
Workflow "forge-migrate" triggered
  Chat/Execution ID: 5ea117c0-b2ce-4ea6-9e9e-80d2d6d72170
```

| Input | Default | What it does |
| - | - | - |
| `model` | a flagship model | Model for every phase |
| `ask` | on | Pause for your review between phases. The plan approval happens either way |
| `working_directory` | `.` | Root of the source repository |
| `target_directory` | empty | Where the new project goes. Empty lets the planner pick a sibling directory; it never ports in place |
| `test_command` | `go test ./...` | The test gate, run inside the new project |

For an app that is not written in Go, the planner first recommends adopting it from its Dockerfile, and ports only if you still ask for it.

**2. Read the plan, then approve it**

The planner reads the code first and asks you only what the code cannot answer. It then writes two files into the source repository and stops at **Approve the migration plan?**:

* `MIGRATION_PLAN.md`: the source inventory, the target shape, the components in port order, the parity bar and the deferred list
* `.forge-migrate/target`: the absolute path of the new project

```markdown MIGRATION_PLAN.md (excerpt) theme={null}
| Source route | Behavior | forge RPC (`tasks.v1.TasksService`) |
| `GET /tasks?done=` | Lists every task ordered by `id` ... | `ListTasks`, with `optional bool done` |
| `POST /tasks` | Trims `title`, requires 1–200 chars ... | `CreateTask` |

### 1. `tasks-schema` (db). Source: `db/schema.sql`
### 2. `tasks-service` (service). Source: `internal/tasks/handler.go`, ...
### 3. `server-composition` (binary). Source: `main.go`
```

Approve it from the [Inbox](https://docs.reliantlabs.io/automations/overview.md#the-inbox) or from the run under **Workflows → Runs**. Edit the plan first if a mapping is wrong. If you deny it, nothing is scaffolded, and the plan stays on disk for the next run.

**3. Follow the port**

After approval the workflow runs [Get It Right](https://docs.reliantlabs.io/guides/get-it-right.md) loops: one for the scaffold and green baseline, one per component in dependency order, and one to converge. A separate reviewer passes or fails each loop.

```bash terminal theme={null}
reliant workflow watch 5ea117c0-b2ce-4ea6-9e9e-80d2d6d72170
reliant workflow status 5ea117c0-b2ce-4ea6-9e9e-80d2d6d72170
```

```text Output (trimmed) theme={null}
  Status:    COMPLETED
  Outcome:   ✓ SUCCESS
NODE THREADS (child workflows)
  builtin://forge-migrate  [COMPLETED]  2m1s
  builtin://forge-migrate  [COMPLETED]  43m50s
  builtin://forge-migrate  [COMPLETED]  3m16s
  builtin://forge-migrate  [COMPLETED]  55m10s
  builtin://forge-migrate  [COMPLETED]  11m0s
  builtin://forge-migrate  [COMPLETED]  11m34s
```

The threads are, in order: the plan, the scaffold and baseline, the three components (`tasks-schema`, `tasks-service`, `server-composition`) and the converge step. This 340-line app took about two hours after approval. The run ends with **Migration Complete**, which names the new project and points at the cutover checklist.

**4. Check the new project**

The project is in the directory recorded in `.forge-migrate/target`. Run the same gates the workflow ran:

```bash terminal theme={null}
cd "$(cat tasks-api/.forge-migrate/target)"
go build ./...
reliant forge lint --quiet
task test:short -- ./internal/handlers/tasks/...
```

```text Output theme={null}
✅ All 25 gating linters passed.
ok  	github.com/example/tasks-api-next/internal/handlers/tasks	0.793s
```

In the source repository, `git status` lists only new files: the two plan files, and the `.reliant/` folder and `reliant.md` that registering the project added. No source file changed.

**5. See what was kept and what was rewritten**

`MIGRATION_PLAN.md` accounts for every source file. For this app:

| Source | In the Forge project |
| - | - |
| `db/schema.sql`, run at every boot | Kept byte for byte as `db/migrations/00001_create_tasks.up.sql`, applied by the migrator. On a database that already has the table, the first `migrate up` records version 1 and keeps the rows |
| Validation and not-found rules in `handler.go` | Kept as behavior in `internal/handlers/tasks/handlers_crud.go`: trimmed title of 1–200 bytes, `id` above 0, `NotFound` |
| `pgStore` and its raw SQL | Replaced by the store Forge generates from the applied schema |
| The five JSON routes | Rewritten as five Connect RPCs in `proto/services/tasks/v1/tasks.proto`, public like the source |
| `main.go`, `os.Getenv("DATABASE_URL")`, `PORT` | Replaced by the scaffolded server and typed config in `proto/tasks_api_next/config/v1/config.proto`. The dev database URL moved to `deploy/kcl/dev/main.k` |
| `GET /healthz` | Still `/healthz`, plus a new readiness probe at `/readyz` |
| `handler_test.go` | Rewritten against real Postgres in `handlers_crud_test.go`, plus an end-to-end `e2e/tasks/parity_test.go` that calls each RPC with no credentials |

Choices it could not settle from the code stay as open questions with the default it used, such as pagination on `ListTasks` and the wire type of `due_date`.

**6. Cut over**

The plan ends with a cutover checklist, and the workflow performs none of it. The new project's git repository has no commits yet. Commit it, rehearse the migration against a copy of your production database, move your clients to the Connect API, then deploy ([Deploy a Go API with managed Postgres](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md)). The module path keeps its `-next` suffix until the last step, so the old and new code build side by side until you switch.

## What this does not do

* **It does not change your source repository**, beyond writing `MIGRATION_PLAN.md` and `.forge-migrate/target`.
* **It does not commit, deploy or cut over.** The new project, the module rename and the switch of traffic are yours.
* **It does not keep your old API shape.** Routes become Connect RPCs, field names follow proto JSON, and errors become Connect codes. There is no REST shim, so clients change with the server.
* **It stops at the first component that cannot go green**, rather than building the next one on a broken base.
* **It is not the way to bring a non-Go app.** For those, [adopt the app from its Dockerfile](https://docs.reliantlabs.io/guides/forge/bring-existing-app-any-language.md).

## Troubleshooting

> [accordion] Migration Stopped
>
> The plan was denied or the approval timed out after 24 hours. Nothing was scaffolded. Edit `MIGRATION_PLAN.md` and start the workflow again.

> [accordion] Migration Did Not Fully Pass
>
> A gate stayed red after its repair attempts. `MIGRATION_PLAN.md` records how far the port got and what failed. Fix that component in the new project, or change the plan, and run the workflow again.

> [accordion] Stopped — External Issue
>
> A phase hit a tooling or environment problem, such as a missing `buf` or `go` on the machine, and escalated rather than working around it. The message above it names the problem.

## Next steps

> [card] [Bring an existing app](https://docs.reliantlabs.io/guides/forge/bring-existing-app-any-language.md)
>
> Deploy an app in any language from its Dockerfile, with no rewrite.

> [card] [Build an app from one prompt](https://docs.reliantlabs.io/guides/forge/build-app-from-one-prompt.md)
>
> Start a new Forge project from a description instead.

> [card] [Generated code and yours](https://docs.reliantlabs.io/forge/concepts/generated-vs-yours.md)
>
> Which files in the new project Forge regenerates and which you own.

> [card] [Deploy a Go API](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md)
>
> Ship the ported project with a managed Postgres.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.