Migrations and Update Pipeline

A core component of Omarchy’s maintenance is its automated update pipeline, which ensures the installer stays current and applies necessary system migrations incrementally. This section details the migration runner behaviour, explaining how Omarchy tracks and executes migration scripts during updates.

Overview

Omarchy’s update process combines Git-based upgrades, system package updates, and configuration migrations. The migration runner ensures one-off scripts in the migrations/ directory run exactly once, preserving system consistency and enabling safe feature rollouts.

Update Pipeline

The omarchy-update command orchestrates the full update sequence, invoking the migration runner as a key step:

#!/bin/bash
set -e
omarchy-snapshot create   # Create a restore snapshot
omarchy-update-git       # Pull latest installer changes
omarchy-migrate          # Execute pending migration scripts
omarchy-update-system-pkgs
omarchy-update-restart
omarchy-restart-waybar   # Refresh UI components

flowchart LR
  A[Create Snapshot] --> B[Update Git]
  B --> C[Run Migrations]
  C --> D[Update System Packages]
  D --> E[Restart Services]
  E --> F[UI Refresh & Reboot Ready]

Migration Runner Behaviour

The migration runner (omarchy-migrate) scans for new scripts, executes them once, and records outcomes to prevent re-execution.

State Management

Omarchy tracks migration runs using a state directory in the user’s home.

Path	Purpose
`$HOME/.local/state/omarchy/migrations/`	Marks completed migrations
`$HOME/.local/state/omarchy/migrations/skipped/`	Marks skipped migrations after failures

Directories are created if absent, ensuring idempotent operation.

Migration Scripts

All migration scripts reside in:

~/.local/share/omarchy/migrations/*.sh

Each script is a standalone Bash file performing a specific configuration change or package adjustment. New scripts can be added via the developer helper:

omarchy-dev-add-migration

Execution Logic

For each script, the runner checks whether it has already been completed or skipped, then executes pending ones:

#!/bin/bash
STATE_DIR="$HOME/.local/state/omarchy/migrations"
mkdir -p "$STATE_DIR" "$STATE_DIR/skipped"

for file in ~/.local/share/omarchy/migrations/*.sh; do
  filename=$(basename "$file")
  if [[ ! -f "$STATE_DIR/$filename" && ! -f "$STATE_DIR/skipped/$filename" ]]; then
    echo -e "\e[32mRunning migration: ${filename%.sh}\e[0m"
    if bash "$file"; then
      touch "$STATE_DIR/$filename"
    else
      # Failure handling (see below)
    fi
  fi
done

Failure Handling

If a migration script exits with a non-zero status, Omarchy prompts the user via gum:

Skip and continue — marks the script as skipped (skipped/), allowing subsequent migrations to run.
Abort update — exits the pipeline immediately for manual intervention.

This interactive approach prevents a single faulty script from halting the entire update sequence.

Preflight Seeding

On initial installation, existing migrations are pre-marked as completed to avoid retroactively applying them. The preflight step touches all migration filenames in the state directory:

#!/bin/bash
OMARCHY_MIGRATIONS_STATE_PATH=~/.local/state/omarchy/migrations
mkdir -p "$OMARCHY_MIGRATIONS_STATE_PATH"
for file in ~/.local/share/omarchy/migrations/*.sh; do
  touch "$OMARCHY_MIGRATIONS_STATE_PATH/$(basename "$file")"
done

By clearly separating state management, script execution, and failure handling, Omarchy’s migration runner ensures that each system tweak applies safely and only once, maintaining a predictable and robust update pipeline.

Search this space