Jira Agent

The jira agent connects to Jira Cloud (or Server) via REST API v3. It uses Basic auth (email + API token) to fetch issues, run JQL searches, add comments, and trigger status transitions. Source data is written to the workspace as JSON files. Target operations read from workspace files and post to Jira.

The agent also supports a notify handler, allowing event-driven Jira updates (e.g., transitioning a ticket when a pipeline escalates) without requiring a dedicated phase.

Sample Phase

- name: fetch-ticket
  agent: jira
  action: get_issue
  sources:
      - name: ticket.json
        ref: PROJ-123

Phase Configuration

Actions

Action	Direction	Description
`get_issue`	Source	Fetch a single issue by key
`get_comments`	Source	Fetch all comments on an issue
`search`	Source	Run a JQL query and return matching issues
`add_comment`	Target	Post a comment to an issue
`transition`	Target	Trigger a workflow status transition

Phase YAML Fields

Field	Type	Required	Description
`name`	`string`	Yes	Unique phase name within the workflow
`type`	`string`	No	Defaults to `"standard"`
`agent`	`string`	Yes	Must be `"jira"`
`depends_on`	`string[]`	No	Upstream phases that must complete before this phase runs
`action`	`string`	Yes	One of: `get_issue`, `get_comments`, `search`, `add_comment`, `transition`
`sources`	`SourceEntry[]`	For fetch actions	Entries to fetch from Jira
`target_entries`	`TargetEntry[]`	For write actions	Entries to deliver to Jira
`notify`	`object`	No	Event-driven handler configuration

Source Entry Fields

Field	Type	Required	Description
`name`	`string`	Yes	Output filename (written to `.cliq/files/{phase}/{name}`)
`ref`	`string`	Yes	Issue key (e.g., `PROJ-123`) or JQL query string

Target Entry Fields

Field	Type	Required	Description
`name`	`string`	Yes	Identifier for the operation
`ref`	`string`	Yes	Issue key to target (e.g., `PROJ-123`)
`file`	`string`	Yes	Workspace file containing comment text or transition ID

Notify Handler

The Jira agent can respond to pipeline events via the notify block. When an event fires, the agent transitions the referenced ticket to a new status.

Field	Type	Description
`ticket`	`string`	Issue key to transition (supports template variables)
`transition_to`	`string`	Target status name (e.g., `Blocked`, `Done`)

Supported events: on_complete, on_escalate, on_fail.

notify:
    on_escalate:
        agent: jira
        ticket: $(inputs.ticket)
        transition_to: Blocked

Settings

Jira credentials are configured under agents.jira in settings.json:

Key	Required	Default	Description
`agents.jira.base_url`	Yes	—	Jira instance URL (e.g., `https://your-org.atlassian.net`)
`agents.jira.email`	Yes	—	Atlassian account email for API auth
`agents.jira.api_token`	Yes	—	Jira API token

Output

Handoff Structure

Source operations return issue metadata; target operations confirm what was posted.

get_issue

{
    "data": {
        "action": "get_issue",
        "sources": {
            "ticket": {
                "ref": "PROJ-123",
                "key": "PROJ-123",
                "summary": "Fix login timeout on mobile",
                "fields": {
                    "status": "In Progress",
                    "assignee": "[email protected]",
                    "priority": "High"
                }
            }
        },
        "targets": {}
    },
    "text": "## Jira Results\n\n✓ Fetched ticket — PROJ-123: Fix login timeout on mobile"
}

search

{
    "data": {
        "action": "search",
        "sources": {
            "bugs": {
                "ref": "project = PROJ AND type = Bug AND status = Open",
                "key": "search",
                "count": 7
            }
        },
        "targets": {}
    },
    "text": "## Jira Results\n\n✓ Searched bugs (7 issues)"
}

add_comment

{
    "data": {
        "action": "add_comment",
        "sources": {},
        "targets": {
            "comment": {
                "ref": "PROJ-123",
                "key": "PROJ-123",
                "comment_id": "10042"
            }
        }
    },
    "text": "## Jira Results\n\n✓ Commented on PROJ-123"
}

transition

