tektoncd-catalog · vdemeester · Jul 3, 2026 · Jul 3, 2026 · Jul 3, 2026 · Jul 3, 2026
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+keys/signing-key.pem
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,47 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in `tektoncd-catalog/kaniko`. For full
+detail see [DEVELOPMENT.md](DEVELOPMENT.md).
+
+## Repository structure
+
+| Path | Role |
+|------|------|
+| `task/kaniko/kaniko.yaml` | **Edit this.** The `kaniko` Task — the single source of truth. |
+| `stepaction/kaniko/kaniko.yaml` | **Generated — never edit by hand.** Derived from the Task. |
+| `hack/generate-stepaction.sh` | Wrapper around the Python generator. |
+| `hack/generate-stepaction.py` | Derives the StepAction from the Task (workspaces → params). |
+| `hack/release.sh` | Release automation. |
+| `test/` | e2e runners (`e2e-tests.sh`, `e2e-bundle-test.sh`). |
+| `.github/workflows/` | `build.yaml` (lint/e2e), `release.yaml` (bundle publish). |
+
+## Critical Rules
+
+1. **Never edit `stepaction/kaniko/kaniko.yaml` directly.** It is generated
+   from the Task. Edit `task/kaniko/kaniko.yaml`, then run
+   `./hack/generate-stepaction.sh`. CI's lint step diffs the committed file
+   against a freshly generated one and fails on mismatch.
+2. **No `$(params.*)` in `script:` blocks.** For StepActions `$(params.*)` in
+   scripts is not supported. Pass values via `env:` and reference the shell
+   env var.
+3. **Workspaces map to params in the StepAction.** `source` → `source-path`,
+   `dockerconfig` → `dockerconfig-path`.
+4. **Sign off every commit** (DCO / EasyCLA): `git commit --signoff`.
+5. **Use conventional commit prefixes** (`feat:`, `fix:`, `docs:`, `chore:`,
+   `ci:`) — the release changelog is derived from them.
+
+## Common commands
+
+```bash
+./hack/generate-stepaction.sh          # regenerate the StepAction from the Task
+./hack/release.sh v0.2.0 --dry-run    # preview a release
+./test/e2e-tests.sh                    # e2e in a kind cluster
+./test/e2e-bundle-test.sh              # bundle-resolver e2e
+```
+
+## Validating changes locally
+
+1. After editing the Task, run `./hack/generate-stepaction.sh`.
+2. Confirm `git status` shows only intended changes.
+3. Run the relevant e2e script against a kind cluster.
+4. Update `README.md` if you changed installation or usage.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,60 @@
+# Contributing
+
+Thanks for your interest in contributing to `tektoncd-catalog/kaniko`! This
+repository is part of the Tekton Catalog and follows the broader
+[tektoncd-catalog contributing guide](https://github.com/tektoncd-catalog/.github/blob/main/CONTRIBUTING.md).
+
+For technical details on how the repo is structured and generated, see
+[DEVELOPMENT.md](DEVELOPMENT.md).
+
+## Developer Certificate of Origin (DCO) / CLA
+
+All commits must be signed off to certify the
+[Developer Certificate of Origin](https://developercertificate.org/). Add a
+`Signed-off-by` trailer to every commit:
+
+```bash
+git commit --signoff -m "fix: update kaniko image version"
+```
+
+The sign-off line must match the author's name and email. Contributions are
+also covered by the Linux Foundation
+[EasyCLA](https://github.com/tektoncd/community/blob/main/process.md#contributor-license-agreements)
+check, which runs on pull requests — follow its prompt to sign the CLA the
+first time you contribute.
+
+## Pull request workflow
+
+1. **Fork and branch** from `main`.
+2. **Edit the Task** (`task/kaniko/kaniko.yaml`) — never edit the generated
+   `stepaction/kaniko/kaniko.yaml` directly.
+3. **Regenerate** the StepAction and commit both files:
+   ```bash
+   ./hack/generate-stepaction.sh
+   git add task/ stepaction/
+   ```
+4. **Test locally** (see [DEVELOPMENT.md](DEVELOPMENT.md#running-tests-locally)).
+5. **Use conventional commit messages** (`feat:`, `fix:`, `docs:`, `chore:`,
+   `ci:`) — the release changelog is derived from these prefixes.
+6. **Open a PR** with a clear description.
+
+Approvals are managed via `OWNERS` (Prow-based auto-merge).
+
+## CI expectations
+
+Every PR runs `.github/workflows/build.yaml`, which must pass:
+
+- **Lint** — validates YAML structure and verifies the StepAction is in sync
+  with the Task.
+- **E2E** — installs the Task in a Kind cluster and builds a test image
+  across supported Tekton Pipelines LTS versions.
+
+> [!TIP]
+> Before pushing, run `./hack/generate-stepaction.sh` and make sure
+> `git status` is clean (apart from your intended changes). A stale StepAction
+> is the most common CI failure.
+
+## Code of conduct
+
+This project follows the Tekton
+[Code of Conduct](https://github.com/tektoncd/community/blob/main/code-of-conduct.md).
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -0,0 +1,115 @@
+# Development
+
+This document explains how the `tektoncd-catalog/kaniko` repository is
+structured and how to develop, generate, test, and release its Task and
+StepAction.
+
+> [!IMPORTANT]
+> The `task/` directory is the **source of truth**. The `stepaction/` directory
+> is **generated** from it. Never edit `stepaction/kaniko/kaniko.yaml`
+> directly — edit the Task and run `./hack/generate-stepaction.sh`.
+
+## Architecture overview
+
+The repository ships a `kaniko` [Task](task/kaniko/) and a derived
+[StepAction](stepaction/kaniko/) for Tekton Pipelines. Both use the
+`ghcr.io/osscontainertools/kaniko` executor image (the community-maintained
+fork of the archived Google kaniko project).
+
+```
+task/kaniko/kaniko.yaml  ─────────── (source of truth)
+        │
+        └─► hack/generate-stepaction.py ──► stepaction/kaniko/kaniko.yaml
+                                            (generated — do not edit)
+```
+
+Key files:
+
+| Path | Role |
+|------|------|
+| `task/kaniko/kaniko.yaml` | **Hand-edited.** The `kaniko` Task — the single source of truth. |
+| `stepaction/kaniko/kaniko.yaml` | **Generated** from the Task. Do not edit. |
+| `hack/generate-stepaction.sh` | Wrapper that runs the Python generator. |
+| `hack/generate-stepaction.py` | Derives the StepAction from the Task (workspaces → params). |
+| `hack/release.sh` | Release automation: bump version → regenerate → changelog → commit → tag → push. |
+| `test/` | e2e runners (`e2e-tests.sh`, `e2e-bundle-test.sh`). |
+| `.github/workflows/` | `build.yaml` (lint/e2e), `release.yaml` (bundle publish). |
+
+### Why generate the StepAction?
+
+- **Deterministic:** CI regenerates the StepAction and diffs it against what's
+  committed. The committed file must match exactly.
+- **DRY:** The StepAction is a mechanical transform of the Task, so behaviour
+  stays in lockstep instead of being maintained by hand in two places.
+
+## How generation works
+
+Run:
+
+```bash
+./hack/generate-stepaction.sh
+```
+
+Requirements: `python3` with **PyYAML**. If PyYAML isn't importable directly,
+the wrapper falls back to `uv tool run --with pyyaml`.
+
+`generate-stepaction.py` parses the Task's build step and produces a StepAction:
+
+- **Workspaces become params.** `source` → `source-path`, `dockerconfig` →
+  `dockerconfig-path`.
+- **Both steps merge into one.** The kaniko executor runs via a script, and the
+  URL result is written in the same step.
+- **Script references use env vars** (never `$(params.*)`) because `$(params.*)`
+  substitution is not allowed in StepAction scripts.
+
+## Modifying the Task or StepAction
+
+1. Edit `task/kaniko/kaniko.yaml`.
+2. Regenerate the StepAction:
+   ```bash
+   ./hack/generate-stepaction.sh
+   ```
+3. Review both files and commit them together.
+
+## Running tests locally
+
+E2e tests run against a real Tekton install in a local
+[kind](https://kind.sigs.k8s.io/) cluster:
+
+```bash
+kind create cluster
+./test/e2e-tests.sh
+./test/e2e-bundle-test.sh
+```
+
+Useful environment variables:
+
+| Var | Default | Meaning |
+|-----|---------|---------|
+| `PIPELINE_VERSION` | `v1.12.0` | Tekton Pipelines release to install |
+| `TIMEOUT` | `180s` | Per-TaskRun timeout |
+| `BUNDLE_REGISTRY` | `ttl.sh` | Registry the bundle test pushes to |
+
+## Release process
+
+Releases are driven by `hack/release.sh`:
+
+```bash
+./hack/release.sh v0.2.0 --dry-run    # preview the diff
+./hack/release.sh v0.2.0              # bump, regenerate, commit, tag, push
+```
+
+What it does:
+
+1. Validates the version (`vX.Y.Z`) and that you're on an up-to-date `main`.
+2. Bumps the `app.kubernetes.io/version` label in the Task and StepAction.
+3. Regenerates the StepAction from the bumped Task.
+4. Commits (`--signoff`), pushes `main`, creates an annotated tag, and pushes
+   the tag.
+
+The tag push triggers `.github/workflows/release.yaml`, which publishes a
+Tekton bundle to `ghcr.io/tektoncd-catalog/kaniko`.
+
+## See also
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) — contribution workflow and CI expectations.