Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Migrating a Batect Project to Ratect

This page is specifically for a project that already has a batect.yml — see Getting Started instead if you’re bringing Ratect into a project that doesn’t use Batect at all.

Most task runners assume a clean slate — convert everything, or don’t bother. Ratect doesn’t: ratect-compat reads an existing batect.yml unchanged, and a native ratect.toml project can include a batect.yml fragment as-is (see Two binaries, two formats). That makes migration a series of independent, optional steps rather than one all-or-nothing conversion — stop at whichever one matches how much of the tool you actually want.

Step 1: point ratect-compat at what you already have

The first step usually needs no config changes: run ratect-compat against the batect.yml you already have, in place of the (now unmaintained) batect binary itself. Same file, same flags, mostly the same behavior. Some checks Batect makes only when a task runs are made here when the file loads, so a latent mistake in a task you never ran can surface — see Load errors, and Differences from Batect for the other exceptions. This alone gets a maintained tool, and is a complete, permanent choice on its own if that’s all you want.

From here, two paths

Once ratect-compat is in place, there are two ways to move onto the native ratect.toml format. They aren’t sequential steps — pick one: ratect config convert only ever reads a Batect-format root file, so it has to run before the project’s root becomes ratect.toml (path A below), not after. Once the root is native, finishing off any remaining .yml includes is a by-hand job (path B). What actually changes between the two formats is tabulated in the ratect.toml reference — at a glance and where the semantics differ — and between the two binaries in the ratect CLI reference.

Path A: convert everything in one pass

ratect config convert reads a project’s actual root batect.yml — includes and all — and converts each file the project owns beside itself: the root to ratect.toml, every local included file to a .toml with the same name in its own directory, with each include entry rewritten to match, so every relative path keeps the directory it resolves against. A Git include stays a Git include. ratect config convert -f batect.yml, captured in examples/jvm — the one example kept as a batect.yml:

Converted batect.yml to ratect.toml.
Review it, then remove batect.yml.

The output is a starting point, not a finished file: config convert doesn’t carry comments over, though it does check each file round-trips losslessly before writing anything. The same configuration runs differently in a few respects under ratect: a task’s own container has no readiness gate (see Dependency Readiness), an enabled run_as_current_user becomes identity, the same goal with a mechanism that depends on the daemon, so its --user may go (see Coming from run_as_current_user), an expression in that home_directory or a string-form volumes entry’s host path is evaluated rather than used as written (see Where the semantics differ), and a Git include’s bundle may offer a ratect-bundle.toml or declare Git includes of its own (see the config convert section). config convert lists each task container whose health_check or setup_commands the first affects, each container the second does, each home_directory or volume the third does, and each Git include the fourth does, after converting and in each converted file’s own header; a health check from the image itself can’t be seen without the image. Review each file against Configuration Reference before deleting the originals — this is the fastest route to fully native, but still one diff worth reading closely, not a step to run and forget.

Path B: migrate incrementally

Try the native binary without converting anything

The native format isn’t all-or-nothing either. An include entry is parsed by its file extension (see Includes), so a ratect.toml project can pull in an entire existing batect.yml unconverted. The one adjustment needed: an included file must not declare project_name, since that’s root-only (see Includes) — move that one line out into the new root file instead.

# legacy.yml — the old batect.yml, minus its `project_name:` line
containers:
  build-env:
    image: alpine:3.18.2
    volumes:
      - .:/code
tasks:
  test:
    run:
      container: build-env
      command: echo "Hello from ratect!"
# ratect.toml
project_name = "my-project"
include = [
    { path = "legacy.yml" },
]

ratect tasks list -f ratect.toml and ratect run test -f ratect.toml now work through the native binary and a native entry point, with zero lines of the actual configuration translated — mostly the same behavior as before, with two differences worth knowing:

  • A task’s own container has no readiness gate. The native binary doesn’t wait on the health check of a container a task runs as its own run.container — whether from health_check or its image’s own HEALTHCHECK — and doesn’t run its setup_commands, wherever that container is declared: the binary running the project decides, not the file’s format (see Dependency Readiness). The same container used as a dependency is still gated.
  • Nested Git includes need a grant. A Git-included bundle that itself declares a nested type: git include is refused under the native format unless allow_nested_git_includes is set, where ratect-compat allows it unconditionally (see Where the semantics differ). It only bites if legacy.yml itself has a nested Git include of that shape.

Migrate one file at a time

From here, migration is as granular as you want it to be. Split legacy.yml into smaller files along whatever lines make sense (one per container group, one per pipeline stage — Batect’s own include already supports this), then convert each piece in turn: since config convert treats the file it’s pointed at as a root, and gives a root’s conversion a project_name (which an included file can’t declare), converting one piece means pointing it at a throwaway root — a batect.yml in a scratch directory, with an include entry naming the piece — which writes the piece’s own .toml beside it, and one beside each file the piece itself includes, their include entries pointing at each other (plus a ratect.toml beside the throwaway root, to delete with it). Swap that one include entry from .yml to .toml, and move on whenever you’re ready — there’s no deadline, and a project can stay a mix of both formats indefinitely.

What decides when a piece has to move is the feature you want. A container still declared in a .yml is a Batect container wherever it is included, so it can use no ratect-native field — see Which fields a file may use. Reaching for ulimits, extends or stop_signal on a container is therefore the signal to convert that container to TOML; nothing else in the project has to move with it.

Next steps

Wherever you stopped, Differences from Batect is what behaves differently from batect itself — the exceptions Step 1 pointed at, in full.