{
    "data": {
        "action": "transition",
        "sources": {},
        "targets": {
            "move-to-done": {
                "ref": "PROJ-123",
                "key": "PROJ-123",
                "transition_id": "31"
            }
        }
    },
    "text": "## Jira Results\n\n✓ Transitioned PROJ-123"
}

Field Reference

Field	Location	Description
`ref`	`data.sources.`, `data.targets.`	Issue key or JQL query string
`key`	`data.sources.`, `data.targets.`	Jira issue key
`summary`	`data.sources.*`	Issue summary text (get_issue only)
`fields`	`data.sources.*`	Selected issue fields — status, assignee, priority, etc. (get_issue only)
`count`	`data.sources.*`	Number of results (search, get_comments)
`comment_id`	`data.targets.*`	ID of the created comment (add_comment only)
`transition_id`	`data.targets.*`	ID of the executed transition (transition only)

Files Written

Source operations write JSON to .cliq/files/{phase}/{source.name}:

get_issue — Full issue JSON including fields, changelog, and links
get_comments — Array of comment objects with author and body
search — Array of issue objects matching the JQL query

Downstream Access

Reference handoff data in downstream phases using template variables:

- name: analyze
  agent: cursor
  prompt: |
      Fix the bug described in $(handoff.fetch-ticket.sources.ticket.key):
      $(handoff.fetch-ticket.sources.ticket.summary)

Examples

Example: Fetch a ticket and implement a fix

A developer pipeline that pulls issue details, implements a fix, then comments back.

phases:
    - name: fetch-ticket
      agent: jira
      action: get_issue
      sources:
          - name: ticket
            ref: $(inputs.ticket)

    - name: implement
      agent: cursor
      depends_on: [fetch-ticket]
      prompt: |
          Implement a fix for $(handoff.fetch-ticket.sources.ticket.key):
          $(handoff.fetch-ticket.sources.ticket.summary)

    - name: comment-result
      agent: jira
      action: add_comment
      depends_on: [implement]
      target_entries:
          - name: comment
            file: .cliq/files/implement/summary.md
            ref: $(inputs.ticket)

Example: Search for open bugs and triage

Pull open bugs via JQL and pass them to an LLM for prioritization.

phases:
    - name: search-bugs
      agent: jira
      action: search
      sources:
          - name: bugs
            ref: "project = MOBILE AND type = Bug AND status = Open ORDER BY created DESC"

    - name: triage
      agent: cursor
      depends_on: [search-bugs]
      prompt: |
          Review the $(handoff.search-bugs.sources.bugs.count) open bugs
          and produce a priority-ranked list with recommended assignees.

Example: Transition a ticket on pipeline completion

Use the notify handler to move a ticket to “Done” when the pipeline succeeds, or “Blocked” if it escalates.

phases:
    - name: deploy
      agent: cursor
      role: deployer
      notify:
          on_complete:
              agent: jira
              ticket: $(inputs.ticket)
              transition_to: Done
          on_escalate:
              agent: jira
              ticket: $(inputs.ticket)
              transition_to: Blocked

Example: Fetch comments for context

Pull existing comments on a ticket to give an LLM conversational context.

phases:
    - name: fetch-comments
      agent: jira
      action: get_comments
      sources:
          - name: discussion
            ref: PROJ-456

    - name: summarize
      agent: cursor
      depends_on: [fetch-comments]
      prompt: |
          Summarize the discussion thread on PROJ-456 and identify
          any unresolved questions.

Setup

Find your Jira instance URL: https://your-org.atlassian.net (Cloud) or https://jira.your-company.com (Server/Data Center)
Go to https://id.atlassian.com/manage-profile/security/api-tokens
Click Create API token, name it (e.g., cliq), and copy it
Confirm your account email at https://id.atlassian.com/manage-profile/email

Jira API tokens inherit the full permissions of your Atlassian account — no scope configuration needed.

cliq settings agents.jira.base_url "https://your-org.atlassian.net" --global
cliq settings agents.jira.email "[email protected]" --global
echo $JIRA_TOKEN | cliq settings agents.jira.api_token --stdin --global
cliq doctor agent jira