Getting Started

Welcome to Migraine! This guide will help you get up and running quickly with workflow automation.

Installation

Prerequisites

Operating System: macOS (Apple Silicon/Intel) or Linux
Required tools: Either curl or wget for shell script installation

Installation Methods

1. Homebrew (Recommended for macOS/Linux)

# Add the Homebrew tap
brew tap tesh254/migraine https://github.com/tesh254/homebrew-migraine

# Install migraine
brew install migraine

2. Shell Script

Using curl:

curl -sSL https://raw.githubusercontent.com/tesh254/migraine/main/install.sh | bash

Using wget:

wget -qO- https://raw.githubusercontent.com/tesh254/migraine/main/install.sh | bash

Verify Installation

# Check if migraine is installed correctly
migraine --version

mgr --version

Your First Workflow

1. Create a New Workflow

You have two options for creating workflows:

Option A: Project-level workflow (recommended for project automation)

migraine workflow init

This creates ./migraine.yaml with a fully documented template for project-level workflows.

Option B: Individual workflow file

migraine workflow init my-workflow -d "Description of my workflow"

This creates ./workflows/my-workflow.yaml with a fully documented template.

2. Examine the Generated File

The command creates ./migraine.yaml with a template like this:

# migraine.yaml - generated by Migraine
# 
# This is a project-level workflow configuration for Migraine.
# 
# Fields:
# - name: The name of the project workflow (required)
# - description: A brief description of what this workflow does (optional)
# - pre_checks: Commands to run before executing the main steps (optional)
# - steps: The main commands to execute in the workflow (required)
# - actions: Additional commands that can be run independently (optional)
# - config: Configuration options for the workflow (optional)
# - use_vault: Whether to use the vault for variable resolution (default: false)

name: my-project-workflow
description: Project-level workflow configuration

# Pre-checks are commands that run before the main workflow steps.
# They are typically used for validation, checking if required tools are available, etc.
# If any pre-check fails, the workflow execution stops.
pre_checks:
  # - command: "which git"  # Check if git is available
  #   description: "Verify git is installed"

# Steps are the main commands that make up the workflow.
# They will be executed in the order they appear.
steps:
  # Example step
  - command: "echo 'Hello from project workflow!'"
    description: "Example step that prints a message"
  # Add more steps as needed

# Actions are optional commands that can be run independently of the main workflow.
# They are typically used for cleanup, deployment, or other operations.
actions:
  # Example action
  # deploy:
  #   command: "echo 'Deploying application...'"
  #   description: "Deploy the application"
  # cleanup:
  #   command: "rm -rf ./temp"
  #   description: "Clean up temporary files"

# Configuration options for the workflow
config:
  # Variables that can be used in the workflow
  # These will be prompted for when running the workflow if not provided
  variables:
    # project_name:
    #   - "slugify"  # Apply slugify transformation to the variable value
  # Whether to store variables in the workflow (true) or prompt for them each time (false)
  store_variables: false

# Whether to use the vault for variable resolution
# If true, variables will be resolved from the vault
# If false, variables will be resolved from environment files or prompted
use_vault: false

3. Validate the Workflow

migraine workflow validate migraine.yaml

4. Run the Project Workflow

# Run with no arguments to execute the project workflow from current directory
migraine workflow run

Expected output:

+------------------------------------------------------------------------------+
| WORKFLOW: hello-world        | ACTION: run     | STARTED: 2024-01-15 10:30 |
+------------------------------------------------------------------------------+

[ SCRIPTS ]
  (1/1) Example step that prints a message            12ms
Hello from workflow hello-world!
  ┌────────────────────────────────────────────────────────────────────────────┐
  │ ℹ Step completed successfully                                              │
  └────────────────────────────────────────────────────────────────────────────┘

[ SUMMARY ]
  Status: SUCCESS
  Duration: 15ms
  Prechecks: 0 passed, 0 failed, 0 warn
  Scripts: 1/1 completed
  ┌────────────────────────────────────────────────────────────────────────────┐
  │ ✓ Project workflow 'hello-world' completed successfully                    │
  └────────────────────────────────────────────────────────────────────────────┘

⚠️ IMPORTANT: The vault currently stores variables in an unencrypted SQLite database. While variables are stored locally, they are not encrypted at rest. We are actively working on adding encryption support in an upcoming release. For now, we recommend avoiding storing highly sensitive information like production API keys in the vault until encryption is implemented.

