Set up and configure»
Steps 1–4 of the migration walkthrough: scaffold the workspace, pick a source, set its credentials, and validate the configuration before anything runs.
Before you start — what you need»
liftoff moves an estate onto Spacelift, so it needs credentials for both ends and an account ready to receive the work. Have these in place before step 1:
- A Spacelift account, and an API key with root-space admin access. The account is read from the very first step, and a repository and admin stack are created later, so a narrowly scoped key fails partway through.
- An account on the system you are migrating from, with credentials that can read everything in scope.
Each source declares exactly which keys it needs;
liftoff sourceslists them and step 4 proves them. - A VCS integration in Spacelift that can reach the repositories your source uses. Generated stacks name the integration they bind to, so one has to exist for every provider in the estate.
- At least one worker — a private worker pool with a worker attached, or the public pool. Applying the generated code is itself a Spacelift run, so an account with no worker cannot finish a migration.
- Network access to both APIs from wherever you run liftoff.
- A decision about where the generated code will live: the Spacelift-managed repository, which needs no setup, or your own git provider.
liftoff checks the ones it can rather than leaving you to find out later.
liftoff configure validate proves both key pairs, and liftoff audit reports a repository it cannot bind to an integration, one whose integration is not connected to the account it lives under, an integration Spacelift cannot reach at all, or an account with nothing to run on — all before you generate anything.
Before you start — install liftoff»
First, know which version you're meant to run.
Most operators want the current stable release, installed just below.
But if you were pointed at a release candidate — anything ending -rc, or a specific pre-release version — stop here and jump to Release candidates.
The stable brew install below and the RC cask both provide the same liftoff command, so running the stable one now would replace an RC you'd already installed, quietly and with no warning from Homebrew.
Confirm the target first; install second.
If stable is what you want, install it:
1 | |
Without Homebrew:
1 | |
On Windows, download the zip from the releases page and put liftoff.exe on your PATH.
Either way you get one binary and nothing else — no runtime, no container, no services. Check it answers and prints the version you meant to install before going further — if you were sent to a release candidate, this is where you catch having landed on stable instead:
1 | |
To upgrade later, brew upgrade liftoff, or re-run the install script.
Release candidates»
brew install spacelift-solutions/tap/liftoff is always the current stable release — a candidate can never arrive there by surprise.
Candidates are a separate cask you have to ask for by name:
1 | |
Both provide the same liftoff command, so Homebrew will not let you have both at once.
Switch back with:
1 | |
Installing a specific version»
Homebrew carries the newest build of each line and nothing older, so an exact version comes from the install script:
1 | |
The setting goes on sh, not in front of curl — in front of curl it reaches the download and not the script that reads it.
Pinning is what you want in CI, where "whatever is newest" is not a build you can reproduce. The tags are on the releases page.
INSTALL_DIR puts the binary somewhere other than /usr/local/bin — reach for it when that directory needs root:
1 | |
Step 1 — initialize the workspace»
1 | |
Creates ./.liftoff/ in the current directory with an empty config.yaml and the SQLite store.
1 2 3 4 5 6 7 8 | |
Running init again on an existing workspace reports Config Created no and changes nothing, so it is safe to repeat.
On a workspace created by an older binary it migrates the store schema forward.
The only decision here is where to stand.
init creates ./.liftoff under the current directory, one directory per migration.
Later commands walk up from $PWD to find that folder, so you can run them from a subdirectory without re-passing the path.
--config-dir or LIFTOFF_CONFIG_DIR still override the walk when you need a workspace somewhere else.
One warning, and it grows over the migration: ./.liftoff/ becomes the most sensitive thing on this machine.
config.yaml may hold source credentials after step 3 (unless you keep them in env references), and the store — liftoff.db, a plain, unencrypted SQLite file — holds everything discover pulls, variable values included, and later any sensitive values and stack state that capabilities capture.
Treat the directory accordingly.
If you are running inside a git repository, ignore the workspace now:
1 | |
That .gitignore line is necessary but not the whole story — it keeps the workspace out of git, not off backups, syncs, or a shared machine, and it does nothing once the migration is done and the directory should simply be gone.
What the directory contains and how to dispose of it safely is covered at the end of the walkthrough, in finalize.
Next up, liftoff sources to see what you can migrate from.
Step 2 — pick a source»
1 | |
Lists every source this binary can migrate from, with the settings each one takes. Read-only; run it as often as you like.
Terraform Cloud / Enterprise
The capture below shows the Terraform source included in this release.
Use the source id terraform for both Terraform Cloud and self-hosted Terraform Enterprise.
A Terraform Enterprise migration also needs source.api_endpoint set to that installation's API endpoint.
The source's secrets capability covers workspace variables.
context-secrets covers variable-set variables and creates a temporary workspace to read them.
Both restore every source-side change before finishing.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 | |
What to take from this screen:
- The id in the title is what you pass to
configure --source. - Config Keys is your settings checklist.
Only the checked
Requiredkeys must be set. Everything else has aDefaultyou can live with, or aWhen Unsettelling you what not setting it means. - Repair Keys are not for discover.
They feed
liftoff audit --repairin step 7 and only come into play when an audit has findings to fix. You can set them now with everything else, and change them later by re-running configure. - Mutations preview a later, opt-in step.
Discover never changes the source; the one step that does —
liftoff mutate— is opt-in and per run, so you pass--allow-mutation <name>on everymutatethat should use it, which is why mutations are not config keys. Nothing to do now — the mutate step shows the flags.
The decision at this step is which source you are migrating from and which of its optional settings your environment needs. Note the id and move on.
Step 3 — configure the source»
1 | |
Records the source and its settings in config.yaml.
Use the id and required keys reported by liftoff sources.
Values can reference environment variables: single-quote the reference so your shell doesn't expand it, and config.yaml stores the literal ${SOURCE_VALUE} — the value is resolved when a command runs, so the secret itself never has to be written to disk.
A reference that doesn't resolve is an error, not an empty string.
Pasting a raw secret works too; it just lives in config.yaml (and your shell history) instead.
Terraform Cloud / Enterprise
Configure the Terraform source with an admin user token:
1 | |
Set source.api_endpoint as well for Terraform Enterprise.
source.workspace_concurrency controls how many workspaces are processed at once, while source.requests_per_second caps API requests.
--set repeats, and configure is incremental — later runs merge into what's already saved.
A later --set of a key that is already in config.yaml replaces that value (it does not keep the first write):
1 | |
Settings for a deployment transform use one more level: the transform subcommand owns the keys below it. For example:
1 | |
These settings do nothing during discovery. They are consumed only when you run
liftoff transform workflow-tool for the current staged batch.
When you need to write config.yaml by hand»
liftoff configure --set is the normal path: it preserves the rest of the file, checks section names, and keeps secret values out of the report.
Writing .liftoff/config.yaml directly is the escape hatch for pre-seeding a workspace from automation, reviewing the whole configuration, or repairing malformed YAML.
The file has four core top-level entries:
exporteris the source id fromliftoff sources.sourceholds settings declared by that source.spaceliftholds the destination account and API key.vcsholds repository credentials used by capabilities that read from git.
An optional transform entry holds settings for commands such as liftoff transform workflow-tool.
Terraform Cloud / Enterprise
Here is a complete Terraform source example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | |
Environment references stay exactly as written on disk.
The command that uses a value resolves it from the environment, so export each referenced variable before validating or running the migration.
After any hand edit, run liftoff configure validate.
It reports missing and unknown keys, validates transform settings, and authenticates against both configured systems when the required credentials are available.
If a required setting is still missing, configure saves your progress and errors with exactly what's left — the specimen in when something goes wrong is this very case.
Terraform Cloud / Enterprise
With the Terraform source's token set, the current capture reads:
1 2 3 4 5 6 7 | |
Values are never echoed back, only key names.
Step 4 — validate before running anything»
1 | |
The verdict on your configuration: what every key resolves to right now and what the run will mean, and — once the config is complete — it authenticates both key pairs and names who each resolved to. Read-only (it never writes), so run it as often as you like. This is the moment to catch a Spacelift endpoint pointed at the wrong account.
Terraform Cloud / Enterprise
The capture below validates the Terraform source shown in step 2.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | |
Where liftoff sources showed templates, this shows results: every Effect is rendered with the value the run will actually use.
Two more sections appear only when something needs attention: Missing Required (required keys with no value) and Unknown Keys (settings in config.yaml the source doesn't recognize — usually a typo'd --set).
Read the Effect column top to bottom and check it against your intent.
Worth deciding now:
- Rate and concurrency — use the source's reported keys to keep discovery within its API limits.
- Repair keys — they change nothing until
liftoff audit --repairhas a matching finding, and you can re-run configure to adjust them whenever. - The mutations — opt-ins for the later
mutatestep. A mutation is never remembered: you pass--allow-mutation <name>on everymutatethat should use it, which is why they aren't config keys. Decide which capabilities the configured source should run; the mutate step shows the flag.
Terraform Cloud / Enterprise
The default request rate and workspace concurrency are safe for Terraform Cloud; lower them when a Terraform Enterprise installation needs a gentler load.
The repair keys are module_workflow_tool, default_branch, custom_runner_image, worker_pool_id, and repository_map.
They change nothing during discovery.
liftoff audit --repair reads them only when the matching finding is present.
custom_runner_image applies to workspaces whose Terraform version requires the CUSTOM workflow tool.
Give it an untagged image name; repair adds each stack's Terraform version as the tag.
The image must contain that Terraform binary.
A private image requires a private worker pool.
Terraform Cloud / Enterprise
Terraform Cloud / Enterprise: building the runner image for CUSTOM stacks»
If a Terraform workspace runs a version newer than Spacelift bundles, its stack migrates onto the CUSTOM workflow tool and runs the binary your image carries. Spacelift downloads nothing for it — you hold the licence for those versions, so you build the image.
You need one tag per version in the batch.
liftoff audit names the version in each finding, so the audit output is the list:
1 2 3 | |
A Dockerfile that adds one version on top of Spacelift's runner image.
Build on that image rather than a bare Alpine or hashicorp/terraform: the worker calls ps to watch the container, and the image has to carry the spacelift user (UID 1983) that jobs run as.
The fetch stage keeps the build from depending on which archive tools the base image ships:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | |
Build and push one tag per version, tagging each with the version itself — that is what the repair writes:
1 2 3 4 | |
Where you push matters.
On Spacelift's public worker pool the image must be public, and only these registries are accepted: public.ecr.aws, dkr.ecr.<region>.amazonaws.com, docker.io, registry.hub.docker.com, ghcr.io, gcr.io, docker.pkg.dev, azurecr.io, quay.io, registry.gitlab.com.
A private image requires a private worker pool: the public pool caches images across accounts, so it only ever pulls public ones.
liftoff audit checks this rather than leaving you to find out from a run that never starts: a stack heading for the public pool with an image from anywhere else is an error, runner-image-not-pullable (audit).
Then point the setting at the untagged name and repair:
1 2 | |
Each CUSTOM stack gets $REGISTRY/liftoff-runner:<its own version>.
Build for linux/amd64 — that is what Spacelift workers run.
A missing or non-executable binary shows up as sh: terraform: not found, with the run stopping in INITIALIZING.
When the effects read the way you intend and the source credentials authenticated, you are ready for discover.