使用 `codex-cli` 自动化 Jira ↔ GitHub

本 cookbook 的目的

本 cookbook 提供了一种实用的、循序渐进的方法来自动化 Jira 和 GitHub 之间的工作流程。通过标记 Jira 问题，您可以触发一个端到端的流程，该流程会创建一个 GitHub 拉取请求，使两个系统保持更新，并简化代码审查，所有这些都只需最少的手动操作。自动化由在 GitHub Action 中运行的 codex-cli 代理提供支持。

流程如下：

标记 Jira 问题
Jira 自动化调用 GitHub Action
Action 启动 codex-cli 来实现更改
打开 PR
Jira 状态转换并注释 — 创建一个整洁、零点击的循环。这包括更改工单状态、添加 PR 链接以及在工单中添加评论以进行更新。

先决条件

Jira：项目管理员权限 + 创建自动化规则的能力
GitHub：写入访问权限、添加存储库密钥的权限以及受保护的 main 分支
API 密钥和密钥作为存储库密钥放置：
OPENAI_API_KEY – 您的 OpenAI 密钥，用于 codex-cli
JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN – 用于从 Action 进行 REST 调用
在本地安装 codex-cli（pnpm add -g @openai/codex），用于临时测试
包含 .github/workflows/ 文件夹的存储库

创建 Jira 自动化规则

自动化规则

此规则的第一步侦听问题标签的变化。这确保我们仅在添加或修改标签时触发自动化，而无需处理问题的每次更新。

接下来，我们检查更新的标签是否包含特定关键字，在我们的示例中，我们使用的是 aswe。这充当过滤器，因此只有明确标记为自动化的问题才会继续，从而避免了无关更新带来的不必要噪音。

如果满足条件，我们会向 GitHub 的 workflow_dispatch 端点发送 POST 请求。这会使用相关的 Jira 问题上下文启动 GitHub Actions 工作流。我们传入问题键、摘要以及清理后的描述版本 — 转义引号和换行符，以便有效负载在 YAML/JSON 中正确解析。JIRA 中有其他字段可用作变量，为 codex 代理在其执行期间提供更多上下文。

此设置允许团队严格控制哪些 Jira 问题会触发自动化，并确保 GitHub 收到结构化、干净的元数据来采取行动。我们还可以设置多个标签，每个标签触发不同的 GitHub Action。例如，一个标签可以启动一个快速的错误修复工作流，而另一个标签可以开始重构代码或生成 API 存根。

添加 GitHub Action

GitHub Actions 允许您通过在 YAML 文件中定义工作流来自动化 GitHub 存储库中的工作流。这些工作流指定了一系列要执行的作业和步骤。当通过手动触发或 POST 请求触发时，GitHub 会自动配置必要的环境并运行定义的工作流步骤。

为了处理来自 JIRA 的 POST 请求，我们将在存储库的 .github/workflows/ 目录中创建一个具有类似下面内容的 YAML 文件：

name: Codex Automated PR
on:
  workflow_dispatch:
    inputs:
      issue_key:
        description: 'JIRA issue key (e.g., PROJ-123)'
        required: true
      issue_summary:
        description: 'Brief summary of the issue'
        required: true
      issue_description:
        description: 'Detailed issue description'
        required: true

permissions:
  contents: write           # allow the action to push code & open the PR
  pull-requests: write      # allow the action to create and update PRs

