WorkflowKt

A Kotlin-first framework for building GitHub Actions workflows as executable Kotlin code.

---

What is WorkflowKt?

WorkflowKt replaces brittle YAML-based GitHub Actions workflows with type-safe, testable Kotlin code. Instead of maintaining complex shell scripts and YAML configurations, you implement your CI/CD logic as regular Kotlin classes that run directly inside your project.

Key Features

• Type-Safe Workflows — Implement CI logic as Kotlin classes with full type checking
• Typed Event Contexts — Direct access to GitHub event payloads (push, PR, issues, releases, etc.)
• Environment Access — Read GitHub Actions environment variables through a clean API
• Local Testing — Run and debug workflows locally before pushing
• Gradle Plugin — Register and execute actions via simple Gradle tasks
• Full JVM Ecosystem — Use any Kotlin/Java library directly in your workflows

Quick Example

class ValidateCommitsAction : GithubAction<PushContext> {

    override fun run(context: PushContext, environment: GithubEnvironment): ActionResult {
        val pattern = Regex("^(feat|fix|docs)(\\(.+\\))?: .+")

        val invalidCommits = context.commits.filter { commit ->
            !pattern.matches(commit.message.lines().first())
        }

        return if (invalidCommits.isEmpty()) {
            ActionResult.Success(mapOf("MESSAGE" to "All commits valid"))
        } else {
            ActionResult.Failure("Found ${invalidCommits.size} invalid commits")
        }
    }
}

Register it in your build.gradle.kts:

workflowkt {
    registerAction(
        key = "validate_commits",
        implementationClass = "com.example.ValidateCommitsAction"
    )
}

Run it:

./gradlew runWorkflowKt --key=validate_commits

Modules

Module	Description	Artifact
core	Runtime library with GithubAction, contexts, environment, and models	ir.amirroid:workflowkt-core
gradle-plugin	Gradle plugin for registering and executing actions	ir.amirroid.workflowkt
sample	Example actions demonstrating real-world usage	—

Requirements

• Kotlin 2.2+
• JDK 17+
• Gradle with Kotlin DSL

License

MIT License — see LICENSE for details.