Guidelines for AI agents working on this codebase.
The Apache Camel Kamelet Catalog is the default catalog of reusable Camel route templates (“Kamelets”), distributed as Kubernetes-style YAML and consumed by Camel, Camel K, Camel Quarkus and Camel Spring Boot.
mvn verify); Go is required for the crds/ generatorapache/camel (Camel core — the Kamelet runtime lives there, not here)These rules apply to ALL AI agents working on this codebase.
apache/camel-kamelets repository, to avoid filling the main repository with uncleaned branches.ci-issue-<ISSUE_NUMBER>, quick-fix → quick-fix/<short-slug>, CI fix → ci-fix/<short-slug>. Include the topic and issue number where possible.good first issue label; experienced tasks carry help wanted.Fix #<ISSUE_NUMBER>: <brief description>chore: <brief description>ci: <brief description>When pushing new commits to a PR, always update the PR description (and title if needed) to reflect the current state of the changeset. Use gh pr edit --title "..." --body "..." after each push.
When creating a PR, always identify and request reviews from the most relevant committers:
git log --format='%an' --since='1 year' -- <affected-files> | sort | uniq -c | sort -rn | head -10 to find who has been most active on the affected files.git blame on key modified files to identify who wrote the code.gh pr edit --add-reviewer.tests/camel-kamelets-itest/src/test/resources/<kamelet-name>/; Kamelets with passing behaviour tests are labelled camel.apache.org/kamelet.verified=true../mvnw clean install # regenerates nav.adoc and validates the catalog
nav.adoc and the per-Kamelet doc pages are generated — do not hand-edit them.camel-kamelets-sbom/camel-kamelets-catalog-sbom.json is generated too: it lists everything spec.dependencies declares, so it can be scanned without building anything. The Catalog Dependency Scan workflow queries https://osv.dev against it weekly, because Dependabot reads poms and cannot see versions embedded in Kamelet YAML. Every Kamelet is a component linked to its artifacts through the CycloneDX dependency graph, so a finding is attributed to the Kamelets it affects. The two kinds of entry are marked apart: an mvn: coordinate is pinned by the catalog and fixed here, while a camel: component is versioned by the runtime and scanned at the newest Camel release, since OSV answers nothing for a SNAPSHOT.mvn verify from the repository root must pass before pushing.Do NOT use Thread.sleep() in test code; it leads to flaky, slow, non-deterministic tests. Use the project's Citrus test constructs (or Awaitility, where Java test code applies) with an explicit timeout instead.
Before implementing a fix, thoroughly investigate the issue. Kamelets are a long-lived shared catalog — a template often looks “wrong” but exists for a reason (compatibility with a Camel component default, an explicit insecure convenience Kamelet, an intentional inbound-header mapping).
git log --oneline <file> and git blame <file>; read commit messages and linked issues.docs/modules/ROOT/pages/development.adoc and the catalog README.md for authoring rules.kamelet: component, {{property}} placeholder binding, or org.apache.camel.kamelets.utils.*, the fix belongs in apache/camel, not here.Present findings to the operator before implementing. Flag risks, ambiguities, or cases where the issue may be invalid.
AI agents have a training cutoff. Never make authoritative claims about external project state (Camel component options, dependency versions) based solely on training knowledge — verify against the Camel catalog, Maven Central, or release notes before relying on or questioning a version.
When writing or modifying .adoc documentation:
xref: for internal links, never external https://camel.apache.org/... URLs for pages that exist in this module.nav.adoc, per-Kamelet pages); change the Kamelet YAML and regenerate.xref: links and anchors resolve.The Kamelet Catalog has a documented security model that defines who is trusted, where the trust boundaries sit, what counts as a catalog vulnerability, and what is route-author or operator responsibility. The canonical document is docs/modules/ROOT/pages/security-model.adoc. It specialises the Apache Camel Security Model; where the catalog model is silent, the Camel model governs. Use it as the reference when triaging security reports, deciding whether a finding warrants a CVE, or reviewing a security-sensitive Kamelet PR.
For the vulnerability reporting convention, SECURITY.md at the repository root is the entry point GitHub and security tooling expect. It points to the security model for scope and to the Apache Camel ASF process for private disclosure. An agent that discovers or is handed a suspected vulnerability MUST NOT open a public issue, PR, or mailing-list post about it — follow the private process and stop.
url, query, template, expression, executable, file paths, credentials — from configuration. Binding a property to attacker-controlled data is route-author error, not a catalog vulnerability.kamelet: component, placeholder binding and org.apache.camel.kamelets.utils.* live in apache/camel; defects there are routed to that project.The fundamental trust boundary is between the Kamelet (template + bound configuration) and the data flowing through it — unchanged from Camel, except the author of the trusted template is now the catalog.
A report is in scope when a shipped Kamelet template, in its default configuration, lets untrusted data cross a boundary the template — not the operator's wiring — should have held:
CamelHttpUri, CamelFileName, Camel*DestinationName, CamelExec*, CamelBeanMethodName, …) without stripping/fixing the dispatch headers it does not deliberately consume.{{property}}) to a simple/template-language/JSONPath/query evaluator the Kamelet's purpose did not require.0.0.0.0, permissive header filter), reachable just by deploying the Kamelet.format: password + x-descriptors: [urn:camel:group:credentials], or a missing pattern: that turns operator contract into reachable unintended behaviour (hardening tier).{{template}}, {{query}}, {{expression}}, {{url}}, {{executable}}, credentials, paths) to untrusted data — including all template-language and SQL/NoSQL/GraphQL Kamelets.exec-sink, ssh-*, scp-sink) or network exposure of a source (webhook-source, http-source); *-secured-* means auth options exist, not that auth is on by default.*-not-secured-*, kafka-not-secured-*).apache/camel).data:image icon annotation (metadata for tooling, never executed).camel-kamelets-catalog “parsing YAML” — it reads only build-bundled classpath YAML, not untrusted documents.script/, crds/ generator, tests/, templates/, kamelets-maven-plugin).When reviewing or recommending a deployment, surface:
Camel* headers from untrusted producers before a sink Kamelet, even though many templates also do this for known dispatch headers.exec-sink / ssh-* / scp-sink downstream of untrusted input.*-secured-* auth options.When reviewing a PR that adds or changes a Kamelet template:
http-sink's removeHeader: CamelHttpUri).{{property}}) to an expression/template/query evaluator? That is the in-scope injection class — the evaluated input must be a bound property.*-not-secured-*, document it, and get PMC sign-off.format: password with x-descriptors: [urn:camel:group:credentials].pattern: (operator-typo containment — not a trust control).camel-kamelets/ ├── kamelets/ # ~250 *.kamelet.yaml route templates (the product) ├── library/ │ ├── camel-kamelets/ # resource bundle (jars the YAML) │ ├── camel-kamelets-bom/ # Maven BOM (pom only) │ ├── camel-kamelets-catalog/ # runtime metadata reader (Java) │ ├── camel-kamelets-crds/ # Fabric8-generated K8s CRD POJOs (Java) │ └── kamelets-maven-plugin/ # build-time validation plugin ├── crds/ # Go CRD client generator (build/CI) ├── script/ # version-bump helper + catalog dependency scan ├── templates/ # init .vm template + Pipe examples ├── tests/camel-kamelets-itest/ # Citrus integration tests └── docs/modules/ROOT/ # Antora AsciiDoc (security-model.adoc lives here)
mvn verify # full build (from root) mvn verify -Pcoverage # with coverage # nav.adoc regeneration and catalog validation both run as part of the build
*.kamelet.yaml per Kamelet; file name MUST match metadata.name.source, sink, or action (camel.apache.org/kamelet.type label, mandatory).camel.apache.org/provider MUST be "Apache Software Foundation".data:image (no external URLs).kamelet:sink; sink templates consume from kamelet:source.spec.dependencies (camel:<component>, mvn:group:artifact:version with Apache-compatible license, or github:apache/... source only).spec.definition; mark secrets format: password + x-descriptors: [urn:camel:group:credentials].