1. Store a Variable in the Vault

migraine vars set api_key "your-api-key-here"

2. List Variables

migraine vars list

3. Use Variables in Workflows

Create a project workflow that uses variables (migraine.yaml):

name: greet-workflow
description: Greet with custom name
use_vault: true

steps:
  - command: "echo 'Hello {{name}}, welcome to {{project}}!'"
    description: "Greet with custom name"

4. Run with Variables

# Run with command-line variables
migraine workflow run greet -v name="Alice" -v project="My Project"

# Or set variables in the vault first
migraine vars set name "Alice"
migraine vars set project "My Project"
migraine workflow run greet

Expected output:

Hello Alice, welcome to My Project!

Project-Level Workflows

Create a migraine.yaml file in your project root to define project-specific workflows:

name: my-project
description: Project-level workflow configuration

pre_checks:
  - command: "which git"
    description: "Verify git is available"
  - command: "which node"
    description: "Verify node is available"

steps:
  - command: "npm install"
    description: "Install dependencies"
  - command: "npm run build"
    description: "Build the project"
  - command: "npm test"
    description: "Run tests"

actions:
  setup:
    command: "git clone {{repo_url}} ."
    description: "Initialize project from repository"
  deploy:
    command: "npm run deploy"
    description: "Deploy to production"
  cleanup:
    command: "rm -rf node_modules package-lock.json"
    description: "Clean up dependencies"

Run the project workflow:

# Run main workflow (pre-checks, then steps)
migraine workflow run

# Run specific action
migraine workflow run -a deploy

# Run with variables
migraine workflow run -v repo_url="https://github.com/user/repo.git"

Using the New Pre-checks Command

Migraine includes a new command that allows you to run only pre-checks:

1. Run Pre-checks from Current Directory

migraine workflow pre-checks

This runs only the pre-checks section of the migraine.yaml file in the current directory.

2. Run Pre-checks for a Specific Workflow

migraine workflow pre-checks my-workflow

This command will:

Look up the stored working directory for "my-workflow"
Change to that directory
Run the pre-checks from that location
Restore your original directory when finished

Common Use Cases

Development Environment Setup

# Create a setup workflow
migraine workflow init dev-setup -d "Development environment setup"

CI/CD Pipeline

# Create a build workflow
migraine workflow init build -d "Build and test application"

Deployment

# Create a deployment workflow
migraine workflow init deploy -d "Deploy to production"

Advanced Quick Example

Multi-Step Deployment Workflow

name: deploy-app
description: Deploy application with validation and rollback

pre_checks:
  - command: "which rsync"
    description: "Verify rsync is available"
  - command: "ssh -q {{server}} exit"
    description: "Test server connectivity"

steps:
  - command: "npm run build"
    description: "Build the application"
  - command: "tar -czf app.tar.gz dist/"
    description: "Package for deployment"
  - command: "rsync -av app.tar.gz {{user}}@{{server}}:/tmp/"
    description: "Upload to server"
  - command: "ssh {{user}}@{{server}} 'cd /opt/app && tar -xzf /tmp/app.tar.gz && systemctl restart myapp'"
    description: "Extract and restart service"

actions:
  rollback:
    command: "ssh {{user}}@{{server}} 'cd /opt/app && git checkout HEAD~1 && systemctl restart myapp'"
    description: "Rollback to previous version"
  cleanup:
    command: "rm -f app.tar.gz && ssh {{user}}@{{server}} 'rm -f /tmp/app.tar.gz'"
    description: "Clean up temporary files"

config:
  variables:
    server:
      - "required"
    user:
      - "required"
  store_variables: false

use_vault: true

Run the deployment:

migraine workflow run deploy-app -v server="prod-server" -v user="deployer"

Or run only pre-checks to validate connectivity:

migraine workflow pre-checks deploy-app

Next Steps

Now that you've created your first workflow, explore these advanced topics:

Workflows: Learn about advanced workflow features and best practices
Vault: Understand variable management and security
CLI Reference: Complete command reference with all options
Alternatives Comparison: Why Migraine vs other tools

The documentation provides comprehensive guides for each of these areas to help you get the most out of Migraine!