Getting Started

Installation

WorkflowKt consists of two components: a Gradle plugin for registering and executing actions, and a core runtime library providing the APIs.

Gradle Plugin

Add the plugin to your build.gradle.kts:

plugins {
    id("ir.amirroid.workflowkt") version "0.0.2"
}

Runtime Dependency

Add the core library as a dependency:

dependencies {
    implementation("ir.amirroid:workflowkt-core:0.0.2")
}

Version Catalog

If you use a version catalog (libs.versions.toml), you can define:

[versions]
workflowkt = "0.0.2"

[libraries]
workflowkt-core = { module = "ir.amirroid:workflowkt-core", version.ref = "workflowkt" }

[plugins]
workflowkt = { id = "ir.amirroid.workflowkt" }

Then reference it in your build file:

plugins {
    alias(libs.plugins.workflowkt)
}

dependencies {
    implementation(libs.workflowkt.core)
}

Project Setup

1. Apply the Plugin

plugins {
    alias(libs.plugins.kotlin.jvm)
    alias(libs.plugins.workflowkt)
}

dependencies {
    implementation(libs.workflowkt.core)
}

2. Register Your First Action

workflowkt {
    registerAction(
        key = "hello",
        implementationClass = "com.example.HelloWorldAction"
    )
}

3. Create the Action Class

package com.example

import ir.amirroid.workflowkt.ActionResult
import ir.amirroid.workflowkt.GithubAction
import ir.amirroid.workflowkt.context.PushContext
import ir.amirroid.workflowkt.environment.GithubEnvironment

class HelloWorldAction : GithubAction<PushContext> {

    override fun run(context: PushContext, environment: GithubEnvironment): ActionResult {
        println("Hello from ${context.repository.fullName}!")
        println("Pushed by: @${context.sender.login}")
        return ActionResult.Success()
    }
}

4. Run It

./gradlew runWorkflowKt --key=hello

Your First GitHub Actions Workflow

Create a minimal .github/workflows/ci.yml:

name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
  workflow_dispatch:

jobs:
  run-action:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 17
          cache: gradle

      - run: chmod +x gradlew

      - run: ./gradlew runWorkflowKt --key=hello --stacktrace --no-daemon

Next Steps

• Learn about Architecture to understand how the framework works
• See API Reference for complete documentation of all types
• Explore Guides for step-by-step tutorials