Skip to content

01-getting-started.md

Latest commit

 

History

History
362 lines (271 loc) · 7.27 KB

01-getting-started.md

File metadata and controls

362 lines (271 loc) · 7.27 KB

Getting Started with Kite

Get up and running with Kite in 5 minutes. This guide will help you create your first workflow.

What is Kite?

Kite is a modern CI/CD workflow runner that lets you define pipelines as type-safe Kotlin code. Replace bash scripts and YAML configs with a powerful DSL that provides:

  • ✅ Type safety - Catch errors at compile time
  • ✅ IDE support - Full autocomplete and syntax highlighting
  • ✅ Reusability - Define segments once, use everywhere
  • ✅ Local testing - Test pipelines before pushing
  • ✅ Platform agnostic - Works on any CI platform

Quick Start

1. Installation

Add Kite to your project:

// build.gradle.kts
repositories {
    mavenCentral()
}

dependencies {
    implementation("com.gianluz.kite:kite-core:0.1.0-alpha9")
    implementation("com.gianluz.kite:kite-dsl:0.1.0-alpha9")
    implementation("com.gianluz.kite:kite-runtime:0.1.0-alpha9")
}

See Installation for other installation methods.

2. Create Your First Segment

Create .kite/segments/build.kite.kts:

segments {
    segment("build") {
        description = "Build the project"
        execute {
            exec("./gradlew", "build")
        }
    }
    
    segment("test") {
        description = "Run tests"
        dependsOn("build")
        execute {
            exec("./gradlew", "test")
        }
    }
}

3. Create Your First Ride

Create .kite/rides/ci.kite.kts:

ride {
    name = "CI"
    
    flow {
        segment("build")
        segment("test")
    }
}

4. Run It!

# Run the CI ride
kite-cli ride CI

# Or run specific segments
kite-cli run build test

That's it! You've created your first Kite workflow.

Project Structure

Kite uses a simple directory structure:

your-project/
├── .kite/
│   ├── segments/           # Reusable units of work
│   │   ├── build.kite.kts
│   │   ├── test.kite.kts
│   │   └── deploy.kite.kts
│   └── rides/              # Workflow definitions
│       ├── ci.kite.kts
│       └── release.kite.kts
└── build.gradle.kts

Key Concepts

Segments

Segments are reusable units of work - like building, testing, or deploying.

segment("build") {
    description = "Build the application"
    timeout = 10.minutes
    execute {
        exec("./gradlew", "build")
    }
}

Rides

Rides compose segments into workflows for different scenarios (CI, release, etc.).

ride {
    name = "CI"
    flow {
        segment("build")
        parallel {
            segment("test")
            segment("lint")
        }
    }
}

Execution Context

Inside execute blocks, you have access to the execution context:

execute {
    // Run commands
    exec("./gradlew", "test")
    
    // Access environment variables
    val branch = env("BRANCH_NAME")
    
    // Work with files
    writeFile("output.txt", "Hello!")
    
    // Conditional logic
    if (branch == "main") {
        exec("./deploy.sh")
    }
}

Learn more in Core Concepts.

IDE Setup

IntelliJ IDEA automatically provides full IDE support for .kite.kts files:

  • ✅ Syntax highlighting
  • ✅ Autocomplete
  • ✅ Type checking
  • ✅ Refactoring support
  • ✅ Error detection

Enable Autocomplete

After adding Kite dependencies, reload your Gradle project:

  1. View → Tool Windows → Gradle
  2. Click "Reload All Gradle Projects" (↻ icon)

That's it! Your .kite.kts files now have full IDE support.

See Troubleshooting if autocomplete doesn't work.

Real-World Example

Here's a complete CI/CD workflow for an Android app:

Segments (.kite/segments/android.kite.kts)

segments {
    segment("compile") {
        description = "Compile the Android app"
        execute {
            exec("./gradlew", "compileDebugKotlin")
        }
    }
    
    segment("lint") {
        description = "Run Android lint checks"
        dependsOn("compile")
        execute {
            exec("./gradlew", "lintDebug")
        }
    }
    
    segment("test") {
        description = "Run unit tests"
        dependsOn("compile")
        execute {
            exec("./gradlew", "testDebugUnitTest")
        }
    }
    
    segment("assemble") {
        description = "Build APK"
        dependsOn("lint", "test")
        execute {
            exec("./gradlew", "assembleDebug")
        }
    }
}

Ride (.kite/rides/ci.kite.kts)

ride {
    name = "CI"
    maxConcurrency = 2
    
    flow {
        segment("compile")
        
        // Run lint and tests in parallel
        parallel {
            segment("lint")
            segment("test")
        }
        
        segment("assemble")
    }
}

GitHub Actions (.github/workflows/ci.yml)

Easiest approach - Use the Kite action:

name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run CI
        uses: ./.github/actions/run-kite
        with:
          command: ride CI

Or manual setup:

name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '17'
      
      - name: Build Kite CLI
        run: ./gradlew :kite-cli:installDist
      
      - name: Run CI
        run: kite-cli/build/install/kite-cli/bin/kite-cli ride CI

Tip: The action includes caching for much faster subsequent runs!

See CI Integration and GitHub Actions for details.

Common Patterns

Helper Functions

Define reusable functions:

fun ExecutionContext.gradleTask(vararg tasks: String) {
    exec("./gradlew", *tasks)
}

segments {
    segment("build") {
        execute {
            gradleTask("clean", "build")
        }
    }
}

Conditional Execution

Run segments based on conditions:

segment("deploy") {
    condition = { ctx: ExecutionContext ->
        ctx.env("BRANCH") == "main"
    }
    execute {
        exec("./deploy.sh", "production")
    }
}

Parallel Execution

Run independent segments concurrently:

flow {
    segment("compile")
    
    parallel {
        segment("unit-tests")
        segment("integration-tests")
        segment("lint")
    }
}

See Parallel Execution for more patterns.

Next Steps

Now that you have Kite running, explore these topics:

Getting Help

  • Documentation: docs/
  • Issues: GitHub Issues
  • Examples: Check .kite/ in the Kite repository

Welcome to Kite! 🪁 Let's build better CI/CD workflows together.