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 fromhealth_checkor its image’s ownHEALTHCHECK— and doesn’t run itssetup_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: gitinclude is refused under the native format unlessallow_nested_git_includesis set, whereratect-compatallows it unconditionally (see Where the semantics differ). It only bites iflegacy.ymlitself 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.