Skip to content

Commit 2913aa7

Browse files
narenoainarenoai
committed
add new cookbook for codex-jira
1 parent a57c80e commit 2913aa7

File tree

7 files changed

+323
-0
lines changed

7 files changed

+323
-0
lines changed

‎examples/codex/images/add_label.png‎

121 KB
Loading

‎examples/codex/images/codex_action.png‎

305 KB
Loading

‎examples/codex/images/jira_comment.png‎

91 KB
Loading

‎examples/codex/images/jira_rule.png‎

326 KB
Loading

‎examples/codex/images/jira_status_change.png‎

85.1 KB
Loading

‎examples/codex/jira-github.ipynb‎

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {
6+
"vscode": {
7+
"languageId": "raw"
8+
}
9+
},
10+
"source": [
11+
"# Automate Jira ↔ GitHub with `codex-cli`\n",
12+
"\n",
13+
"## What you'll build\n",
14+
"\n",
15+
"By the end of this walkthrough, you'll have an end-to-end automation that turns a **labelled Jira issue** into a\n",
16+
"fully-fledged **GitHub pull request**, keeps the Jira ticket updated throughout the review process, and finally merges\n",
17+
"the code once checks pass – all driven by the\n",
18+
"[`codex-cli`](https://github.com/openai/openai-codex) agent working inside a GitHub Action.\n",
19+
"\n",
20+
"# <img src=\"./images/codex_action.png\" alt=\"Full data-flow diagram\" width=\"500\"/>\n"
21+
]
22+
},
23+
{
24+
"cell_type": "markdown",
25+
"metadata": {
26+
"vscode": {
27+
"languageId": "raw"
28+
}
29+
},
30+
"source": [
31+
"The flow is:\n",
32+
"1. Label a Jira issue \n",
33+
"2. Jira Automation calls the GitHub Action \n",
34+
"3. The action spins up `codex-cli` to implement the change \n",
35+
"4. A PR is opened\n",
36+
"5. Jira is transitioned & annotated – creating a neat, zero-click loop\n",
37+
"\n",
38+
"## Prerequisites\n",
39+
"\n",
40+
"* Jira: project admin rights + ability to create automation rules \n",
41+
"* GitHub: write access, permission to add repository secrets, and a protected `main` branch \n",
42+
"* API keys & secrets placed as repository secrets:\n",
43+
" * `OPENAI_API_KEY` – your OpenAI key for `codex-cli` \n",
44+
" * `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` – for REST calls from the action \n",
45+
"* `codex-cli` installed locally (`pnpm add -g @openai/codex`) for ad-hoc testing \n",
46+
"* A repository that already contains a `.github/workflows/` folder (any Node project is fine)\n"
47+
]
48+
},
49+
{
50+
"cell_type": "markdown",
51+
"metadata": {
52+
"vscode": {
53+
"languageId": "raw"
54+
}
55+
},
56+
"source": [
57+
"## Create the Jira Automation Rule\n",
58+
"\n",
59+
"<img src=\"./images/jira_rule.png\" alt=\"Automation Rule\" width=\"500\"/>\n",
60+
"\n",
61+
"* **Trigger – Issue updated**: fires whenever labels change \n",
62+
"* **Condition – `labels` contains `autocodex`**: limits noise to explicitly opted-in issues \n",
63+
"* **Action – Send web request**: POSTs the issue key/summary/description to your GitHub Action's `workflow_dispatch` endpoint\n"
64+
]
65+
},
66+
{
67+
"cell_type": "markdown",
68+
"metadata": {
69+
"vscode": {
70+
"languageId": "raw"
71+
}
72+
},
73+
"source": [
74+
"## Add the GitHub Action\n",
75+
"\n",
76+
"Create a workflow file in your `.github/workflows/` directory with the following YAML (Modify it as needed):\n"
77+
]
78+
},
79+
{
80+
"cell_type": "markdown",
81+
"metadata": {},
82+
"source": [
83+
"```yaml\n",
84+
"name: Codex Automated PR\n",
85+
"on:\n",
86+
" workflow_dispatch:\n",
87+
" inputs:\n",
88+
" issue_key:\n",
89+
" description: 'JIRA issue key (e.g., PROJ-123)'\n",
90+
" required: true\n",
91+
" issue_summary:\n",
92+
" description: 'Brief summary of the issue'\n",
93+
" required: true\n",
94+
" issue_description:\n",
95+
" description: 'Detailed issue description'\n",
96+
" required: true\n",
97+
"\n",
98+
"permissions:\n",
99+
" contents: write # allow the action to push code & open the PR\n",
100+
" pull-requests: write # allow the action to create and update PRs\n",
101+
"\n",
102+
"jobs:\n",
103+
" codex_auto_pr:\n",
104+
" runs-on: ubuntu-latest\n",
105+
"\n",
106+
" steps:\n",
107+
" # 0 – Checkout repository\n",
108+
" - uses: actions/checkout@v4\n",
109+
" with:\n",
110+
" fetch-depth: 0 # full history → lets Codex run tests / git blame if needed\n",
111+
"\n",
112+
" # 1 – Set up Node.js and Codex\n",
113+
" - uses: actions/setup-node@v4\n",
114+
" with:\n",
115+
" node-version: 22\n",
116+
" - run: pnpm add -g @openai/codex\n",
117+
"\n",
118+
" # 2 – Export / clean inputs (available via $GITHUB_ENV)\n",
119+
" - id: vars\n",
120+
" run: |\n",
121+
" echo \"ISSUE_KEY=${{ github.event.inputs.issue_key }}\" >> $GITHUB_ENV\n",
122+
" echo \"TITLE=${{ github.event.inputs.issue_summary }}\" >> $GITHUB_ENV\n",
123+
" echo \"RAW_DESC=${{ github.event.inputs.issue_description }}\" >> $GITHUB_ENV\n",
124+
" DESC_CLEANED=$(echo \"${{ github.event.inputs.issue_description }}\" | tr '\\n' ' ' | sed 's/\"/'\\''/g')\n",
125+
" echo \"DESC=$DESC_CLEANED\" >> $GITHUB_ENV\n",
126+
" echo \"BRANCH=codex/${{ github.event.inputs.issue_key }}\" >> $GITHUB_ENV\n",
127+
"\n",
128+
" # 3 – Transition Jira issue to \"In Progress\"\n",
129+
" - name: Jira – Transition to In Progress\n",
130+
" env:\n",
131+
" ISSUE_KEY: ${{ env.ISSUE_KEY }}\n",
132+
" JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}\n",
133+
" JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}\n",
134+
" JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}\n",
135+
" run: |\n",
136+
" curl -sS -X POST \\\n",
137+
" --url \"$JIRA_BASE_URL/rest/api/3/issue/$ISSUE_KEY/transitions\" \\\n",
138+
" --user \"$JIRA_EMAIL:$JIRA_API_TOKEN\" \\\n",
139+
" --header 'Content-Type: application/json' \\\n",
140+
" --data '{\"transition\":{\"id\":\"21\"}}'\n",
141+
"\n",
142+
" # 4 – Set Git author for CI commits\n",
143+
" - run: |\n",
144+
" git config user.email \"github-actions[bot]@users.noreply.github.com\"\n",
145+
" git config user.name \"github-actions[bot]\"\n",
146+
"\n",
147+
" # 5 – Let Codex implement & commit (no push yet)\n",
148+
" - name: Codex implement & commit\n",
149+
" env:\n",
150+
" OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n",
151+
" CODEX_QUIET_MODE: \"1\" # suppress chatty logs\n",
152+
" run: |\n",
153+
" set -e\n",
154+
" codex --approval-mode full-auto --no-terminal --quiet \\\n",
155+
" \"Implement JIRA ticket $ISSUE_KEY: $TITLE. $DESC\"\n",
156+
"\n",
157+
" git add -A\n",
158+
" git commit -m \"feat($ISSUE_KEY): $TITLE\"\n",
159+
"\n",
160+
" # 6 – Open (and push) the PR in one go\n",
161+
" - id: cpr\n",
162+
" uses: peter-evans/create-pull-request@v6\n",
163+
" with:\n",
164+
" token: ${{ secrets.GITHUB_TOKEN }}\n",
165+
" base: main\n",
166+
" branch: ${{ env.BRANCH }}\n",
167+
" title: \"${{ env.TITLE }} (${{ env.ISSUE_KEY }})\"\n",
168+
" body: |\n",
169+
" Auto-generated by Codex for JIRA **${{ env.ISSUE_KEY }}**.\n",
170+
" ---\n",
171+
" ${{ env.DESC }}\n",
172+
"\n",
173+
" # 7 – Transition Jira to \"In Review\" & drop the PR link\n",
174+
" - name: Jira – Transition to In Review & Comment PR link\n",
175+
" env:\n",
176+
" ISSUE_KEY: ${{ env.ISSUE_KEY }}\n",
177+
" JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}\n",
178+
" JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}\n",
179+
" JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}\n",
180+
" PR_URL: ${{ steps.cpr.outputs.pull-request-url }}\n",
181+
" run: |\n",
182+
" # Status transition\n",
183+
" curl -sS -X POST \\\n",
184+
" --url \"$JIRA_BASE_URL/rest/api/3/issue/$ISSUE_KEY/transitions\" \\\n",
185+
" --user \"$JIRA_EMAIL:$JIRA_API_TOKEN\" \\\n",
186+
" --header 'Content-Type: application/json' \\\n",
187+
" --data '{\"transition\":{\"id\":\"31\"}}'\n",
188+
"\n",
189+
" # Comment with PR link\n",
190+
" curl -sS -X POST \\\n",
191+
" --url \"$JIRA_BASE_URL/rest/api/3/issue/$ISSUE_KEY/comment\" \\\n",
192+
" --user \"$JIRA_EMAIL:$JIRA_API_TOKEN\" \\\n",
193+
" --header 'Content-Type: application/json' \\\n",
194+
" --data \"{\\\"body\\\":{\\\"type\\\":\\\"doc\\\",\\\"version\\\":1,\\\"content\\\":[{\\\"type\\\":\\\"paragraph\\\",\\\"content\\\":[{\\\"type\\\":\\\"text\\\",\\\"text\\\":\\\"PR created: $PR_URL\\\"}]}]}}\"\n",
195+
"```\n"
196+
]
197+
},
198+
{
199+
"cell_type": "markdown",
200+
"metadata": {
201+
"vscode": {
202+
"languageId": "raw"
203+
}
204+
},
205+
"source": [
206+
"## Key Steps in the Workflow\n",
207+
"\n",
208+
"1. **Codex Implementation & Commit** (Step 5)\n",
209+
" - Uses OpenAI API to implement the JIRA ticket requirements\n",
210+
" - Runs codex CLI in full-auto mode without terminal interaction\n",
211+
" - Commits all changes with standardized commit message\n",
212+
"\n",
213+
"2. **Create Pull Request** (Step 6) \n",
214+
" - Uses peter-evans/create-pull-request action\n",
215+
" - Creates PR against main branch\n",
216+
" - Sets PR title and description from JIRA ticket info\n",
217+
" - Returns PR URL for later use\n",
218+
"\n",
219+
"3. **JIRA Updates** (Step 7)\n",
220+
" - Transitions ticket to \"In Review\" status via JIRA API\n",
221+
" - Posts comment with PR URL on the JIRA ticket\n",
222+
" - Uses curl commands to interact with JIRA REST API\n"
223+
]
224+
},
225+
{
226+
"cell_type": "markdown",
227+
"metadata": {
228+
"vscode": {
229+
"languageId": "raw"
230+
}
231+
},
232+
"source": [
233+
"## Label an Issue\n",
234+
"\n",
235+
"Attach the special `autocodex` label to any bug/feature ticket:\n",
236+
"\n",
237+
"1. **During creation** – add it in the \"Labels\" field before hitting *Create* \n",
238+
"2. **Existing issue** – hover the label area → click the pencil icon → type `autocodex`\n",
239+
"\n",
240+
"<img src=\"./images/add_label.png\" alt=\"Adding a label\" width=\"500\"/>\n"
241+
]
242+
},
243+
{
244+
"cell_type": "markdown",
245+
"metadata": {
246+
"vscode": {
247+
"languageId": "raw"
248+
}
249+
},
250+
"source": [
251+
"## End-to-end Flow in Action\n",
252+
"\n",
253+
"1. Jira label added → Automation triggers\n",
254+
"2. `workflow_dispatch` fires; action spins up on GitHub\n",
255+
"3. `codex-cli` edits the codebase & commits\n",
256+
"4. PR is opened on the generated branch\n",
257+
"5. Jira is moved to **In Review** and a comment with the PR URL is posted\n",
258+
"6. Reviewers are notified per your normal branch protection settings\n",
259+
"\n",
260+
"<img src=\"./images/jira_comment.png\" alt=\"Jira comment with PR link\" width=\"300\"/>\n",
261+
"<img src=\"./images/jira_status_change.png\" alt=\"Jira status transition to In Review\" width=\"300\"/>\n"
262+
]
263+
},
264+
{
265+
"cell_type": "markdown",
266+
"metadata": {
267+
"vscode": {
268+
"languageId": "raw"
269+
}
270+
},
271+
"source": [
272+
"## Review & Merge the PR\n",
273+
"\n",
274+
"* Confirm CI passes – tests, lint, build\n",
275+
"* Approve & squash-merge\n",
276+
"* The default branch protection will auto-close the Jira ticket once the PR merges if your *Smart Commits* integration is enabled\n",
277+
"\n",
278+
"## Conclusion\n",
279+
"\n",
280+
"This automation streamlines your development workflow by creating a seamless integration between Jira and GitHub:\n",
281+
"\n",
282+
"* **Zero-click implementation** - AI handles the code changes based on ticket descriptions\n",
283+
"* **Automatic status tracking** - Tickets progress through your workflow without manual updates\n",
284+
"* **Improved developer experience** - Focus on reviewing quality code instead of writing boilerplate\n",
285+
"* **Reduced handoff friction** - The PR is ready for review as soon as the ticket is labeled\n",
286+
"\n",
287+
"The `codex-cli` tool is a powerful AI coding assistant that automates repetitive programming tasks. You can explore more about it at:\n",
288+
"\n",
289+
"* [OpenAI Codex-CLI GitHub Repository](https://github.com/openai/codex/)"
290+
]
291+
}
292+
],
293+
"metadata": {
294+
"kernelspec": {
295+
"display_name": ".venv",
296+
"language": "python",
297+
"name": "python3"
298+
},
299+
"language_info": {
300+
"codemirror_mode": {
301+
"name": "ipython",
302+
"version": 3
303+
},
304+
"file_extension": ".py",
305+
"mimetype": "text/x-python",
306+
"name": "python",
307+
"nbconvert_exporter": "python",
308+
"pygments_lexer": "ipython3",
309+
"version": "3.12.10"
310+
}
311+
},
312+
"nbformat": 4,
313+
"nbformat_minor": 2
314+
}

‎registry.yaml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,15 @@
33
# This file is used to generate cookbook.openai.com. It specifies which paths we
44
# should build pages for, and indicates metadata such as tags, creation date and
55
# authors for each page.
6+
- title: Automate Jira ↔ GitHub with Codex
7+
path: examples/codex/jira-github.ipynb
8+
date: 2025-06-21
9+
authors:
10+
- alwell-kevin
11+
- narenoai
12+
tags:
13+
- codex
14+
- automation
615

716
- title: Fine-Tuning Techniques - Choosing Between SFT, DPO, and RFT (With a Guide to DPO)
817
path: examples/Fine_tuning_direct_preference_optimization_guide.ipynb

0 commit comments

Comments
 (0)