Setup scripts

Cyrus supports automated repository initialization through setup scripts that run when creating new Git worktrees for Linear issues. This powerful feature allows you to prepare the development environment automatically for each task.

Overview

When Cyrus processes a Linear issue, it:

Creates a new Git worktree for isolation
Runs setup scripts to prepare the environment
Processes the issue in the prepared worktree
Cleans up the worktree after completion

Setup scripts ensure each worktree starts with the correct dependencies, configuration, and environment.

Repository setup script

Creating a repository script

Place a cyrus-setup.sh script in your repository root:

#!/bin/bash
# cyrus-setup.sh - Repository initialization script

# Install dependencies
npm install

# Copy environment files
cp .env.example .env

# Build the project
npm run build

# Any other repository-specific setup
echo "Repository setup complete for issue: $LINEAR_ISSUE_IDENTIFIER"

Make the script executable:

chmod +x cyrus-setup.sh

Available environment variables

Cyrus provides these environment variables to your script:

LINEAR_ISSUE_ID: The Linear issue ID (UUID format)
LINEAR_ISSUE_IDENTIFIER: The issue identifier (e.g., “CEA-123”)
LINEAR_ISSUE_TITLE: The issue title

Example Usage:

#!/bin/bash

echo "Setting up environment for: $LINEAR_ISSUE_IDENTIFIER"
echo "Title: $LINEAR_ISSUE_TITLE"

# Create issue-specific log directory
mkdir -p logs/$LINEAR_ISSUE_IDENTIFIER

# Install dependencies
npm install

# Setup database with issue identifier
createdb "test_db_${LINEAR_ISSUE_IDENTIFIER}"

When to use repository scripts

Common Use Cases:

Dependency Installation: npm install, pip install -r requirements.txt
Environment Configuration: Copy .env files, set up credentials
Database Setup: Create test databases, run migrations
Build Steps: Compile code, generate assets
Service Startup: Start local services needed for development

Example: Node.js Project

#!/bin/bash
set -e  # Exit on error

echo "Setting up Node.js project for $LINEAR_ISSUE_IDENTIFIER"

# Install dependencies
npm install

# Copy environment configuration
if [ ! -f .env ]; then
    cp .env.example .env
    echo "Created .env from .env.example"
fi

# Run database migrations
npm run db:migrate

# Build the project
npm run build

echo "Setup complete!"

Example: Monorepo

#!/bin/bash
set -e

echo "Setting up monorepo for $LINEAR_ISSUE_IDENTIFIER"

# Install root dependencies
npm install

# Build all packages
npm run build --workspaces

# Copy shared configuration
cp config/shared/.env.example config/shared/.env

# Setup test databases
./scripts/setup-test-db.sh

echo "Monorepo setup complete!"

Script best practices

Exit on error

Always use set -e to exit immediately if any command fails:

#!/bin/bash
set -e  # Exit on error

Keep scripts fast

Setup scripts delay issue processing. Keep them fast:

Cache dependencies when possible
Skip unnecessary steps
Use parallel installation when available

# Fast npm install with frozen lockfile
npm ci --prefer-offline

Timeout and error handling

Timeout: Scripts have a 5-minute timeout
Failure Behavior: Script failures don’t prevent worktree creation
Logs: Script output appears in Cyrus logs for debugging

Testing your script

Test the script locally before relying on it:

# Set test environment variables
export LINEAR_ISSUE_ID="test-id"
export LINEAR_ISSUE_IDENTIFIER="TEST-123"
export LINEAR_ISSUE_TITLE="Test Issue"

# Run the script
./cyrus-setup.sh

Advanced patterns

Conditional setup based on issue

Run different setup based on issue labels or title:

#!/bin/bash
set -e

echo "Setup for: $LINEAR_ISSUE_IDENTIFIER"

# Check if this is a database issue
if [[ "$LINEAR_ISSUE_TITLE" == *"database"* ]]; then
    echo "Database issue detected, setting up test DB"
    ./scripts/setup-test-database.sh
fi

# Standard setup for all issues
npm install
npm run build

Caching dependencies

Speed up setup by caching dependencies:

#!/bin/bash
set -e

CACHE_DIR="$HOME/.cyrus/cache/$(basename $(pwd))"

# Create cache directory if it doesn't exist
mkdir -p "$CACHE_DIR"

# Link node_modules from cache if available
if [ -d "$CACHE_DIR/node_modules" ]; then
    echo "Using cached node_modules"
    ln -s "$CACHE_DIR/node_modules" node_modules
else
    echo "Installing dependencies (will be cached)"
    npm install
    # Copy to cache
    cp -r node_modules "$CACHE_DIR/"
fi

Parallel setup

Run independent setup tasks in parallel:

#!/bin/bash
set -e

echo "Running parallel setup tasks..."

# Start parallel tasks
npm install &
PID1=$!

./scripts/setup-database.sh &
PID2=$!

./scripts/download-assets.sh &
PID3=$!

# Wait for all tasks to complete
wait $PID1
echo "Dependencies installed"

wait $PID2
echo "Database setup complete"

wait $PID3
echo "Assets downloaded"

echo "All setup tasks complete!"

Issue-specific configuration

Create configuration specific to each issue:

#!/bin/bash
set -e

# Create issue-specific environment
cat > .env.local << EOF
ISSUE_ID=$LINEAR_ISSUE_ID
ISSUE_IDENTIFIER=$LINEAR_ISSUE_IDENTIFIER
LOG_PREFIX=[$LINEAR_ISSUE_IDENTIFIER]
TEST_DB_NAME=cyrus_test_${LINEAR_ISSUE_IDENTIFIER}
EOF

echo "Created issue-specific configuration"

Troubleshooting

Script not running

Check:

Script exists at repository root
Script is named exactly cyrus-setup.sh
Script has execute permissions (chmod +x cyrus-setup.sh)
Script has correct shebang (#!/bin/bash)

Script failing

Debug Steps:

Test script locally with test environment variables
Check Cyrus logs for script output and errors
Add echo statements to identify where script fails
Verify all dependencies and commands are available

Common Issues:

Missing dependencies (e.g., npm not in PATH)
Permission errors (e.g., can’t write to directories)
Timeout (script takes longer than 5 minutes)

Script timeout

If scripts consistently timeout:

Optimize dependency installation:

# Use npm ci instead of npm install (faster)
npm ci --prefer-offline

Skip unnecessary steps:

# Skip build if not needed for testing
# npm run build

Cache dependencies: See caching pattern above

Script works locally but fails in Cyrus

Check that:

All paths are relative or use environment variables
All required tools are installed in the Cyrus environment
No interactive prompts (scripts must run non-interactively)

Next: Remote Hosting

​Setup scripts

​Overview

​Repository setup script

​Creating a repository script

​Available environment variables

​When to use repository scripts

​Script best practices

​Exit on error

​Keep scripts fast

​Timeout and error handling

​Testing your script

​Advanced patterns

​Conditional setup based on issue

​Caching dependencies

​Parallel setup

​Issue-specific configuration

​Troubleshooting

​Script not running

​Script failing

​Script timeout

​Script works locally but fails in Cyrus