new changes

Author: narenoai

examples/codex/jira-github.ipynb

@@ -10,12 +10,9 @@
       "source": [
         "# Automate Jira ↔ GitHub with `codex-cli`\n",
         "\n",
-        "## What you'll build\n",
+        "## Purpose of this cookbook\n",
         "\n",
-        "By the end of this walkthrough, you'll have an end-to-end automation that turns a **labelled Jira issue** into a\n",
-        "fully-fledged **GitHub pull request**, keeps the Jira ticket updated throughout the review process, and finally merges\n",
-        "the code once checks pass – all driven by the\n",
-        "[`codex-cli`](https://github.com/openai/openai-codex) agent working inside a GitHub Action.\n",
+        "This cookbook provides a practical, step-by-step approach to automating the workflow between Jira and GitHub. By labeling a Jira issue, you trigger an end-to-end process that creates a **GitHub pull request**, keeps both systems updated, and streamlines code review, all with minimal manual effort. The automation is powered by the [`codex-cli`](https://github.com/openai/openai-codex) agent running inside a GitHub Action.\n",
         "\n",
         "# <img src=\"./images/codex_action.png\" alt=\"Full data-flow diagram\" width=\"500\"/>\n"
       ]
@@ -29,11 +26,12 @@
       },
       "source": [
         "The flow is:\n",
+        "\n",
         "1. Label a Jira issue \n",
         "2. Jira Automation calls the GitHub Action \n",
         "3. The action spins up `codex-cli` to implement the change \n",
         "4. A PR is opened\n",
-        "5. Jira is transitioned & annotated – creating a neat, zero-click loop\n",
+        "5. Jira is transitioned & annotated - creating a neat, zero-click loop. This includes changing the status of the ticket, adding the PR link and commenting in the ticket with updates.\n",
         "\n",
         "## Prerequisites\n",
         "\n",
@@ -43,7 +41,7 @@
         "  * `OPENAI_API_KEY` – your OpenAI key for `codex-cli`  \n",
         "  * `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` – for REST calls from the action  \n",
         "* `codex-cli` installed locally (`pnpm add -g @openai/codex`) for ad-hoc testing  \n",
-        "* A repository that already contains a `.github/workflows/` folder (any Node project is fine)\n"
+        "* A repository that contains a `.github/workflows/` folder\n"
       ]
     },
     {
@@ -58,9 +56,13 @@
         "\n",
         "<img src=\"./images/jira_rule.png\" alt=\"Automation Rule\" width=\"500\"/>\n",
         "\n",
-        "* **Trigger – Issue updated**: fires whenever labels change  \n",
-        "* **Condition – `labels` contains `autocodex`**: limits noise to explicitly opted-in issues  \n",
-        "* **Action – Send web request**: POSTs the issue key/summary/description to your GitHub Action's `workflow_dispatch` endpoint\n"
+        "The first step in this rule listens for changes to an issue’s labels. This ensures we only trigger the automation when a label is added or modified—no need to process every update to the issue.\n",
+        "\n",
+        "Next, we check whether the updated labels include a specific keyword, in our example we are using `aswe`. This acts as a filter so that only issues explicitly tagged for automation proceed, avoiding unnecessary noise from unrelated updates.\n",
+        "\n",
+        "If the condition is met, we send a `POST` request to GitHub’s `workflow_dispatch` endpoint. This kicks off a GitHub Actions workflow with the relevant issue context. We pass in the issue key, summary, and a cleaned-up version of the description—escaping quotes and newlines so the payload parses correctly in YAML/JSON. There are [additional fields](https://support.atlassian.com/cloud-automation/docs/jira-smart-values-issues/) available as variables in JIRA to give the codex agent more context during its execution.\n",
+        "\n",
+        "This setup allows teams to tightly control which Jira issues trigger automation, and ensures GitHub receives structured, clean metadata to act on. We can also set up multiple labels, each triggering a different GitHub Action. For example, one label could kick off a quick bug fix workflow, while another might start work on refactoring code or generating API stubs.\n"
       ]
     },
     {
@@ -73,7 +75,9 @@
       "source": [
         "## Add the GitHub Action\n",
         "\n",
-        "Create a workflow file in your `.github/workflows/` directory with the following YAML (Modify it as needed):\n"
+        "GitHub Actions enable you to automate workflows within your GitHub repository by defining them in YAML files. These workflows specify a series of jobs and steps to execute. When triggered either manually or via a POST request, GitHub automatically provisions the necessary environment and runs the defined workflow steps.\n",
+        "\n",
+        "To process the `POST` request from JIRA we will create a Github action with a YAML like below in the `.github/workflows/` directory of the repository:\n"
       ]
     },
     {
@@ -138,6 +142,7 @@
         "          --user  \"$JIRA_EMAIL:$JIRA_API_TOKEN\" \\\n",
         "          --header 'Content-Type: application/json' \\\n",
         "          --data  '{\"transition\":{\"id\":\"21\"}}'\n",
+        "          # 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\n",
         "\n",
         "    # 4 – Set Git author for CI commits\n",
         "    - run: |\n",
@@ -185,6 +190,7 @@
         "          --user  \"$JIRA_EMAIL:$JIRA_API_TOKEN\" \\\n",
         "          --header 'Content-Type: application/json' \\\n",
         "          --data  '{\"transition\":{\"id\":\"31\"}}'\n",
+        "          # 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\n",
         "\n",
         "        # Comment with PR link\n",
         "        curl -sS -X POST \\\n",
@@ -232,10 +238,10 @@
       "source": [
         "## Label an Issue\n",
         "\n",
-        "Attach the special `autocodex` label to any bug/feature ticket:\n",
+        "Attach the special `aswe` label to any bug/feature ticket:\n",
         "\n",
         "1. **During creation** – add it in the \"Labels\" field before hitting *Create*  \n",
-        "2. **Existing issue** – hover the label area → click the pencil icon → type `autocodex`\n",
+        "2. **Existing issue** – hover the label area → click the pencil icon → type `aswe`\n",
         "\n",
         "<img src=\"./images/add_label.png\" alt=\"Adding a label\" width=\"500\"/>\n"
       ]
@@ -248,7 +254,7 @@
         }
       },
       "source": [
-        "## End-to-end Flow in Action\n",
+        "## End-to-end Flow\n",
         "\n",
         "1. Jira label added → Automation triggers\n",
         "2. `workflow_dispatch` fires; action spins up on GitHub\n",
@@ -271,9 +277,7 @@
       "source": [
         "## Review & Merge the PR\n",
         "\n",
-        "* Confirm CI passes – tests, lint, build\n",
-        "* Approve & squash-merge\n",
-        "* The default branch protection will auto-close the Jira ticket once the PR merges if your *Smart Commits* integration is enabled\n",
+        "You can open the PR link posted in the JIRA ticket and check to see if everything looks good and then merge it. If you have branch protection and Smart Commits integration enabled, the Jira ticket will be automatically closed when the pull request is merged.\n",
         "\n",
         "## Conclusion\n",
         "\n",
@@ -284,10 +288,13 @@
         "* **Improved developer experience** - Focus on reviewing quality code instead of writing boilerplate\n",
         "* **Reduced handoff friction** - The PR is ready for review as soon as the ticket is labeled\n",
         "\n",
-        "The `codex-cli` tool is a powerful AI coding assistant that automates repetitive programming tasks. You can explore more about it at:\n",
-        "\n",
-        "* [OpenAI Codex-CLI GitHub Repository](https://github.com/openai/codex/)"
+        "The `codex-cli` tool is a powerful AI coding assistant that automates repetitive programming tasks. You can explore more about it [here](https://github.com/openai/codex/)"
       ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": []
     }
   ],
   "metadata": {