# Moving from Netlify

> Move a site from Netlify to Evolving Edge with ee-migrate: translate netlify.toml into _redirects, _headers and a GitHub Actions workflow that builds and deploys the site, and read the report of what carried over and what didn't.

Source: https://docs.evolvingedge.ai/migrate-from-netlify/

`ee-migrate` reads your site's `netlify.toml` and writes the [`_redirects`](https://docs.evolvingedge.ai/redirects/) and [`_headers`](https://docs.evolvingedge.ai/headers/) files Evolving Edge reads, and a GitHub Actions workflow that builds and deploys your site on every push, as Netlify did. It tells you what it carried over, what it couldn't and why, and what is left for you to do.

It's part of the [`@evolving-edge/ee-cdn-cli`](https://docs.evolvingedge.ai/cli/) package. The workflow needs version 0.6.0 or later.

| Netlify setting | What happens |
|---|---|
| `[[redirects]]` with status 301, 302, 200 or 404, and `force` | Written to `_redirects` |
| `[[headers]]` | Written to `_headers` |
| `[build.processing.html] pretty_urls` | Written to `_redirects` as the [clean URLs](https://docs.evolvingedge.ai/redirects/#clean-urls) setting |
| `[build] command`, `base`, `publish` and `environment` | Written to a GitHub Actions workflow that builds and deploys the site. See [The deploy workflow](#the-deploy-workflow) |
| `[context.production]` | Used over `[build]`, as Netlify does for production deploys |
| Everything else | Listed as not carried over, with the reason. See [What doesn't carry over](#what-doesnt-carry-over) |

## Before you begin

You need:

- **Node.js 22.12 or later.**
- **Windows (x64), macOS or Linux (x64 or arm64).**
- **Your site's source folder,** with its `netlify.toml`, in a git repository on GitHub.
- **A deploy token and your project ID,** from the portal. See [Deploy tokens](https://docs.evolvingedge.ai/cli/#deploy-tokens).

`ee-migrate` writes into your site's folder, and the workflow into your repository's `.github/workflows/` folder. Commit or back up your work first, so you can see exactly what it changed.

If you don't build on GitHub, add `--no-workflow`: you get the files without the workflow, and [build and deploy yourself](#deploy-without-the-workflow).

## 1. Run ee-migrate

In your site's folder, run:

```sh
npx --package=@evolving-edge/ee-cdn-cli ee-migrate
```

To run it on another folder, name it: `npx --package=@evolving-edge/ee-cdn-cli ee-migrate ./my-site`.

It needs no deploy token and doesn't publish anything. Like `ee-deploy`, it downloads the [packaging tool](https://docs.evolvingedge.ai/cli/#the-packaging-tool-and-its-lockfile) the first time, which does the translation.

The workflow goes to `.github/workflows/ee-deploy.yml` at the root of the git repository that holds the folder.

## 2. Read the report

For a Hugo site, the output looks like this:

```
ee-migrate: read netlify.toml (39 lines)
Wrote: .github/workflows/ee-deploy.yml (deploy workflow), _redirects (2 rule(s)), _headers (2 rule(s))
Deploy folder: public

Carried over: 8 of 11 settings

Dropped (3):
  netlify.toml:8  [context.deploy-preview]
      Deploy previews and branch deploys aren't available, so this context's settings aren't carried over.
  netlify.toml:20  /api/* https://api.example.com/:splat 200
      A 200 rule to another host is a proxy, which isn't supported.
  netlify.toml:25  /old-campaign / 410
      Status 410 isn't supported; a rule can use 301, 302, 200 or 404.

Needs you (4):
  1. Move _redirects and _headers into the folder your generator copies into public unchanged (public/ for Vite and Astro, static/ for Hugo, Gatsby and Docusaurus), so the build puts them in the deploy folder.
  2. Create what the workflow reads, in the repository's settings under Secrets and variables > Actions, or with GitHub's gh command: gh secret set EE_CDN_TOKEN (a deploy token from the portal); gh variable set EE_CDN_DOMAIN --body www.example.com (your site's domain); gh variable set EE_CDN_PROJECT_ID --body proj_... (your project's ID).
  3. Variables set in Netlify's dashboard aren't in netlify.toml. For each one your build needs, create a repository secret (gh secret set NAME) and add NAME: ${{ secrets.NAME }} to the env: list of the Build step in .github/workflows/ee-deploy.yml, and of Install dependencies too if installing needs it.
  4. Commit .github/workflows/ee-deploy.yml and push it to main: each push to main then builds and deploys the site. Netlify's production branch is set in its dashboard; if it isn't main, change branches: in the workflow.

Full report: /home/you/my-site/ee-migrate-report.json
```

- **Carried over** counts the settings now in `_redirects`, `_headers` or the workflow.
- **Changed** lists settings carried over in a different form, with what was written instead. A build variable that looks like a credential is listed here: see [Build variables](#build-variables).
- **Dropped** lists each setting that didn't carry over, with its line in `netlify.toml` and the reason. Nothing on this list changes how your site behaves here.
- **Handled elsewhere** lists settings that don't change what's deployed, such as `[dev]`. With `--no-workflow`, your build settings are listed here too.
- **Needs you** is what's left for you to do.

The same report is written as JSON to `ee-migrate-report.json`, one entry per setting. It names your build command and every rule, so it's kept out of the folder you deploy: when that folder is where the report would go, it's written to a temporary file instead, and the last line says where. The values of your build environment variables are never printed or written to the report. Their names are, since the workflow holds them anyway; with `--no-workflow`, neither is.

## 3. Put the files where your generator copies them

When your site has no build command, the files go straight into the folder you deploy, and there's nothing to move.

When it has one, the files go beside `netlify.toml`, because the build replaces the deploy folder. Move them into the folder your generator copies into its output unchanged:

| Generator | Move `_redirects` and `_headers` into |
|---|---|
| Astro, Vite, Qwik City | `public/` |
| VitePress | `docs/public/` (your source folder's `public/`) |
| Hugo, Docusaurus, Gatsby | `static/` |
| Eleventy | Any folder you pass through to the output |
| Jekyll | The site root, with `include: [_redirects, _headers]` in `_config.yml` |

If your site already has a `_redirects` or `_headers` file, `ee-migrate` adds the translated rules to it, after your own, and there's nothing to move. See [Running it again](#running-it-again).

## 4. Set up the workflow and push

1. **Create the deploy token secret and the two variables** the workflow reads, as **Needs you** shows. In your repository on GitHub, go to **Settings → Secrets and variables → Actions**, or use GitHub's `gh` command in your repository:

   ```sh
   gh secret set EE_CDN_TOKEN
   gh variable set EE_CDN_DOMAIN --body www.example.com
   gh variable set EE_CDN_PROJECT_ID --body proj_abc123
   ```

   `gh secret set` asks for the token, so it doesn't end up in your shell history. Your domain must be claimed for your project first. See [Custom domains](https://docs.evolvingedge.ai/custom-domains/).

2. **Create a repository secret for each credential** among your build variables, if **Needs you** lists any. See [Build variables](#build-variables).
3. **Add anything the workflow marks for you**, such as a tool it doesn't set up, or variables set in Netlify's dashboard.
4. **Commit and push.** Commit the workflow, the moved `_redirects` and `_headers`, and your other changes, then push to the branch the workflow names. Each push to that branch builds and deploys the site. You can also run it by hand from the repository's **Actions** tab.

When the workflow deploys, the rules in `_redirects` are checked again, now against your built site. A rule with status 200 or 404 must point at a file that's in it.

A rule that [redirects a whole domain](https://docs.evolvingedge.ai/redirects/#redirect-a-whole-domain) applies only on a domain claimed and bound to this site. **Needs you** names each one.

### Deploy without the workflow

With `--no-workflow`, build the site with the command from your `netlify.toml`, then deploy the output folder with [`ee-deploy`](https://docs.evolvingedge.ai/cli/):

```sh
hugo --gc --minify
npx @evolving-edge/ee-cdn-cli ./public --domain www.example.com --project proj_abc123
```

Set the variables from `[build.environment]`, and any set in Netlify's dashboard, where you build: your shell, or your CI's secrets and variables. For CI other than GitHub Actions, see [Deploying from GitHub Actions](https://docs.evolvingedge.ai/cli/#deploying-from-github-actions); any CI system works the same way.

## The deploy workflow

The workflow builds your site the way Netlify did for production deploys, then deploys it with the [GitHub Action](https://docs.evolvingedge.ai/cli/#the-github-action).

- **When it runs:** on every push to your repository's default branch, and by hand from the **Actions** tab. One deploy runs at a time; a newer push waits for the one before it.
- **Where it builds:** in `base`, which is relative to your repository's root, as on Netlify. With no `base`, it builds in the folder that holds `netlify.toml`.
- **What it deploys:** the `publish` folder. With a build command and no `publish` in `netlify.toml`, the deploy step finds your build's output folder itself; if Netlify's dashboard names a publish directory, add `directory:` with that folder to the deploy step.
- **Your domain, project and token:** read from the repository variables `EE_CDN_DOMAIN` and `EE_CDN_PROJECT_ID` and the secret `EE_CDN_TOKEN`. To write the domain or project into the workflow instead, give `--domain` or `--project`.

### Toolchains

- **Node.js** is set up when there's a build command and the site has a `package.json`, or the command runs `npm`, `npx`, `yarn`, `pnpm` or `node`. The version comes from `NODE_VERSION` in `netlify.toml`, then `.nvmrc` or `.node-version`, then `engines.node` in `package.json`, else Node 22, and **Needs you** says so.
- **Dependencies** are installed where your lockfile is, with the matching package manager: npm, Yarn or pnpm. A lockfile in a parent folder is used only when that folder is a workspace root. Netlify's `NPM_FLAGS`, `NPM_VERSION` and the Yarn and pnpm equivalents work as they did on Netlify.
- **Hugo** (extended) is installed at the version `HUGO_VERSION` gives, checked against Hugo's published checksums. With no `HUGO_VERSION`, the latest Hugo is installed, and **Needs you** says to pin it.
- **Any other tool** the build uses, such as make, Python, Ruby or Go, is named in **Needs you**, and the workflow marks where its install steps go. GitHub's runner may already have it.

### Build variables

Each variable in `[build.environment]` is set in the workflow, with `[context.production.environment]`'s value used over `[build]`'s.

- **A variable that looks like a credential is read from a repository secret** of the same name, not written into the file: one whose name contains `TOKEN`, `KEY`, `SECRET`, `PASSWORD` or `AUTH`, or whose value starts like a known API key. It's listed under **Changed**, and **Needs you** gives the `gh secret set` command for it. It's committed in `netlify.toml`, so **rotate it** and store the new value as the secret. Secrets are given only to the install and build steps.
- **Every other variable is written into the workflow** as it is.
- **To decide for one variable,** give `--secret NAME` to read it from a secret, or `--plain NAME` to write its value in. A name like `NEXTAUTH_URL` contains `AUTH` but isn't a credential, so use `--plain` for it.
- **Netlify's own settings,** such as `SECRETS_SCAN_ENABLED`, `NETLIFY_USE_YARN` and `NETLIFY_USE_PNPM`, are listed under **Handled elsewhere** and left out.

### Your own workflow file is safe

The workflow's first lines mark it as written by `ee-migrate`, name the `netlify.toml` it came from, and hold a checksum of the rest. Running `ee-migrate` again replaces it only if it's unchanged since. It stops before writing anything, `_redirects` and `_headers` included, when the file:

- wasn't written by `ee-migrate`;
- was written for another site in the same repository;
- has been edited since.

To keep your edits, name another file with `--workflow` and copy your changes across, or skip the workflow with `--no-workflow`. A file checked out with Windows line endings counts as unchanged.

For a second site in the same repository, give `--workflow` a file of its own, such as `.github/workflows/ee-deploy-docs.yml`.

## How the files are written

The translated rules go in a block of their own:

```
# --- ee-migrate: translated from netlify.toml. Running ee-migrate again replaces this block. ---
/blog/* /posts/:splat 301
/docs https://docs.example.com 302
# ee-migrate dropped (rewrite-target): /api/* https://api.example.com/:splat 200
# ee-migrate dropped (unsupported-status): /old-campaign / 410
# --- ee-migrate: end ---
```

- **A rule that didn't carry over stays as a comment,** with the reason in brackets, so you can read it and decide what to do.
- **Every rule is checked** with the same rules a deploy uses, so the file `ee-migrate` writes deploys.
- **Your own rules come first.** Netlify reads `_redirects` before `netlify.toml`, and the first rule that matches wins, so the translated rules go after yours. A rule of your own that wouldn't deploy is turned into a comment the same way, and listed.
- **Redirects with no status** get 301, Netlify's default.

### Running it again

Run `ee-migrate` again after you change `netlify.toml`. It replaces its own block and leaves the rest of each file alone, and replaces the workflow if you haven't edited it (see [Your own workflow file is safe](#your-own-workflow-file-is-safe)). When nothing is left to translate, it removes the block, and deletes a file that held only the block.

Edit your rules outside the block. After you've moved the files into `static/` or `public/`, running it again finds them there. If it finds more than one copy of a file, it asks you to name one with `--redirects` or `--headers`.

If the block's begin and end lines no longer pair up, it stops and names the line, and doesn't change the file.

## What doesn't carry over

These are listed under **Dropped**, each with its reason:

- **Netlify Functions and Edge Functions,** and rules that point at them (`/.netlify/functions/`).
- **Proxies to another site:** a rule with status 200 whose target is on another host.
- **Statuses other than 301, 302, 200 and 404,** such as 307, 308 and 410.
- **Conditions:** `Country`, `Language`, `Role` and `Cookie`, `signed`, and rules that match on query parameters. See [Scope and limits](https://docs.evolvingedge.ai/redirects/#scope-and-limits).
- **Headers on a redirect** (`[redirects.headers]`) and `Basic-Auth`.
- **Headers the network sets itself.** See [Response headers](https://docs.evolvingedge.ai/headers/).
- **Rules for `*.netlify.app` addresses,** which don't apply here.
- **Deploy previews and branch deploys** (`[context.deploy-preview]`, `[context.branch-deploy]` and named branches).
- **Build plugins and integrations,** `[functions]`, `[edge_functions]`, `[images]`, `[template]`, and asset processing other than `pretty_urls`.

`[dev]`, Netlify's local server, is listed under **Handled elsewhere**: it never changes what's deployed. Use your generator's own dev server.

`ee-migrate` sees only `netlify.toml`. Netlify features set up elsewhere, such as forms, identity, split testing and variables set in its dashboard, aren't in the report. Check yours before you move.

## Options

```
ee-migrate [folder] [options]
```

| Option | What it does |
|---|---|
| `[folder]` | The folder holding `netlify.toml`. Defaults to the current folder. |
| `--strict` | Exit with status 1 if any setting was dropped. Settings listed under **Handled elsewhere** don't count. |
| `--no-workflow` | Don't write the deploy workflow. |
| `--workflow <path>` | Write the deploy workflow to this file instead of `.github/workflows/ee-deploy.yml`. |
| `--domain <domain>` | Write this domain into the workflow instead of reading the `EE_CDN_DOMAIN` repository variable. |
| `--project <id>` | Write this project ID into the workflow instead of reading the `EE_CDN_PROJECT_ID` repository variable. |
| `--secret <NAME>` | Read this build variable from a repository secret, whatever it looks like. Repeat it for more than one. |
| `--plain <NAME>` | Write this build variable's value into the workflow, even if it looks like a credential. Repeat it for more than one. |
| `--report <path>` | Where to write the JSON report. |
| `--redirects <path>` | The `_redirects` file to add the rules to, when your site has more than one. |
| `--headers <path>` | The `_headers` file to add the rules to, when your site has more than one. |
| `--builder-version <v>` | Pin the [packaging tool](https://docs.evolvingedge.ai/cli/#the-packaging-tool-and-its-lockfile)'s version. Defaults to `EE_BUILDER_VERSION`, then the latest. |
| `--quiet`, `-q` | Don't print download progress. |
| `--help`, `-h` | Every option. |

**Exit status.** 0 when the files and the report were written, even if some settings were dropped. 1 when nothing was written (no `netlify.toml`, one that doesn't parse, or a workflow file `ee-migrate` can't replace), or with `--strict` when a setting was dropped. 2 for a mistake in the command.

To check in CI that `netlify.toml` and your Evolving Edge files stay in step, run `ee-migrate --strict` and commit what it writes.

## Troubleshooting

**"no netlify.toml in …"**. Run it in the folder that holds `netlify.toml`, or name that folder.

**"netlify.toml:12:5: …"**. The file doesn't parse. The numbers are its line and column. Fix it, then run again.

**"found more than one _redirects"** (or `_headers`). Name the one your site deploys with, using `--redirects` or `--headers`.

**".github/workflows/ee-deploy.yml is already there and ee-migrate didn't write it"**. Your repository has a workflow of that name. Name another file with `--workflow`, or skip the workflow with `--no-workflow`.

**"… was written by ee-migrate for other/netlify.toml"**. Another site in the repository uses that workflow. Give this site its own file with `--workflow`.

**"… has been edited since ee-migrate wrote it"**. Name another file with `--workflow`, then copy your changes into it and delete the old file, or skip the workflow with `--no-workflow`.

**"ee-builder … predates the deploy workflow, so no workflow is written"**. The packaging tool it used came before the workflow. Most often, `.ee-builder-lock.json` pins an older version: delete its `"latest:"` entry and run again. If you pinned a version with `--builder-version` or `EE_BUILDER_VERSION`, use `2026.11.13.06` or later.

**"ee-builder … is too old to migrate"**. The packaging tool it found came before `ee-migrate`. The message says why that one was used and what to do. Most often, `.ee-builder-lock.json` pins an older version: delete its `"latest:"` entry and run again. If you pinned a version with `--builder-version` or `EE_BUILDER_VERSION`, use one published on 2026-11-10 or later. A refused run leaves your lockfile as it was.

**"ee-builder checksum mismatch"**. A new version of the packaging tool has been published since your lockfile was written. See [The packaging tool and its lockfile](https://docs.evolvingedge.ai/cli/#the-packaging-tool-and-its-lockfile).

Still stuck? See [Customer Support](https://docs.evolvingedge.ai/customer-support/).
