kuranto

kuranto implements Forgejo Runner v13's experimental plugin.v1alpha.BackendPlugin gRPC interface. It creates one Kubernetes Pod per Actions job and executes workflow commands using the Kubernetes pods/exec subresource.

The Forgejo plugin protocol is alpha. This implementation currently targets Forgejo Runner v13.1.0.

Execution model

kuranto runs as a container alongside the Forgejo Runner in one pod. The runner talks to kuranto through its gRPC plugin interface. When picking up jobs, the runner instructs the plugin to execute it; kuranto then creates job pods in its configured namespace.

A job pod is:

• a job container using the label's image, or the workflow's configured image;
• an emptyDir mounted on /shared for ephemeral storage during job execution, and a writable /tmp;
• optional service containers as sidecars, reachable by their service name on 127.0.0.1

The job pod has no access to the Kubernetes cluster, and empty service account is mounted, which has no permissions at all.

Configuration

The plugin reads these environment variables:

Variable	Required	Default	Purpose
KUBERNETES_NAMESPACE	yes	—	Dedicated namespace in which it may create job Pods.
LISTEN_ADDR	no	0.0.0.0:50051	gRPC listener.
DEFAULT_JOB_IMAGE	no	data.forgejo.org/oci/node:lts	Used if the runner sends no image.
JOB_SERVICE_ACCOUNT	no	none	Service account assigned to generated job Pods. It should have no Kubernetes RBAC by default.
JOB_CPU_REQUEST	no	none	CPU request for each generated primary job container, for example 250m.
JOB_MEMORY_REQUEST	no	none	Memory request for each generated primary job container, for example 512Mi.
JOB_CPU_LIMIT	no	none	CPU limit for each generated primary job container, for example 1.
JOB_MEMORY_LIMIT	no	none	Memory limit for each generated primary job container, for example 1Gi.
MAX_ENVIRONMENT_TIMEOUT_SECONDS	no	10800	Upper bound for a job Pod's activeDeadlineSeconds.

Resource values use Kubernetes quantity syntax. When unset, the corresponding resource field is omitted. These settings apply only to the generated primary job container.

Development

cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release