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_KEY for Claude Code or OPENAI_API_KEY for 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-preview and promote-production actions from Approve after an agent's pull request, and the deploy.yml workflow 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

  1. 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.
  2. 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".
  3. 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.
  4. 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 - and 1. 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_request workflows, like your CI, on its own when the workflow's token opened the pull request. Someone with write access approves them in GitHub, or the publish job 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.groups and 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 notes textarea, pass {{input.notes}} as a notes input and add it to the prompt.
  • An Approve button. A next-only jira_update action that adds an approved label. 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.