actions-toolkit-go

module

v0.2.0 Latest Latest Go to latest Published: Oct 20, 2026 License: MIT

README ¶

actions-toolkit-go

A toolkit for writing GitHub Actions in Go, patterned after the JavaScript actions/toolkit. The API is Go-shaped rather than a line-for-line port. Requires Go 1.27 or later.

go get github.com/asteroid-computing/actions-toolkit-go

The API is not yet stable: while the version is below 1.0.0, a minor release may contain breaking changes, which CHANGELOG.md calls out.

Packages

core — inputs (GetInput, GetBooleanInput, GetMultilineInput), outputs and file commands (SetOutput, SetOutputJSON, SetEnv, SetState/GetState, AddToPath), logging and workflow commands (Info, Debug, Notice, Warning, Error, Group, StartGroup/EndGroup, MaskValue, StopCommands, SetCommandEcho, IsDebug), path separator conversion (ToPosixPath, ToWin32Path, ToPlatformPath), failing the step (SetFailed), GitHub OIDC ID tokens for keyless cloud authentication (GetIDToken) and the job summary builder (StepSummary).
actioncontext — the run's context, read by actioncontext.Load() from the default environment variables, with the event payload decoded into the matching go-github type (PullRequestEvent(), PushEvent(), …), the raw payload (RawEventPayload()), and NewGitHubClient targeting the run's API host (github.com or GHES).

package main

import (
	"fmt"
	"os"

	"github.com/asteroid-computing/actions-toolkit-go/actioncontext"
	"github.com/asteroid-computing/actions-toolkit-go/core"
)

func main() {
	name, err := core.GetInput("name", &core.InputOptions{Required: true})
	if err != nil {
		core.Error(err.Error(), nil)
		os.Exit(1)
	}
	ac, err := actioncontext.Load()
	if err != nil {
		core.Error(err.Error(), nil)
		os.Exit(1)
	}
	if pr, ok := ac.PullRequestEvent(); ok {
		fmt.Printf("PR #%d\n", pr.GetNumber())
	}
	core.SetOutput("greeting", "Hello, "+name)
}

cmd/example is a complete example.

Developing

Tooling is plain Go behind the ./walle task runner: ./walle --help lists the tasks, and ./walle check is the gate CI runs. AGENTS.md has the layout, rules and conventions.

Releases are cut by release-please from Conventional Commits on main: merging its release PR tags vX.Y.Z and publishes the GitHub release. See CHANGELOG.md.

Contributions are welcome; see CONTRIBUTING.md. Report security issues as described in SECURITY.md, not in public issues.

License

MIT

Directories ¶

Path	Synopsis
actioncontext Package actioncontext provides the GitHub Actions runtime context of the current step.	Package actioncontext provides the GitHub Actions runtime context of the current step.
cmd
example command Command example is a minimal GitHub Action step built on this toolkit.	Command example is a minimal GitHub Action step built on this toolkit.
github-actions/build command Command build is the Go entry point of the build GitHub Action: it compiles release components in the caller's job with internal/buildrun — the code `./walle build` runs — and writes the outcome to the job summary.	Command build is the Go entry point of the build GitHub Action: it compiles release components in the caller's job with internal/buildrun — the code `./walle build` runs — and writes the outcome to the job summary.
github-actions/changed-scope command Command changed-scope is the Go entry point of the changed-scope GitHub Action: it reports which release components a change touched, so the workflow builds and validates only those.	Command changed-scope is the Go entry point of the changed-scope GitHub Action: it reports which release components a change touched, so the workflow builds and validates only those.
walle command Command walle is the project's developer task runner: build, check, inspect and maintain, in plain Go.	Command walle is the project's developer task runner: build, check, inspect and maintain, in plain Go.
core Package core provides helpers for emitting GitHub Actions workflow commands and working with runner-provided files.	Package core provides helpers for emitting GitHub Actions workflow commands and working with runner-provided files.
internal
buildrun Package buildrun compiles the project's release components and its Go GitHub Actions.	Package buildrun compiles the project's release components and its Go GitHub Actions.
buildscope Package buildscope is the registry of the project's release components and the engine that computes each one's build closure: the module-local packages and files that compile into its entry-point binary.	Package buildscope is the registry of the project's release components and the engine that computes each one's build closure: the module-local packages and files that compile into its entry-point binary.
cireport Package cireport renders a CI step's outcome as markdown for the workflow job summary, so a reader sees what was built (and what failed, and how long it took) on the run page instead of expanding a log.	Package cireport renders a CI step's outcome as markdown for the workflow job summary, so a reader sees what was built (and what failed, and how long it took) on the run page instead of expanding a log.
gocache Package gocache trims the Go build cache to the working set of one CI run, so the cache CI saves stays the size of what a build actually uses instead of accreting a layer of stale compile output with every save.	Package gocache trims the Go build cache to the working set of one CI run, so the cache CI saves stays the size of what a build actually uses instead of accreting a layer of stale compile output with every save.
gocmd Package gocmd runs child processes — mostly the go toolchain — for walle and the Go GitHub Actions.	Package gocmd runs child processes — mostly the go toolchain — for walle and the Go GitHub Actions.
version Package version carries the project's version.	Package version carries the project's version.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL