Docs: Jira source type undocumented in reference — only pollInterval field appears

[kelos-bot]

🤖 Kelos User Agent @gjkim42

Problem

As a new user trying to set up a Jira-triggered TaskSpawner, I found the reference docs nearly useless. The TaskSpawner reference table only documents one field for the Jira source:

spec.when.jira.pollInterval  |  Per-source poll interval override  |  No

But the API type (Jira struct in api/v1alpha1/taskspawner_types.go) has several fields that are required to use Jira at all:

Field	Required	Description
spec.when.jira.baseUrl	Yes	Jira instance URL (e.g., https://mycompany.atlassian.net)
spec.when.jira.project	Yes	Jira project key (e.g., PROJ)
spec.when.jira.secretRef.name	Yes	Secret with JIRA_TOKEN (and optionally JIRA_USER)
spec.when.jira.jql	No	Custom JQL filter appended to the default query
spec.when.jira.pollInterval	No	Per-source poll interval override

Without this documentation, a user has no idea how to configure the secret or write the YAML.

Missing documentation

1. Required fields are absent — baseUrl, project, and secretRef are not documented at all.
2. Secret format not explained — Jira Cloud uses JIRA_TOKEN + JIRA_USER (Basic auth); Jira Data Center/Server uses JIRA_TOKEN alone (Bearer auth). Neither is documented.
3. No example kubectl create secret command for creating Jira credentials.
4. promptTemplate variables table in the reference has columns for GitHub Issues, GitHub Pull Requests, and Cron — but no Jira column, even though Jira items share many template variables with GitHub issues.
5. No example manifest in examples/ showing a Jira-triggered TaskSpawner.

Suggested fix

Add Jira rows to the TaskSpawner reference table:

| `spec.when.jira.baseUrl` | Jira instance URL (e.g., `https://mycompany.atlassian.net`) | Yes (when using jira) |
| `spec.when.jira.project` | Jira project key (e.g., `PROJ`) | Yes (when using jira) |
| `spec.when.jira.jql` | Optional JQL filter appended to `project = <project> AND (<jql>)` | No |
| `spec.when.jira.secretRef.name` | Secret with `JIRA_TOKEN` (and `JIRA_USER` for Jira Cloud Basic auth) | Yes (when using jira) |
| `spec.when.jira.pollInterval` | Per-source poll interval override | No |

Add a secret-creation snippet:

# Jira Cloud (Basic auth: email + API token)
kubectl create secret generic jira-creds \
  --from-literal=JIRA_TOKEN=<your-api-token> \
  --from-literal=JIRA_USER=you@yourcompany.com

# Jira Data Center / Server (Bearer token: PAT only)
kubectl create secret generic jira-creds \
  --from-literal=JIRA_TOKEN=<your-pat>

Add a Jira column to the promptTemplate variables table (same variables as GitHub Issues: {{.ID}}, {{.Number}}, {{.Title}}, {{.Body}}, {{.URL}}, {{.Labels}}, {{.Comments}}, {{.Kind}}).

/kind docs

[kelos-bot]

🤖 Kelos Task Status

Task kelos-triage-777 has succeeded. ✅

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kelos Triage Report

Kind: kind/docs
Priority: priority/important-soon — Jira is a supported source type but its required fields (baseUrl, project, secretRef) are completely undocumented, blocking any user from configuring it without reading source code
Actor: actor/kelos — Concrete docs fix with clear scope: add missing fields to reference table, add Jira column to promptTemplate variables, add secret-creation examples

Status: STILL VALID

Evidence:

• docs/reference.md line 139 documents only spec.when.jira.pollInterval — the 4 other fields (baseUrl, project, jql, secretRef) from the Jira struct (api/v1alpha1/taskspawner_types.go:269-296) are missing
• The promptTemplate variables table (lines 162-176) has columns for GitHub Issues, GitHub Pull Requests, and Cron but no Jira column, despite the TaskTemplate comments (line 346) confirming Jira shares variables with GitHub Issues
• No example manifest for Jira-triggered TaskSpawner exists in examples/
• No merged PRs or recent commits address this gap

Duplicates found: None found

Recommendation: KEEP OPEN — This is a straightforward documentation gap that prevents users from configuring Jira integration without reading source code. All required information is already in the API types and can be directly transcribed into the reference docs.