Jira Integration

This page is for the developer or self-hoster connecting a Jira project to Avocado Studio. The Jira integration turns the orchestrator into a Jira-driven agent. When a ticket lands in the right status (or mentions the agent), Avocado reviews the request, applies the changes to your site, posts a preview link, and waits for approval before publishing.

Experimental — a demo channel. The Jira agent runs its own tool loop rather than the chat planner, so it lags the editor’s capabilities. Expect it to be rebuilt on top of the site assistant.

The /jira/* routes exist on the standalone orchestrator only. A library-mode mount (createOrchestrator()) does not serve them. They are internal-only: they don’t appear in the public API reference, and they answer 403 when DEMO_MODE=1 is set.

How it works

The integration runs a three-stage state machine driven by Jira ticket statuses and comment events. Review — The agent reads the full ticket context (summary, description, attachments, complete comment thread) and posts one of two comments:

A plan: “Here’s what I’ll do — let me know when to proceed.”
Questions: “I need more info on X before I can start.”

No site changes are made during review. The review prompt explicitly lists what the execute pass is capable of (Unsplash search, photo-page URL resolution, AI image generation) so the agent doesn’t fabricate limitations or ask for things it already has. Execute — The ticket is immediately transitioned to JIRA_EXECUTE_STATUS (In Progress) so the board reflects live progress. The agent then runs with full tool access, including the complete comment history so any clarifications posted as replies reach the agent. It reads the current site state, applies ops, posts a comment listing every change with clickable preview links, then parks the ticket at JIRA_PREVIEW_STATUS. Preview — The reporter reviews the draft in the editor. An approval comment triggers publish and moves the ticket to Done. Any other comment re-runs execute with the new instruction.

Approval keywords

The dispatcher uses keyword matching (not LLM inference) to detect approval. A comment approves only when approval is all it says: at least one of these words, plus nothing but courtesy (please, thanks, it, the changes…):

proceed · go · go ahead · yes · ok · okay · approved · approve
lgtm · ship it · looks good · confirm · confirmed · continue · publish

Anything more is a change request. On In Review that means the agent applies it and shows you the result again; nothing goes live until you reply with a plain approval. A comment with no, not, don’t, wait, hold, stop or but in it never approves. Examples that approve: “lgtm”, “ok, ship it”, “thanks, looks good — publish it please” Examples that don’t: “Change the heading to X and publish” (edit first, then you approve), “ok but the image is too dark”, “no, don’t publish yet”, “going through the feedback” (go only matches as a whole token)

Self-loop prevention

The agent detects its own comments using both the author account ID and the comment body. A comment is only treated as agent-authored when the Jira accountId matches JIRA_AGENT_ACCOUNT_ID AND the comment body starts with a known agent headline (e.g. “Draft updated. Ready for your review.” or “Review complete — ready to proceed.”). The dual check prevents false positives on solo / dev Jira tenants where the operator and agent share the same account — reporter replies from that account are still treated as reporter input, not self-loops.

Prerequisites

A Jira Cloud or Jira Server / Data Center instance
An API token (Cloud) or Personal Access Token (Server/DC)
ANTHROPIC_API_KEY or OPENAI_API_KEY in the orchestrator environment — the Jira processor uses the same AI backend as the chat pipeline; without at least one key it will refuse every ticket with an error
Orchestrator reachable from Jira’s webhook delivery (for webhook mode) or able to reach Jira (for polling mode)

Cloud vs Server/DC auth

	JIRA Cloud	JIRA Server / Data Center
`JIRA_USER_EMAIL`	Required — your Atlassian account email	Leave blank
`JIRA_API_TOKEN`	API token from id.atlassian.com	Personal Access Token
HTTP auth scheme	Basic (`email:token` → base64)	Bearer token

The client detects which to use based on whether JIRA_USER_EMAIL is set.

Configuration

Set these variables in your .env (or deployment environment). Only JIRA_BASE_URL and JIRA_API_TOKEN are required; everything else has a sensible default.

Required

Variable	Description
`JIRA_BASE_URL`	Your Jira instance URL, e.g. `https://mycompany.atlassian.net`
`JIRA_API_TOKEN`	API token (Cloud) or PAT (Server/DC)

Auth

Variable	Default	Description
`JIRA_USER_EMAIL`	—	Email for Cloud Basic auth. Leave unset for Server/DC Bearer auth.
`JIRA_WEBHOOK_SECRET`	—	Shared secret validated on every incoming webhook. Omit to accept all requests (not recommended in production).
`JIRA_AGENT_ACCOUNT_ID`	—	The agent’s Jira account ID. Used to detect `@mention`s and prevent self-loops. Get it from your Jira profile URL or `GET /rest/api/3/myself`.

Workflow statuses

These must exactly match your Jira workflow status names (case-insensitive comparison is used).

Variable	Default	Stage
`JIRA_REVIEW_STATUS`	`To Do`	Tickets waiting for agent review / reporter approval
`JIRA_EXECUTE_STATUS`	`In Progress`	Agent is applying edits
`JIRA_PREVIEW_STATUS`	`In Review`	Draft ready; reporter reviews and approves
`JIRA_DONE_STATUS`	`Done`	Terminal — ticket closed after publish
`JIRA_FAILED_STATUS`	—	Optional — status to transition to on unrecoverable error

JIRA_TRIGGER_STATUS is a legacy alias for JIRA_REVIEW_STATUS. Both are accepted.

Behaviour

Variable	Default	Description
`JIRA_SITE_ID`	`avocado-stories`	Fallback site, used only when no sites are registered. It is not a lock — see Which site a ticket edits.
`JIRA_SESSION`	`dev`	Session name the Jira runs edit, scoped per site in SQLite.
`JIRA_AUTO_PUBLISH`	`0`	Set to `1` to skip the preview stage: the agent publishes immediately after execute and closes the ticket.
`JIRA_MAX_REVIEW_PASSES`	`3`	Maximum clarification rounds per ticket. After this cap, the agent forces a proceed-or-stop decision.

Polling mode

Variable	Default	Description
`JIRA_POLL_ENABLED`	`0`	Set to `1` to enable polling (alternative to webhooks).
`JIRA_POLL_JQL`	`status in ("To Do", "In Review")`	JQL filter for the poller. Defaults to matching your configured review and preview statuses.
`JIRA_POLL_INTERVAL_MS`	`60000`	Polling interval in milliseconds.

Setting up webhooks

Webhooks are the primary event delivery mechanism. If your orchestrator is not publicly reachable (local dev, firewalled environments), use polling mode instead.

Make the orchestrator reachable

The orchestrator must be accessible from Jira’s servers. For local development, use a tunnelling tool (e.g. ngrok http 4200). For production, deploy to a public URL and set ORCHESTRATOR_PUBLIC_ORIGIN accordingly.

Create the webhook in Jira

Create a system webhook under Settings → System → WebHooks (Jira admin) pointing to:

POST https://<your-orchestrator>/jira/webhook?secret=<your-shared-secret>

Subscribe to these event types:

Issue created (jira:issue_created)
Issue updated (jira:issue_updated) — covers status changes
Comment created (comment_created)
Comment updated (comment_updated)

Configure the secret

The orchestrator compares the secret from the x-jira-webhook-secret header or the secret query parameter against JIRA_WEBHOOK_SECRET:

JIRA_WEBHOOK_SECRET=your-shared-secret

A system webhook can’t send a custom header, so put the secret in the URL as above. Its own Secret field produces an HMAC signature, which the orchestrator does not verify — leave it empty. If you send events from a Jira Automation rule (Send web request) instead, you can set the x-jira-webhook-secret header there.The comparison is timing-safe. Without a configured secret, all requests are accepted — fine for local dev, not for production.

Verify delivery

Move a test ticket to your JIRA_REVIEW_STATUS. You should see an HTTP 202 response in Jira’s webhook delivery log and a new comment from the agent on the ticket within seconds.If the webhook times out or returns 503, the integration isn’t configured — check that JIRA_BASE_URL and JIRA_API_TOKEN are set and the orchestrator has restarted.

Polling mode

Use polling when webhooks aren’t available (firewall, local dev without ngrok).

JIRA_POLL_ENABLED=1
JIRA_POLL_INTERVAL_MS=60000   # check every 60s
# Optional: narrow the query to your project
JIRA_POLL_JQL=project = SITE AND status in ("To Do", "In Review")

The poller queries Jira on the configured interval and applies the same routing logic as the webhook dispatcher. It deduplicates using a fingerprint of issueKey:status:commentCount so it only re-processes a ticket when its state actually changes. The dedup cache is cleared every 24 hours. If the Jira query fails, the poller backs off: the wait doubles with each consecutive failure, up to 15 minutes, and only the first failure is logged as an error. GET /jira/status shows poller.consecutiveFailures and poller.lastError throughout, and a recovery is logged once.

Polling and webhook modes can run simultaneously, but this risks duplicate processing. Enable one or the other.

Webhook routing logic

The table below summarises how the dispatcher maps incoming events to processing modes.

Event	Current status	Comment content	Action
Comment created/updated	`JIRA_REVIEW_STATUS`	Approval keyword	execute
Comment created/updated	`JIRA_REVIEW_STATUS`	Anything else	review (re-review with new info)
Comment created/updated	`JIRA_PREVIEW_STATUS`	Approval keyword	publish
Comment created/updated	`JIRA_PREVIEW_STATUS`	Anything else	execute (apply follow-up edits)
Comment (any other status)	Any	Jira @mention of the `JIRA_AGENT_ACCOUNT_ID` user	review
Status changed (by human)	→ `JIRA_REVIEW_STATUS`	—	review
Status changed (by human)	→ `JIRA_EXECUTE_STATUS`	—	execute
Status changed (by human)	→ anything else	—	skip
Issue created	`JIRA_REVIEW_STATUS` or assigned to agent	—	review
Any event	Any	Authored by agent account	skip (self-loop guard)

An @mention means a real Jira mention of the agent’s account (the person picker), not typed text — @site-editor written as plain text is ignored. Mentions only matter outside the managed statuses; in the review and preview statuses every reporter comment is already routed.

Which site a ticket edits

The agent resolves the target site from the registered sites, in this order:

Named in the ticket — a registered site’s id or name appears in the summary, description, or a reporter comment. Exactly one match wins.
Ambiguous — no single match and more than one site is registered. The agent posts a comment listing the candidates and asks; replying with the site’s id resolves it.
Only one site — exactly one site is registered, so that one is used.
No sites registered — JIRA_SITE_ID is used, defaulting to avocado-stories.

Attachment handling

Attachments on the ticket are downloaded and injected into the agent’s context:

Type	Handling
Images (png, jpg, jpeg, webp, svg, gif)	Saved to disk, URL passed to the agent as a reference image
Text documents (txt, md)	Content extracted and included inline
PDFs	Basic text extraction (regex-based); embedded in context
Other	Ignored

Maximum attachment size: 25 MB.

Unsplash image URLs

When a reporter pastes an Unsplash photo-page URL (https://unsplash.com/photos/<id>), the execute agent uses the built-in unsplash_get_by_id tool to resolve it to a direct images.unsplash.com asset URL instead of searching for a substitute. The same tool accepts a bare photo ID. If the URL can’t be resolved, the agent asks rather than silently falling back to a keyword search.

What reporters see

Every agent action posts a comment to the ticket. Here’s what each one looks like and what to reply.

Review comment (waiting for approval)

Review complete — ready to proceed.

Plan:
- Update the Hero heading to "Grow Your Business"
- Add a CTA block linking to /contact

Reply `go` (or `proceed`, `lgtm`, `approved`, etc.)
or move the ticket to In Progress and I'll apply the edits.

Or, if information is missing:

Review — I need a bit more info before I make changes.

What I think you want:
- Update the Hero section

Questions:
- Which page should this change apply to?

Reply with the answers and I'll re-review.

Execution complete (waiting for publish approval)

Draft updated. Ready for your review.

Changes made:
- Updated Hero heading to "Grow Your Business"
- Added CTA block linking to /contact

Preview:
- Open preview → /home  (clickable link)

Next step: Reply `approved` / `publish` / `lgtm` to publish,
or send a follow-up instruction for more changes.

AI Model: <model id> | Duration: 12.3s | Tool calls: 8

After publish

Published. Changes are live.

Live pages:
- Open live → /home  (clickable link)

Session isolation

Jira runs share one session per site — scopedSessionKey(JIRA_SESSION, siteId), i.e. {siteId}::{JIRA_SESSION} — deliberately, so Jira changes show up in the editor without per-ticket URLs. There is no per-ticket isolation: two tickets targeting the same site edit the same draft and their changes interleave. Every edit the agent makes is in page history like any other: it can be undone from the editor, and the version panel lists it under the agent as Jira SITE-42.

Endpoints

All three endpoints require the x-jira-webhook-secret header (or ?secret= query parameter) if JIRA_WEBHOOK_SECRET is configured.

`POST /jira/webhook`

Receives Jira webhook events. Returns 202 Accepted immediately; processing runs asynchronously. Response (queued):

{ "ok": true, "issueKey": "SITE-42", "mode": "review", "queued": true }

Response (skipped):

{ "ok": true, "skipped": true, "reason": "comment is from agent (self-loop guard)" }

`POST /jira/process`

Manually trigger processing for a ticket — useful for retries and testing. Request body:

{ "issueKey": "SITE-42", "mode": "review" }

mode is one of review, execute, or publish. Defaults to review. Unlike /jira/webhook, this call blocks until processing completes and returns the full result.

`GET /jira/status`

Returns the current state of the processing queue, recent results, and poller status.

{
  "configured": true,
  "reviewStatus": "To Do",
  "executeStatus": "In Progress",
  "previewStatus": "In Review",
  "doneStatus": "Done",
  "autoPublish": false,
  "agentAccountId": "5b10a...",
  "poller": { "running": true, "processedCount": 4, "isPolling": false },
  "queue": [],
  "recent": [...]
}

Telemetry

Every ticket run appends a line to ~/.data/telemetry/jira-telemetry.jsonl (NDJSON). Each entry contains:

Field	Description
`timestamp`	ISO timestamp of the run
`issueKey`	Jira issue key (e.g. `SITE-42`)
`mode`	`review`, `execute`, or `publish`
`siteId` / `session`	Target site and session name
`status`	`success` or `error`
`durationMs`	Wall-clock time for the run
`model` / `provider`	LLM used (execute mode only)
`instruction`	Full instruction text sent to the agent
`reviewDecision`	`{ decision, plan, questions }` (review mode only)
`toolCalls`	Per-tool trace: name, redacted input, duration, result excerpt, error flag
`toolCallCount`	Total tool calls made
`summary` / `changes`	Agent’s output summary and list of changes
`touchedSlugs`	Page slugs modified
`published`	Whether the draft was published in this run
`transitions`	Jira status transitions performed
`error`	Error message if `status = "error"`

The orchestrator also logs a structured JIRA: agent tool call line to stdout for each tool invocation during live runs.

Troubleshooting

503 from /jira/webhook JIRA_BASE_URL or JIRA_API_TOKEN is missing. Check your .env and restart the orchestrator. Ticket errors with “No AI API key configured” Neither ANTHROPIC_API_KEY nor OPENAI_API_KEY is set in the orchestrator environment. Add one and restart the orchestrator. The Anthropic key is preferred when both are present. 401 from /jira/webhook JIRA_WEBHOOK_SECRET is set but the request didn’t include the right value in x-jira-webhook-secret. Confirm Jira is sending the secret in the webhook header. Agent posts questions but never edits The reporter’s approval reply didn’t match any keyword, or said more than yes. Post one of the approval keywords above as a comment on its own. Agent keeps re-reviewing after approval JIRA_AGENT_ACCOUNT_ID is not set or is wrong. The dispatcher can’t detect which comments are from the agent, so it treats them as reporter comments and triggers re-review. Find your account ID via GET /rest/api/3/myself and set the env var. Ticket stays in Execute status The agent failed to apply edits or transition the ticket. Check GET /jira/status for the recent array — the error field shows the root cause. Poller processes the same ticket repeatedly The fingerprint (issueKey:status:commentCount) didn’t change between polls. This happens if the agent’s comment failed to post (so comment count didn’t increment). Check orchestrator logs for Jira API errors. Edits go to the wrong site Name the site’s id or name in the ticket summary or description. JIRA_SITE_ID won’t help once any site is registered — it is only the fallback when none are (see Which site a ticket edits). Typing @site-editor does nothing Only a real Jira @mention of the JIRA_AGENT_ACCOUNT_ID user counts. Pick the agent from the mention autocomplete. Agent ignores or replaces an Unsplash URL I pasted Paste the full photo-page URL (https://unsplash.com/photos/<id>) or just the bare photo ID. The agent resolves it via unsplash_get_by_id and uses it directly. If UNSPLASH_ACCESS_KEY is missing from the orchestrator environment, resolution will fail and the agent will ask for a direct image URL instead.

MCP server

The other inbound channel — 49 tools over Model Context Protocol.

Environment reference

Every JIRA_* variable, and everything else Avocado reads.

Drive it from outside

API

Orchestrator endpoints

How it works

Approval keywords

Self-loop prevention

Prerequisites

Cloud vs Server/DC auth

Configuration

Required

Auth

Workflow statuses

Behaviour

Polling mode

Setting up webhooks

Polling mode

Webhook routing logic

Which site a ticket edits

Attachment handling

Unsplash image URLs

What reporters see

Review comment (waiting for approval)

Execution complete (waiting for publish approval)

After publish

Session isolation

Endpoints

`POST /jira/webhook`

`POST /jira/process`

`GET /jira/status`

Telemetry

Troubleshooting

What to read next

MCP server

Environment reference

​How it works

​Approval keywords

​Self-loop prevention

​Prerequisites

​Cloud vs Server/DC auth

​Configuration

​Required

​Auth

​Workflow statuses

​Behaviour

​Polling mode

​Setting up webhooks

​Polling mode

​Webhook routing logic

​Which site a ticket edits

​Attachment handling

​Unsplash image URLs

​What reporters see

​Review comment (waiting for approval)

​Execution complete (waiting for publish approval)

​After publish

​Session isolation

​Endpoints

​POST /jira/webhook

​POST /jira/process

​GET /jira/status

​Telemetry

​Troubleshooting

​What to read next

MCP server

Environment reference

How it works

Approval keywords

Self-loop prevention

Prerequisites

Cloud vs Server/DC auth

Configuration

Required

Auth

Workflow statuses

Behaviour

Polling mode

Setting up webhooks

Polling mode

Webhook routing logic

Which site a ticket edits

Attachment handling

Unsplash image URLs

What reporters see

Review comment (waiting for approval)

Execution complete (waiting for publish approval)

After publish

Session isolation

Endpoints

`POST /jira/webhook`

`POST /jira/process`

`GET /jira/status`

Telemetry

Troubleshooting

What to read next