Write the Jira description with AI

Goal

Someone files "saved card not picked when i go to checkout" and nothing else. A developer or tester presses Write description with AI. Your workflow reads the work item from Jira, Claude Code reads your repository, and the description becomes a problem statement, steps to reproduce, the expected result, where to look in the code and acceptance criteria. Then the work item offers Send to agent, so an agent can fix it.

The AI runs on your GitHub Actions runner with your own API key. Cuelight doesn't call any AI. It starts the workflow, checks who pressed the button and shows the result.

What you need

  • Cuelight installed and GitHub connected
  • A repository secret ANTHROPIC_API_KEY
  • A Jira account for the workflow, ideally a bot account that can edit work items in the project. Store its email and an API token as repository secrets JIRA_EMAIL and JIRA_API_TOKEN, and your site address as a repository variable JIRA_URL, like https://your-team.atlassian.net
  • The send-to-agent action from Run Claude Code or Codex from Jira, or take send-to-agent out of next below. Cuelight refuses a report that offers an action you haven't defined.

Actions

[
  {
    "id": "write-description",
    "label": "Write description with AI",
    "type": "github_workflow",
    "github": {
      "workflow": "ai-description.yml",
      "inputs": { "issue_key": "{{issue.key}}", "notes": "{{input.notes}}" }
    },
    "form": [{ "name": "notes", "label": "Anything the AI should know?", "type": "textarea" }],
    "allow": { "groups": ["developers", "qa-team"] }
  }
]

The button sends only the work item key and the notes. The workflow reads the description from Jira itself, because {{issue.fields.description}} arrives as plain text cut at 1000 characters. Rewriting from that would drop the end of a long description and its screenshots.

Workflow

ai-description.yml has three jobs. read and update use the Jira token. draft runs the AI on its own runner without it, and can only read the repository and write one folder.

name: AI description
on:
  workflow_dispatch:
    inputs:
      issue_key: { type: string, required: true }
      notes: { type: string, required: false }
      cuelight_callback_url: { type: string, required: false }
      cuelight_token: { type: string, required: false }

concurrency:
  group: ai-description-${{ inputs.issue_key }}

jobs:
  read:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - name: Read the work item from Jira
        env:
          JIRA_URL: ${{ vars.JIRA_URL }}
          JIRA_AUTH: ${{ secrets.JIRA_EMAIL }}:${{ secrets.JIRA_API_TOKEN }}
          ISSUE_KEY: ${{ inputs.issue_key }}
        run: |
          [[ "$ISSUE_KEY" =~ ^[A-Z][A-Z0-9]+-[0-9]+$ ]] || exit 1
          mkdir ai-draft
          # API v2 returns the description as Jira wiki markup, with images and links.
          curl -fsS -u "$JIRA_AUTH" "$JIRA_URL/rest/api/2/issue/$ISSUE_KEY?fields=summary,description" |
            jq -r '"Summary: \(.fields.summary)\n\n\(.fields.description // "(empty)")"' \
              >ai-draft/current.txt
      - uses: actions/upload-artifact@v7
        with:
          name: work-item
          path: ai-draft/current.txt

  draft:
    needs: read
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/download-artifact@v8
        with:
          name: work-item
          path: ai-draft
      - name: Rewrite with Claude Code
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ github.token }}
          claude_args: --max-turns 20 --allowedTools "Read,Glob,Grep,Edit(ai-draft/**)"
          prompt: |
            ai-draft/current.txt has Jira work item ${{ inputs.issue_key }}: its summary and its
            description in Jira wiki markup.

            Notes from the person who pressed the button, if any:
            ${{ inputs.notes }}

            Read the repository to understand the problem. Then write a new description to
            ai-draft/description.txt in Jira wiki markup (h3. headings, # numbered lists,
            * bullets) with these sections: Problem, Steps to reproduce, Expected, Where to look,
            Acceptance criteria. Keep every fact, link and image (lines like !screenshot.png!)
            from the current description. Write "Unknown" where you don't know. Don't invent facts.
      - uses: actions/upload-artifact@v7
        with:
          name: ai-description
          path: ai-draft/description.txt

  update:
    needs: draft
    if: always()
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - uses: actions/download-artifact@v8
        if: needs.draft.result == 'success'
        with:
          name: ai-description
      - name: Update the description in Jira
        id: update
        if: needs.draft.result == 'success'
        env:
          JIRA_URL: ${{ vars.JIRA_URL }}
          JIRA_AUTH: ${{ secrets.JIRA_EMAIL }}:${{ secrets.JIRA_API_TOKEN }}
          ISSUE_KEY: ${{ inputs.issue_key }}
        run: |
          [ -s description.txt ] || { echo 'The AI wrote no description.' >&2; exit 1; }
          jq -n --rawfile d description.txt '{fields: {description: $d}}' |
            curl -fsS -X PUT -u "$JIRA_AUTH" -H 'Content-Type: application/json' \
              --data @- "$JIRA_URL/rest/api/2/issue/$ISSUE_KEY"
      - name: Hand back the result
        if: always()
        uses: huseyinbuyukdere/cuelight-report@v1
        with:
          status: ${{ steps.update.outcome == 'success' && 'success' || 'failure' }}
          message: ${{ steps.update.outcome == 'success' && 'Description rewritten. The old text is in History.' || 'The description was not changed' }}
          next: ${{ steps.update.outcome == 'success' && 'send-to-agent,write-description' || 'write-description' }}

What people see

  1. SHOP-142 says only "saved card not picked when i go to checkout". Ayşe from QA presses Write description with AI and writes "Only with Visa cards" in the form. The work item gets a start comment with her notes.
  2. About a minute later the description has Problem, Steps to reproduce, Expected, Where to look and Acceptance criteria. The panel says "Description rewritten. The old text is in History."
  3. The panel offers Send to agent and Write description with AI, "Suggested by ai-description.yml". A developer reads the new description and sends the work item to the agent.

Things to know

  • Nothing is lost. Jira keeps the old description in the work item's History. Images and links stay, because the workflow reads and writes Jira wiki markup through REST API v2 and Jira turns it back into rich text.
  • Jira shows the bot as the editor. History names the account behind JIRA_API_TOKEN. The Cuelight comment says who pressed the button and what they wrote.
  • The AI reads what people write. The description and the notes are part of its prompt, and its text goes straight into Jira. Keep allow.groups narrow, and give these workflows an Anthropic key of their own with a spending limit.

Variations

  • Only for thin work items. Add "showWhen": { "issueTypes": ["Bug"], "statuses": ["To Do"] }.
  • Review before it changes. Post the draft as a comment instead: send {body: $d} with POST to $JIRA_URL/rest/api/2/issue/$ISSUE_KEY/comment, and change the message.
  • Another field. Write acceptance criteria to a multi-line text field by sending its id, like customfield_10050, in place of description.
  • Another agent. Swap the Claude Code step for Codex or any agent that runs in GitHub Actions, as in Run Claude Code or Codex from Jira. Keep the three jobs.