Environment¶

Interface for accessing GitHub Actions environment variables.

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

Interface Hierarchy¶

classDiagram
    class Environment {
        <<interface>>
        +toMap(): Map~String,String~
        +get(key: String): String?
        +require(key: String): String
        +getBoolean(key: String, default): Boolean?
        +getInt(key: String, default): Int?
        +getLong(key: String, default): Long?
        +getDouble(key: String, default): Double?
        +requireBoolean(key: String): Boolean
        +requireInt(key: String): Int
        +requireLong(key: String): Long
        +requireDouble(key: String): Double
    }
    class GithubCoreEnvironments {
        +action: String?
        +actor: String?
        +repository: String?
        +repositoryOwner: String?
        +eventName: String?
        +workflow: String?
        +sha: String?
        +runId: String?
        +runNumber: Long?
        +workspace: String?
        +eventPath: String?
        +output: String?
        +requireEventName: String
        +requireEventPath: String
    }
    class GithubRefEnvironments {
        +ref: String?
        +refName: String?
        +refType: String?
        +baseRef: String?
        +headRef: String?
    }
    class GithubRunnerEnvironments {
        +runnerOs: String?
        +runnerArch: String?
        +runnerName: String?
        +runnerTemp: String?
        +runnerWorkspace: String?
    }
    class GithubSystemEnvironments {
        +isCi: Boolean
        +home: String?
        +path: String?
    }
    class GithubEnvironment {
        <<interface>>
    }

    Environment <|-- GithubCoreEnvironments
    Environment <|-- GithubRefEnvironments
    Environment <|-- GithubRunnerEnvironments
    Environment <|-- GithubSystemEnvironments
    GithubCoreEnvironments <|-- GithubEnvironment
    GithubRefEnvironments <|-- GithubEnvironment
    GithubRunnerEnvironments <|-- GithubEnvironment
    GithubSystemEnvironments <|-- GithubEnvironment

Base Methods¶

Method	Return Type	Description
`get(key)`	`String?`	Returns the value for the given key, or `null` if not set
`require(key)`	`String`	Returns the value or throws if not set
`toMap()`	`Map<String, String>`	Returns all environment variables as a map
`getBoolean(key, default?)`	`Boolean?`	Parses the value as a boolean
`getInt(key, default?)`	`Int?`	Parses the value as an integer
`getLong(key, default?)`	`Long?`	Parses the value as a long
`getDouble(key, default?)`	`Double?`	Parses the value as a double
`requireBoolean(key)`	`Boolean`	Returns boolean or throws
`requireInt(key)`	`Int`	Returns int or throws
`requireLong(key)`	`Long`	Returns long or throws
`requireDouble(key)`	`Double`	Returns double or throws

GitHub Core Environments¶

Source: environment/GithubCoreEnvironments.kt

Property	Environment Variable	Description
`action`	`GITHUB_ACTION`	The name of the current action
`actor`	`GITHUB_ACTOR`	The user or app that triggered the workflow
`repository`	`GITHUB_REPOSITORY`	The owner/repo (e.g., `"octocat/hello-world"`)
`repositoryOwner`	`GITHUB_REPOSITORY_OWNER`	The repository owner
`eventName`	`GITHUB_EVENT_NAME`	The event that triggered the workflow
`workflow`	`GITHUB_WORKFLOW`	The name of the workflow
`sha`	`GITHUB_SHA`	The commit SHA that triggered the workflow
`runId`	`GITHUB_RUN_ID`	The unique ID for the workflow run
`runNumber`	`GITHUB_RUN_NUMBER`	The run number for the workflow
`workspace`	`GITHUB_WORKSPACE`	The default working directory
`eventPath`	`GITHUB_EVENT_PATH`	Path to the JSON event payload file
`output`	`GITHUB_OUTPUT`	Path to the output file
`requireEventName`	`GITHUB_EVENT_NAME`	Same as `eventName` but throws if missing
`requireEventPath`	`GITHUB_EVENT_PATH`	Same as `eventPath` but throws if missing

GitHub Ref Environments¶

Source: environment/GithubRefEnvironments.kt

Property	Environment Variable	Description
`ref`	`GITHUB_REF`	The full ref path (e.g., `"refs/heads/main"`)
`refName`	`GITHUB_REF_NAME`	The short ref name (e.g., `"main"`)
`refType`	`GITHUB_REF_TYPE`	The ref type (`"branch"` or `"tag"`)
`baseRef`	`GITHUB_BASE_REF`	Base ref for pull requests
`headRef`	`GITHUB_HEAD_REF`	Head ref for pull requests

GitHub Runner Environments¶

Source: environment/GithubRunnerEnvironments.kt

Property	Environment Variable	Description
`runnerOs`	`RUNNER_OS`	Runner operating system (`"Linux"`, `"Windows"`, `"macOS"`)
`runnerArch`	`RUNNER_ARCH`	Runner architecture (`"X64"`, `"X86"`, `"ARM64"`)
`runnerName`	`RUNNER_NAME`	The name of the runner
`runnerTemp`	`RUNNER_TEMP`	Path to a temporary directory
`runnerWorkspace`	`RUNNER_WORKSPACE`	Path to the workspace directory

System Environments¶

Source: environment/GithubSystemEnvironments.kt

Property	Environment Variable	Description
`isCi`	`CI`	Whether running in CI (boolean)
`home`	`HOME`	The user's home directory
`path`	`PATH`	The system PATH

Implementations¶

GithubActionEnvironment (Internal)¶

Source: environment/GithubActionEnvironment.kt

Used in production GitHub Actions. Reads from System.getenv().

FakeEnvironment¶

Source: environment/FakeEnvironment.kt

Used for local testing. Accepts a Map<String, String> of values.

val env = FakeEnvironment(mapOf(
    "GITHUB_REPOSITORY" to "user/repo",
    "GITHUB_SHA" to "abc123",
    "CUSTOM_VAR" to "hello"
))

println(env.repository)  // "user/repo"
println(env["CUSTOM_VAR"])  // "hello"

Usage Examples¶

override fun run(context: PushContext, environment: GithubEnvironment): ActionResult {
    // Access typed properties
    val repo = environment.repository
    val sha = environment.sha
    val os = environment.runnerOs

    // Access custom variables
    val token = environment["GITHUB_TOKEN"]
    val apiUrl = environment["EMAIL_API_URL"]

    // Require specific variables (throws if missing)
    val requiredToken = environment.require("GITHUB_TOKEN")

    // Parse typed values
    val maxRetries = environment.getInt("MAX_RETRIES", default = 3)
    val isDebug = environment.getBoolean("DEBUG", default = false)

    return ActionResult.Success()
}