Run Claude Code or Codex from Jira
Goal
A developer presses Send to agent on a work item. Cuelight starts your agent workflow with the work item's key, summary and description. The agent changes the code in your GitHub Actions, the workflow opens a pull request, and the work item offers Deploy preview and Run agent again. From there, Approve after an agent's pull request takes it to production.
The agent runs on your GitHub Actions runner with your own API key. Cuelight doesn't call any AI. It sends the inputs you define to GitHub, and your workflow decides what the agent sees.
What you need
- Cuelight installed and GitHub connected
- A repository secret with your agent's key:
ANTHROPIC_API_KEYfor Claude Code orOPENAI_API_KEYfor Codex - Allow GitHub Actions to create and approve pull requests turned on in the repository's Settings → Actions → General, so the workflow can open the pull request
- The
deploy-previewandpromote-productionactions from Approve after an agent's pull request, and thedeploy.ymlworkflow from Deploy, promote and roll back
Actions
[
{
"id": "send-to-agent",
"label": "Send to agent",
"style": "primary",
"type": "github_workflow",
"github": {
"workflow": "agent.yml",
"inputs": {
"issue_key": "{{issue.key}}",
"summary": "{{issue.summary}}",
"description": "{{issue.fields.description}}"
}
},
"allow": { "groups": ["developers"] }
},
{
"id": "run-agent-again",
"label": "Run agent again",
"type": "github_workflow",
"availability": "next-only",
"github": {
"workflow": "agent.yml",
"inputs": {
"issue_key": "{{issue.key}}",
"summary": "{{issue.summary}}",
"description": "{{issue.fields.description}}",
"feedback": "{{input.feedback}}"
}
},
"form": [
{
"name": "feedback",
"label": "What should change?",
"type": "textarea",
"required": true,
"maxLength": 1000
}
],
"allow": { "groups": ["developers", "qa-team"] }
}
]Workflow with Claude Code
agent.yml has two jobs. The first runs the agent with read-only access. The second starts on a
fresh runner, pushes the change, opens or updates the pull request and reports to the work item, so
the write token never reaches the runner the agent worked on.
name: Agent
on:
workflow_dispatch:
inputs:
issue_key: { type: string, required: true }
summary: { type: string, required: true }
description: { type: string, required: false }
feedback: { type: string, required: false }
cuelight_callback_url: { type: string, required: false }
cuelight_token: { type: string, required: false }
concurrency:
group: agent-${{ inputs.issue_key }}
jobs:
agent:
runs-on: ubuntu-latest
timeout-minutes: 30
permissions:
contents: read
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
persist-credentials: false
- name: Switch to the work item's branch
env:
ISSUE_KEY: ${{ inputs.issue_key }}
run: |
[[ "$ISSUE_KEY" =~ ^[A-Z][A-Z0-9]+-[0-9]+$ ]] || exit 1
git switch "agent/$ISSUE_KEY" 2>/dev/null || git switch -c "agent/$ISSUE_KEY"
- name: Run Claude Code
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
github_token: ${{ github.token }}
# Add the commands it may run, like Bash(npm test:*).
claude_args: --max-turns 30 --allowedTools Edit,Read,Write,Glob,Grep
prompt: |
Fix Jira work item ${{ inputs.issue_key }}: ${{ inputs.summary }}
Description, as plain text and cut at 1000 characters:
${{ inputs.description }}
Feedback on the last attempt, if any:
${{ inputs.feedback }}
Edit the files in this repository. Don't commit or push.
- name: Save the changes
run: |
git add -A
if git diff --cached --quiet; then
echo 'The agent made no changes.' >&2
exit 1
fi
git diff --cached --binary >"$RUNNER_TEMP/agent.patch"
- uses: actions/upload-artifact@v7
with:
name: agent-patch
path: ${{ runner.temp }}/agent.patch
publish:
needs: agent
if: always()
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- uses: actions/download-artifact@v8
if: needs.agent.result == 'success'
with:
name: agent-patch
path: ${{ runner.temp }}
- name: Open or update the pull request
id: pr
if: needs.agent.result == 'success'
env:
GH_TOKEN: ${{ github.token }}
ISSUE_KEY: ${{ inputs.issue_key }}
SUMMARY: ${{ inputs.summary }}
run: |
branch="agent/$ISSUE_KEY"
git switch "$branch" 2>/dev/null || git switch -c "$branch"
git apply --index "$RUNNER_TEMP/agent.patch"
git config user.name 'github-actions[bot]'
git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
git commit -m "$ISSUE_KEY: $SUMMARY"
git push origin "$branch"
url="$(gh pr list --head "$branch" --state open --json url --jq '.[0].url // empty')"
if [ -z "$url" ]; then
url="$(gh pr create --head "$branch" --title "$ISSUE_KEY: $SUMMARY" \
--body "Opened by an AI agent from $ISSUE_KEY. Review it like any other pull request.")"
fi
echo "number=${url##*/}" >>"$GITHUB_OUTPUT"
- name: Pick the next steps
id: next
if: always()
env:
PR: ${{ steps.pr.outputs.number }}
run: |
if [ -n "$PR" ]; then
echo "message=PR #$PR opened, preview ready to deploy" >>"$GITHUB_OUTPUT"
next="$(jq -nc --arg pr "$PR" '[{action: "deploy-preview", inputs: {pr: $pr}}, {action: "run-agent-again"}]')"
echo "next=$next" >>"$GITHUB_OUTPUT"
else
echo "message=The agent didn't open a pull request" >>"$GITHUB_OUTPUT"
echo "next=run-agent-again" >>"$GITHUB_OUTPUT"
fi
- name: Hand back the next steps
if: always()
uses: huseyinbuyukdere/cuelight-report@v1
with:
status: ${{ steps.pr.outputs.number && 'success' || 'failure' }}
message: ${{ steps.next.outputs.message }}
next: ${{ steps.next.outputs.next }}With github_token set, Claude Code uses the workflow's own token, so you don't need to install the
Claude GitHub app. --allowedTools decides what it may do. Leave out Bash unless you list the
exact commands.
Workflow with OpenAI Codex
Use the same agent.yml and swap the Run Claude Code step for this one:
- name: Run Codex
uses: openai/codex-action@v1
with:
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
permission-profile: ':workspace'
prompt: |
Fix Jira work item ${{ inputs.issue_key }}: ${{ inputs.summary }}
Description, as plain text and cut at 1000 characters:
${{ inputs.description }}
Feedback on the last attempt, if any:
${{ inputs.feedback }}
Edit the files in this repository. Don't commit or push.The :workspace profile lets Codex edit the checkout but gives it no network access, so install
dependencies in a step before it. Codex's own security guide recommends running it at the end of
a job and doing the rest in a new one, which is why the push happens in publish.
What people see
- A developer presses Send to agent on SHOP-142. The work item gets a start comment with the inputs, and the panel shows the run.
- When the pull request is open, the panel says "PR #318 opened, preview ready to deploy" and offers Deploy preview and Run agent again, "Suggested by agent.yml".
- QA presses Deploy preview. The form already says
318. When the preview is live, release managers get Promote to production, as in Approve after an agent's pull request. - If the change isn't right, someone presses Run agent again and writes what should change. The agent works on the same branch, and the pull request updates.
Things to know
- The description arrives as plain text, cut at 1000 characters. Lists come as
-and1.lines, and links as their addresses. Long descriptions lose their end. Put extra instructions in the Run agent again form, or let the workflow read the work item from Jira itself. - The pull request's own workflows wait. GitHub doesn't start
pull_requestworkflows, like your CI, on its own when the workflow's token opened the pull request. Someone with write access approves them in GitHub, or thepublishjob uses a GitHub App token instead. - The agent reads what people write. Anyone who can edit the work item can steer the agent
through its text. Keep
allow.groupsand the agent's tools narrow, and review the pull request like any other. - The run starts as the token's owner. GitHub shows the owner of the token saved in Cuelight as the actor. Claude Code stops if that's a bot account rather than a user, and Codex runs only for actors with write access to the repository.
Variations
- Write the description first. Write the Jira description with AI turns a one-line report into steps and acceptance criteria, then offers Send to agent.
- Test the preview with AI. Test the preview with AI runs AI-written tests on the preview and offers Run agent again with the failures written in.
- Only for some work items. Add
"showWhen": { "issueTypes": ["Bug"] }to Send to agent, or a label like"labelsAny": ["agent-ok"]. - Ask for instructions up front. Give Send to agent a
notestextarea, pass{{input.notes}}as anotesinput and add it to the prompt. - An Approve button. A next-only
jira_updateaction that adds anapprovedlabel. Offer it next to Deploy preview, and let your Automation rules or merge checks look for the label. - Another agent. Anything that runs in GitHub Actions works the same way. Swap the agent step and keep the rest.