ActionResult

Represents the result of executing a GitHub Action.

Source: core/src/main/kotlin/ir/amirroid/workflowkt/ActionResult.kt

Definition

sealed interface ActionResult {
    data class Success(val result: Map<String, String>? = null) : ActionResult
    data class Failure(val reason: String? = null) : ActionResult
}

Variants

ActionResult.Success

Indicates the action completed successfully. The workflow continues to the next step.

Property	Type	Default	Description
result	Map<String, String>?	null	Optional key-value pairs written to GITHUB_OUTPUT

// Simple success
return ActionResult.Success()

// Success with outputs
return ActionResult.Success(
    mapOf(
        "MESSAGE" to "All checks passed",
        "TIME" to Instant.now().toString()
    )
)

Output Handling

When result is non-null and non-empty, the Gradle task writes each entry to the GITHUB_OUTPUT file as key=value lines. These outputs are then available in subsequent GitHub Actions steps via ${{ steps.<id>.outputs.<key> }}.

ActionResult.Failure

Indicates the action failed. The workflow step fails and stops further execution.

Property	Type	Default	Description
reason	String?	null	Optional description of the failure

// Simple failure
return ActionResult.Failure()

// Failure with reason
return ActionResult.Failure("Tests failed: 3 out of 42 test cases failed")

Failure Behavior

When a Failure is returned, the Gradle task throws a WorkflowFailureException with the failure reason, which causes the GitHub Actions step to fail with a non-zero exit code.

Usage Pattern

override fun run(context: PushContext, environment: GithubEnvironment): ActionResult {
    val invalidCommits = validateCommits(context.commits)

    return if (invalidCommits.isEmpty()) {
        ActionResult.Success(
            mapOf("VALIDATED" to "true")
        )
    } else {
        ActionResult.Failure(
            "Found ${invalidCommits.size} invalid commit messages"
        )
    }
}