tkn-act

module

v1.2.0 Latest Latest Go to latest Published: May 3, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/danielfbm/tkn-act

Links

Open Source Insights

README ¶

tkn-act

Run Tekton Pipelines locally on Docker — no Kubernetes cluster required. Inspired by nektos/act.

Status

v1 alpha. Single Docker backend. k3d cluster backend planned for v1.x.

Install

go install github.com/dfbmorinigo/tkn-act/cmd/tkn-act@latest

Or via tkn's plugin discovery — drop the binary on your PATH and run tkn act ....

Usage

cd my-repo-with-pipeline.yaml
tkn-act               # auto-discovers pipeline.yaml / .tekton/

tkn-act run -f pipeline.yaml -p revision=main -w shared=./build
tkn-act validate
tkn-act list

What's supported (v1)

Tekton tekton.dev/v1 Task, Pipeline, PipelineRun, TaskRun
Steps with image, command, args, script, env, workingDir
Params (string, array, object), defaults, $(params.x) and $(params.x[*])
Results (file-based at /tekton/results/<n>) and $(tasks.X.results.Y)
Workspaces shared across tasks (host bind mounts)
DAG ordering via runAfter and result-data deps
when expressions (operator: in, notin)
finally tasks

What's not supported in v1

Sidecars, StepActions, retries, Resolvers (git/hub/cluster), tekton-results, custom tasks, signed pipelines, Windows.

See docs/superpowers/specs/2026-05-01-tkn-act-design.md for the full spec.

Cluster backend (v1.1)

For Tekton-fidelity runs (real controller, real entrypoint shim):

tkn-act cluster up               # one-time, ~30-60s
tkn-act run --cluster -f pipeline.yaml
tkn-act cluster status
tkn-act cluster down

Requires k3d and kubectl on PATH.

For AI agents

tkn-act has first-class support for AI agents and scripts:

AGENTS.md — canonical guide (also embedded; print with tkn-act agent-guide).
tkn-act doctor -o json — preflight: Docker, k3d, kubectl, cache dir.
tkn-act help-json — full command/flag/example tree as JSON.
Every command supports --output json with a stable shape.
Stable, documented exit codes (0 ok, 2 usage, 3 env, 4 validate, 5 pipeline, 130 cancelled).

License

Apache 2.0

Directories ¶

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

Path	Synopsis
cmd
tkn-act command
internal
backend Package backend defines the contract between the engine and an execution substrate (Docker, k3d, ...).	Package backend defines the contract between the engine and an execution substrate (Docker, k3d, ...).
backend/cluster Package cluster implements backend.Backend by submitting PipelineRuns to a real Tekton install on a local Kubernetes cluster (k3d).	Package cluster implements backend.Backend by submitting PipelineRuns to a real Tekton install on a local Kubernetes cluster (k3d).
backend/docker Package docker implements backend.Backend using a local Docker daemon.	Package docker implements backend.Backend using a local Docker daemon.
cluster Package cluster defines the local-Kubernetes driver abstraction.	Package cluster defines the local-Kubernetes driver abstraction.
cluster/k3d Package k3d implements cluster.Driver by shelling out to the k3d binary.	Package k3d implements cluster.Driver by shelling out to the k3d binary.
cluster/tekton Package tekton installs the Tekton Pipelines controller into a Kubernetes cluster.	Package tekton installs the Tekton Pipelines controller into a Kubernetes cluster.
cmdrunner Package cmdrunner wraps os/exec so unit tests can substitute a fake.	Package cmdrunner wraps os/exec so unit tests can substitute a fake.
discovery Package discovery finds Tekton YAML files in a project directory using a fixed priority order: pipelinerun.yaml, pipeline.yaml, .tekton/, tekton/.	Package discovery finds Tekton YAML files in a project directory using a fixed priority order: pipelinerun.yaml, pipeline.yaml, .tekton/, tekton/.
e2e/fixtures Package fixtures is the single source of truth for the e2e fixture set shared between the docker-backend harness (internal/e2e) and the cluster- backend harness (internal/clustere2e).	Package fixtures is the single source of truth for the e2e fixture set shared between the docker-backend harness (internal/e2e) and the cluster- backend harness (internal/clustere2e).
engine Package engine orchestrates a Tekton PipelineRun.	Package engine orchestrates a Tekton PipelineRun.
engine/dag Package dag implements a small directed acyclic graph: build, topological level grouping, cycle detection, descendant traversal.	Package dag implements a small directed acyclic graph: build, topological level grouping, cycle detection, descendant traversal.
exitcode Package exitcode defines the stable exit-code contract for the tkn-act CLI and provides a small error-wrapper that lets command implementations associate an error with a specific code without coupling them to the main package.	Package exitcode defines the stable exit-code contract for the tkn-act CLI and provides a small error-wrapper that lets command implementations associate an error with a specific code without coupling them to the main package.
loader Package loader parses one or more Tekton YAML files into a Bundle of typed resources keyed by name.	Package loader parses one or more Tekton YAML files into a Bundle of typed resources keyed by name.
reporter Package reporter formats engine events for the user.	Package reporter formats engine events for the user.
resolver Package resolver performs Tekton-style variable substitution:	Package resolver performs Tekton-style variable substitution:
tektontypes Package tektontypes defines minimal Go types matching the tekton.dev/v1 schema for Task, TaskRun, Pipeline, and PipelineRun.	Package tektontypes defines minimal Go types matching the tekton.dev/v1 schema for Task, TaskRun, Pipeline, and PipelineRun.
validator Package validator runs semantic checks on a loaded Bundle: refs resolve, the pipeline DAG has no cycles, workspaces are bound, params are present.	Package validator runs semantic checks on a loaded Bundle: refs resolve, the pipeline DAG has no cycles, workspaces are bound, params are present.
volumes Package volumes resolves Tekton TaskSpec.Volumes into host directories the docker backend can bind-mount.	Package volumes resolves Tekton TaskSpec.Volumes into host directories the docker backend can bind-mount.
workspace Package workspace materializes Tekton workspaces as host directories that the Docker backend can bind-mount into Step containers.	Package workspace materializes Tekton workspaces as host directories that the Docker backend can bind-mount into Step containers.