tkn-act

module

v1.4.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, or on an ephemeral k3d cluster with a real Tekton controller. No production Kubernetes required. Inspired by nektos/act.

Status

v1.4 — tekton.dev/v1 Pipelines and Tasks run locally with two backends, structured JSON output, and stable exit codes for CI/agents. See docs/feature-parity.md for the full shipped/in-progress/gap scoreboard.

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

For machine-readable output (CI, agents, scripts):

tkn-act doctor      -o json            # preflight environment check
tkn-act run         -o json -f pipeline.yaml   # one event per line on stdout
tkn-act validate    -o json
tkn-act list        -o json
tkn-act help-json                      # full command/flag tree

Two backends

Mode	Trigger	Fidelity	Speed	Needs
Docker (default)	(no flag)	Each Step is a container	Fast (<1s startup)	Docker daemon
Cluster	`--cluster`	Real Tekton controller, real entrypoint shim	~30–60s first run	`k3d`, `kubectl`

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

Cross-backend fixtures in internal/e2e/fixtures are exercised by both backends in CI — divergences are explicit DockerOnly / ClusterOnly flags, never silent omissions.

Tekton features supported

tekton.dev/v1 Task, Pipeline, PipelineRun, TaskRun
Steps with image, command, args, script, env, workingDir, imagePullPolicy, resources, onError, per-step results
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 (in / notin)
finally tasks
Task.spec.timeout (per-task) and Pipeline.spec.timeouts.{pipeline, tasks, finally} (whole-run / DAG / finally budgets)
PipelineTask.retries
Volumes: emptyDir, hostPath, configMap, secret (inline via --configmap/--secret or directory layout)
Task.spec.stepTemplate — Steps inherit image, command, args, env, workingDir, imagePullPolicy, resources from a per-Task base template (env merged by name; Step values always win)

The single source of truth, with one row per Tekton field and links to fixtures, plans, and PRs, is docs/feature-parity.md. CI's parity-check job enforces that the table doesn't drift from the tree.

Not yet supported

Sidecars (cluster-only), StepActions, Resolvers (git/hub/cluster/ bundles), PipelineTask.matrix, custom tasks, signed pipelines, tekton-results, Windows.

See docs/short-term-goals.md for the prioritized track of what's next.

For AI agents and CI

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

Stable JSON shapes on every command (--output json).
Stable exit codes: 0 ok, 2 usage, 3 env, 4 validate, 5 pipeline failure, 6 timeout, 130 cancelled.
tkn-act doctor -o json — preflight: Docker, k3d, kubectl, cache dir.
tkn-act help-json — full command / flag / example tree.
tkn-act agent-guide prints the embedded agent guide (AGENTS.md) — also the canonical place to read about conventions, exit codes, JSON contracts, and the project rule that every change must update related docs in the same PR.

Documentation

Document	Purpose
`AGENTS.md`	Canonical guide for AI agents and scripts: machine-readable interfaces, exit codes, JSON shapes, environment variables, and project rules (squash-merge, tests-required, docs-sync). Also embedded in the binary (`tkn-act agent-guide`).
`docs/feature-parity.md`	Single source of truth for which Tekton features are `shipped` / `in-progress` / `gap`, with the e2e fixture and limitations fixture per row. CI gate: `parity-check`.
`docs/short-term-goals.md`	Prioritized tracks for upcoming work (Track 1 = Tekton features, Track 2 = backend parity, Track 3 = ergonomics). Status updated as items land.
`docs/test-coverage.md`	What runs in each CI workflow, which paths trigger which workflow, and which fixtures are in `-tags integration` vs `-tags cluster`.

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.