jobs:
  codex_auto_pr:
    runs-on: ubuntu-latest

    steps:
    # 0 – Checkout repository

    - uses: actions/checkout@v4
      with:
        fetch-depth: 0       # full history → lets Codex run tests / git blame if needed

    # 1 – Set up Node.js and Codex

    - uses: actions/setup-node@v4
      with:
        node-version: 22

    - run: pnpm add -g @openai/codex

    # 2 – Export / clean inputs (available via $GITHUB_ENV)

    - id: vars
      run: |
        echo "ISSUE_KEY=${{ github.event.inputs.issue\_key }}"        >> $GITHUB_ENV
        echo "TITLE=${{ github.event.inputs.issue\_summary }}"        >> $GITHUB_ENV
        echo "RAW_DESC=${{ github.event.inputs.issue\_description }}" >> $GITHUB_ENV
        DESC_CLEANED=$(echo "${{ github.event.inputs.issue_description }}" | tr '\n' ' ' | sed 's/"/'\''/g')
        echo "DESC=$DESC\_CLEANED"                                    >> $GITHUB_ENV
        echo "BRANCH=codex/${{ github.event.inputs.issue\_key }}"     >> $GITHUB_ENV

    # 3 – Transition Jira issue to "In Progress"

    - name: Jira – Transition to In Progress
      env:
        ISSUE_KEY:      ${{ env.ISSUE_KEY }}
        JIRA_BASE_URL:  ${{ secrets.JIRA_BASE_URL }}
        JIRA_EMAIL:     ${{ secrets.JIRA_EMAIL }}
        JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
      run: |
        curl -sS -X POST \
          --url   "$JIRA\_BASE\_URL/rest/api/3/issue/$ISSUE_KEY/transitions" \
          --user  "$JIRA\_EMAIL:$JIRA_API_TOKEN" \
          --header 'Content-Type: application/json' \
          --data  '{"transition":{"id":"21"}}'
          # 21 is the transition ID for changing the ticket status to In Progress. Learn more here: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-transitions-get

    # 4 – Set Git author for CI commits

    - run: |
        git config user.email "github-actions[bot]@users.noreply.github.com"
        git config user.name  "github-actions[bot]"

    # 5 – Let Codex implement & commit (no push yet)

    - name: Codex implement & commit
      env:
        OPENAI_API_KEY:  ${{ secrets.OPENAI_API_KEY }}
        CODEX_QUIET_MODE: "1"          # suppress chatty logs
      run: |
        set -e
        codex --approval-mode full-auto --no-terminal --quiet \
              "Implement JIRA ticket $ISSUE\_KEY: $TITLE. $DESC"

        git add -A
        git commit -m "feat($ISSUE\_KEY): $TITLE"

    # 6 – Open (and push) the PR in one go

    - id: cpr
      uses: peter-evans/create-pull-request@v6
      with:
        token:  ${{ secrets.GITHUB_TOKEN }}
        base:   main
        branch: ${{ env.BRANCH }}
        title:  "${{ env.TITLE }} (${{ env.ISSUE_KEY }})"
        body: |
          Auto-generated by Codex for JIRA **${{ env.ISSUE_KEY }}**.
          ---
          ${{ env.DESC }}

    # 7 – Transition Jira to "In Review" & drop the PR link

    - name: Jira – Transition to In Review & Comment PR link
      env:
        ISSUE_KEY:      ${{ env.ISSUE_KEY }}
        JIRA_BASE_URL:  ${{ secrets.JIRA_BASE_URL }}
        JIRA_EMAIL:     ${{ secrets.JIRA_EMAIL }}
        JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
        PR_URL:         ${{ steps.cpr.outputs.pull-request-url }}
      run: |
        # Status transition
        curl -sS -X POST \
          --url   "$JIRA\_BASE\_URL/rest/api/3/issue/$ISSUE_KEY/transitions" \
          --user  "$JIRA\_EMAIL:$JIRA_API_TOKEN" \
          --header 'Content-Type: application/json' \
          --data  '{"transition":{"id":"31"}}'
          # 31 is the Transition ID for changing the ticket status to In Review. Learn more here: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-transitions-get

        # Comment with PR link
        curl -sS -X POST \
          --url   "$JIRA\_BASE\_URL/rest/api/3/issue/$ISSUE_KEY/comment" \
          --user  "$JIRA\_EMAIL:$JIRA_API_TOKEN" \
          --header 'Content-Type: application/json' \
          --data  "{\"body\":{\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"PR created: $PR_URL\"}]}]}}"

工作流中的关键步骤

Codex 实现与提交 (步骤 5) - 使用 OpenAI API 实现 JIRA 票证要求 - 在完全自动模式下运行 codex CLI，无需终端交互 - 使用标准化的提交消息提交所有更改
创建拉取请求 (步骤 6) - 使用 peter-evans/create-pull-request action - 创建针对 main 分支的 PR - 从 JIRA 票证信息设置 PR 标题和描述 - 返回 PR URL 以供后续使用
JIRA 更新 (步骤 7) - 通过 JIRA API 将票证状态转换为“正在审查” - 在 JIRA 票证上发布包含 PR URL 的评论 - 使用 curl 命令与 JIRA REST API 交互

标记问题

将特殊的 aswe 标签附加到任何错误/功能票证：

创建期间 – 在点击“创建”之前，在“标签”字段中添加它
现有问题 – 将鼠标悬停在标签区域上 → 单击铅笔图标 → 输入 aswe

添加标签

端到端流程

添加 Jira 标签 → 触发自动化
workflow_dispatch 触发；Action 在 GitHub 上启动
codex-cli 编辑代码库并提交
在生成的分支上打开 PR
Jira 移至“正在审查”，并在 Jira 票证上发布包含 PR URL 的评论
根据您的正常分支保护设置通知审阅者

带有 PR 链接的 Jira 评论 Jira 状态转换为正在审查

审查和合并 PR

您可以打开 Jira 票证中发布的 PR 链接，检查一切是否正常，然后进行合并。如果您启用了分支保护和智能提交集成，当拉取请求合并时，Jira 票证将自动关闭。

结论

此自动化通过在 Jira 和 GitHub 之间创建无缝集成来简化您的开发工作流程：

自动状态跟踪 - 票证在您的工作流程中进展，无需手动更新
改进的开发人员体验 - 专注于审查代码质量，而不是编写样板代码
减少交接摩擦 - 一旦票证被标记，PR 即可用于审查

codex-cli 工具是一个强大的 AI 编码助手，可以自动化重复性的编程任务。您可以在此处探索更多关于它的信息。

使用 codex-cli 自动化 Jira ↔ GitHub