Running Workflows

WorkflowKt provides two Gradle tasks for executing actions.

Production Mode

Run an action using the runWorkflowKt task:

./gradlew runWorkflowKt --key=<action_key>

Example

./gradlew runWorkflowKt --key=validate_commits

Options

Option	Description
--key	The action key registered in workflowkt { }
--payload	Optional: path to a local event payload file (overrides GITHUB_EVENT_PATH)

Output Handling

When your action returns ActionResult.Success(result = mapOf(...)), the outputs are written to the GITHUB_OUTPUT file. You can reference them in subsequent steps:

- name: Run action
  id: workflow
  run: ./gradlew runWorkflowKt --key=validate_commits

- name: Use outputs
  run: echo "Result: ${{ steps.workflow.outputs.MESSAGE }}"

GitHub Actions Workflow

Here's a complete workflow file that uses WorkflowKt:

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

      - name: Run workflow action
        run: ./gradlew runWorkflowKt --key=validate_commits --stacktrace --no-daemon
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Event-Based Routing

The Gradle task automatically skips actions whose context type doesn't match the current event. For example, an action with GithubAction<PushContext> won't run on pull_request events.

This means you can register multiple actions and use a single workflow file:

name: CI

on:
  issues:
    types: [opened, edited]
  pull_request:
    types: [opened, synchronize, reopened]
  push:
    branches: [main, develop]
  release:

jobs:
  issue-workflow:
    if: github.event_name == 'issues'
    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=auto_label --stacktrace --no-daemon
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  pr-workflow:
    if: github.event_name == 'pull_request'
    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=code_quality --stacktrace --no-daemon
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  push-workflow:
    if: github.event_name == 'push'
    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=validate_commits --stacktrace --no-daemon

Task Behavior

1. The task depends on classes — compilation happens automatically
2. Action classes are loaded via URLClassLoader with the module's runtime classpath
3. The context type is resolved from the action's generic type parameter
4. The task checks if the action's event matches GITHUB_EVENT_NAME
5. If the event doesn't match (and not in test mode), the action is skipped