{"id":49648540,"url":"https://github.com/danielfbm/tkn-act","last_synced_at":"2026-05-06T03:36:37.400Z","repository":{"id":355329773,"uuid":"1226252201","full_name":"danielfbm/tkn-act","owner":"danielfbm","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-03T04:20:57.000Z","size":392,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-03T04:25:08.560Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danielfbm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-01T06:42:04.000Z","updated_at":"2026-05-03T04:21:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/danielfbm/tkn-act","commit_stats":null,"previous_names":["danielfbm/tkn-act"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/danielfbm/tkn-act","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfbm%2Ftkn-act","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfbm%2Ftkn-act/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfbm%2Ftkn-act/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfbm%2Ftkn-act/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielfbm","download_url":"https://codeload.github.com/danielfbm/tkn-act/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfbm%2Ftkn-act/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32677933,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T02:33:58.958Z","status":"ssl_error","status_checked_at":"2026-05-06T02:33:39.611Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-06T03:36:34.035Z","updated_at":"2026-05-06T03:36:37.386Z","avatar_url":"https://github.com/danielfbm.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tkn-act\n\nRun [Tekton Pipelines](https://tekton.dev) locally — on Docker, or on an\nephemeral [k3d](https://k3d.io) cluster with a real Tekton controller.\nNo production Kubernetes required. Inspired by\n[`nektos/act`](https://github.com/nektos/act).\n\n## Status\n\nv1.4 — `tekton.dev/v1` Pipelines and Tasks run locally with two\nbackends, structured JSON output, and stable exit codes for CI/agents.\nSee [`docs/feature-parity.md`](docs/feature-parity.md) for the full\nshipped/in-progress/gap scoreboard.\n\n## Quickstart\n\nIf you have Docker, [`k3d`](https://k3d.io), and `kubectl` on your\n`PATH`:\n\n    make quickstart\n\nThat builds `bin/tkn-act`, boots a local k3d cluster, installs Tekton,\nand runs the `testdata/e2e/hello/pipeline.yaml` fixture against the real\ncontroller. If anything is missing, run `make doctor` first — it prints\ninstall hints and pinned versions matching the\n[`cluster-integration`](.github/workflows/cluster-integration.yml) CI\njob. `make help` lists every target; [`AGENTS.md`](AGENTS.md) is the\ncanonical agent / JSON contract.\n\n## Install\n\n    go install github.com/dfbmorinigo/tkn-act/cmd/tkn-act@latest\n\nOr via `tkn`'s plugin discovery — drop the binary on your `PATH` and\nrun `tkn act ...`.\n\n## Usage\n\n    cd my-repo-with-pipeline.yaml\n    tkn-act                                # auto-discovers pipeline.yaml / .tekton/\n    tkn-act run -f pipeline.yaml -p revision=main -w shared=./build\n    tkn-act validate\n    tkn-act list\n\nFor machine-readable output (CI, agents, scripts):\n\n    tkn-act doctor      -o json            # preflight environment check\n    tkn-act run         -o json -f pipeline.yaml   # one event per line on stdout\n    tkn-act validate    -o json\n    tkn-act list        -o json\n    tkn-act help-json                      # full command/flag tree\n\n## Two backends\n\n| Mode | Trigger | Fidelity | Speed | Needs |\n|---|---|---|---|---|\n| Docker (default) | (no flag) | Each Step is a container | Fast (\u003c1s startup) | Docker daemon |\n| Cluster | `--cluster` | Real Tekton controller, real entrypoint shim | ~30–60s first run | `k3d`, `kubectl` |\n\n```sh\ntkn-act cluster up                         # one-time, ~30-60s\ntkn-act run --cluster -f pipeline.yaml\ntkn-act cluster status\ntkn-act cluster down -y\n```\n\nCross-backend fixtures in [`internal/e2e/fixtures`](internal/e2e/fixtures/fixtures.go)\nare exercised by both backends in CI — divergences are explicit\n`DockerOnly` / `ClusterOnly` flags, never silent omissions.\n\n## Tekton features supported\n\n- `tekton.dev/v1` `Task`, `Pipeline`, `PipelineRun`, `TaskRun`\n- Steps with `image`, `command`, `args`, `script`, `env`, `workingDir`,\n  `imagePullPolicy`, `resources`, `onError`, per-step `results`\n- Params (string, array, object), defaults, `$(params.x)` and\n  `$(params.x[*])`\n- Results (file-based at `/tekton/results/\u003cn\u003e`) and\n  `$(tasks.X.results.Y)`\n- `Pipeline.spec.results` — named outputs surfaced on the `run-end`\n  event (string / array / object); resolved from task results after\n  the entire run completes\n- Workspaces shared across tasks (host bind mounts)\n- DAG ordering via `runAfter` and result-data deps\n- `when` expressions (`in` / `notin`)\n- `finally` tasks\n- `Task.spec.timeout` (per-task) and `Pipeline.spec.timeouts.{pipeline,\n  tasks, finally}` (whole-run / DAG / finally budgets)\n- `PipelineTask.retries`\n- Volumes: `emptyDir`, `hostPath`, `configMap`, `secret`\n  (inline via `--configmap`/`--secret`, directory layout via\n  `--configmap-dir`/`--secret-dir`, or `kind: ConfigMap` /\n  `kind: Secret` resources embedded directly in the `-f` YAML stream)\n- `Task.spec.stepTemplate` — Steps inherit `image`, `command`, `args`,\n  `env`, `workingDir`, `imagePullPolicy`, `resources` from a per-Task\n  base template (`env` merged by name; Step values always win)\n- `displayName` / `description` on Task / Pipeline / PipelineTask / Step\n  — surfaced on the JSON event stream as `display_name` / `description`,\n  preferred over `name` in pretty output\n- `taskRef.resolver` / `pipelineRef.resolver` — **fully shipped in\n  v1.6**: scaffolding (types, lazy dispatch at task-dispatch time,\n  eager top-level pipelineRef resolution at load time, cluster-backend\n  inline-before-submit, validator pre-flight, two new event kinds —\n  `resolver-start` / `resolver-end`, and CLI flags), plus the\n  **direct `git` resolver** (Phase 2): shallow clones a repo via\n  `go-git/v5` and reads `pathInRepo` at the requested revision; HTTPS\n  / file:// / ssh:// honored, plain http:// refused unless\n  `--resolver-allow-insecure-http` is set. **`hub` and `http` direct\n  resolvers ship in Phase 3** (HTTPS-only by default; loopback http\n  exempt; bearer-token via `HubOptions.Token` / `HTTPOptions.Token` /\n  env `TKNACT_HTTP_RESOLVER_TOKEN`; 5xx single-retry budget). **`bundles`\n  and `cluster` direct resolvers ship in Phase 4** — `bundles` pulls\n  Tekton OCI bundles via `go-containerregistry`, walks layer\n  `dev.tekton.image.{name,kind,apiVersion}` annotations, and returns\n  the layer's embedded YAML (HTTPS-only by default; loopback exempt;\n  `--resolver-allow-insecure-http` opens HTTP for non-loopback\n  registries; auth honors `~/.docker/config.json`); `cluster` reads\n  Tekton resources via the kube dynamic client and is **OFF BY\n  DEFAULT** for safety (KUBECONFIG may point at production) — opt in\n  via `--cluster-resolver-context=\u003cctx\u003e` or by adding `cluster` to\n  `--resolver-allow`. **Mode B — remote resolver via\n  `ResolutionRequest` CRD ships in Phase 5**: setting\n  `--remote-resolver-context=\u003ckubeconfig-context\u003e` flips the registry\n  into Mode B, where every `taskRef.resolver:` block is dispatched\n  by submitting a `resolution.tekton.dev/v1beta1.ResolutionRequest`\n  to the remote cluster, watching `status.conditions[Succeeded]`,\n  and decoding `status.data`. Wire-compat: v1beta1 first, with\n  v1alpha1 fallback for older Tekton Resolution installs. Cleanup\n  discipline: the `ResolutionRequest` is always Deleted on the way\n  out (success / failure / timeout / `context.Cancel`). Pair with\n  `--remote-resolver-namespace=\u003cns\u003e` (default `default`) and\n  `--remote-resolver-timeout=\u003cduration\u003e` (default `60s`). Arbitrary\n  custom resolver names are valid in Mode B (the validator's\n  allow-list is short-circuited). **Phase 6** ships `--offline`\n  end-to-end (validate-time + run-time), an on-disk cross-run cache\n  (every direct resolver writes\n  `\u003c--resolver-cache-dir\u003e/\u003cresolver\u003e/\u003csha256\u003e.{yaml,json}`; second\n  runs surface `cached: true` on `resolver-end`), and the\n  `tkn-act cache list / prune --older-than / clear -y` subcommand\n  family. See\n  [`docs/superpowers/plans/2026-05-04-resolvers.md`](docs/superpowers/plans/2026-05-04-resolvers.md)\n- `PipelineTask.matrix` — Cartesian-product fan-out across named\n  string-list params, plus optional `include` rows for named extras.\n  Per-row `when:`, result aggregation (`$(tasks.X.results.Y[*])`),\n  256-row cardinality cap. Cluster-backend round-trip via canonical\n  param-hash matching.\n- `Task.spec.sidecars` — long-lived helper containers (databases,\n  proxies, mock services). On `--docker`, a tiny per-Task pause\n  container owns the netns and steps + sidecars all join it via\n  `network_mode: container:\u003cpause-id\u003e` so steps reach sidecars at\n  `localhost:\u003cport\u003e`. Two new flags: `--sidecar-start-grace`\n  (default 2s) and `--sidecar-stop-grace` (default 30s, matches\n  upstream Tekton's `terminationGracePeriodSeconds`). Cluster\n  pass-through forwards the full Tekton schema; `sidecar-start` /\n  `sidecar-end` events fire on both backends.\n- `StepAction` (`apiVersion: tekton.dev/v1beta1`, `kind: StepAction`)\n  — referenceable Step shapes inlined client-side into Steps that\n  carry `ref: {name: ...}`. Caller `params:` bind to the StepAction's\n  declared params (defaults applied for omitted bindings); the\n  StepAction's `results:` flow through to the per-step results dir\n  unchanged. Local-files-only resolution: resolver-form refs\n  (`hub`, `git`, `cluster`, `bundles`) are tracked under Track 1 #9.\n\nThe single source of truth, with one row per Tekton field and links to\nfixtures, plans, and PRs, is\n[`docs/feature-parity.md`](docs/feature-parity.md). CI's `parity-check`\njob enforces that the table doesn't drift from the tree.\n\n## Not yet supported\n\nCustom tasks, signed pipelines, tekton-results, Windows.\n(`taskRef.resolver` is shipped for the five canonical names — `git`,\n`hub`, `http`, `bundles`, `cluster` — plus Mode B remote resolution\nvia `ResolutionRequest`, `--offline` mode, and the `tkn-act cache`\nsubcommand family.)\n\nSee [`docs/short-term-goals.md`](docs/short-term-goals.md) for the\nprioritized track of what's next.\n\n## For AI agents and CI\n\n`tkn-act` has first-class support for AI agents and scripts:\n\n- Stable JSON shapes on every command (`--output json`).\n- Stable exit codes: `0` ok, `2` usage, `3` env, `4` validate,\n  `5` pipeline failure, `6` timeout, `130` cancelled.\n- `tkn-act doctor -o json` — preflight: Docker, k3d, kubectl, cache dir.\n- `tkn-act help-json` — full command / flag / example tree.\n- `tkn-act agent-guide` prints the embedded agent guide\n  ([`AGENTS.md`](AGENTS.md)) — also the canonical place to read about\n  conventions, exit codes, JSON contracts, and the project rule that\n  every change must update related docs in the same PR.\n\n## Documentation\n\n| Document | Purpose |\n|---|---|\n| [`AGENTS.md`](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`). |\n| [`docs/feature-parity.md`](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`. |\n| [`docs/short-term-goals.md`](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. |\n| [`docs/test-coverage.md`](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`. |\n\n## License\n\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielfbm%2Ftkn-act","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielfbm%2Ftkn-act","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielfbm%2Ftkn-act/lists"}