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_EMAILandJIRA_API_TOKEN, and your site address as a repository variableJIRA_URL, likehttps://your-team.atlassian.net - The
send-to-agentaction from Run Claude Code or Codex from Jira, or takesend-to-agentout ofnextbelow. 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
- 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.
- 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."
- 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.groupsnarrow, 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 ofdescription. - 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.