diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..86634ebf93 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,23 @@ +# Repository Guidelines + +## Project Structure & Module Organization +The cookbook is organized around runnable examples and reference articles for OpenAI APIs. Place notebooks and Python scripts under `examples//`, grouping related assets inside topic subfolders (for example, `examples/agents_sdk/`). Narrative guides and long-form docs live in `articles/`, and shared diagrams or screenshots belong in `images/`. Update `registry.yaml` whenever you add content so it appears on cookbook.openai.com, and add new author metadata in `authors.yaml` if you want custom attribution. Keep large datasets outside the repo; instead, document how to fetch them in the notebook. + +## Build, Test, and Development Commands +Use a virtual environment to isolate dependencies: +- `python -m venv .venv && source .venv/bin/activate` +- `pip install -r examples//requirements.txt` (each sample lists only what it needs) +- `jupyter lab` or `jupyter notebook` to develop interactively +- `python .github/scripts/check_notebooks.py` to validate notebook structure before pushing + +## Coding Style & Naming Conventions +Write Python to PEP 8 with four-space indentation, descriptive variable names, and concise docstrings that explain API usage choices. Name new notebooks with lowercase, dash-or-underscore-separated phrases that match their directory—for example `examples/gpt-5/prompt-optimization-cookbook.ipynb`. Keep markdown cells focused and prefer numbered steps for multi-part workflows. Store secrets in environment variables such as `OPENAI_API_KEY`; never hard-code keys inside notebooks. + +## Testing Guidelines +Execute notebooks top-to-bottom after installing dependencies and clear lingering execution counts before committing. For Python modules or utilities, include self-check cells or lightweight `pytest` snippets and show how to run them (for example, `pytest examples/object_oriented_agentic_approach/tests`). When contributions depend on external services, mock responses or gate the cells behind clearly labeled opt-in flags. + +## Commit & Pull Request Guidelines +Use concise, imperative commit messages that describe the change scope (e.g., "Add agent portfolio collaboration demo"). Every PR should provide a summary, motivation, and self-review, and must tick the registry and authors checklist from `.github/pull_request_template.md`. Link issues when applicable and attach screenshots or output snippets for UI-heavy content. Confirm CI notebook validation passes locally before requesting review. + +## Metadata & Publication Workflow +New or relocated content must have an entry in `registry.yaml` with an accurate path, date, and tag set so the static site generator includes it. When collaborating, coordinate author slugs in `authors.yaml` to avoid duplicates, and run `python -m yaml lint registry.yaml` (or your preferred YAML linter) to catch syntax errors before submitting. diff --git a/authors.yaml b/authors.yaml index ddeeb35b15..cd407f6c69 100644 --- a/authors.yaml +++ b/authors.yaml @@ -492,3 +492,11 @@ heejingithub: name: "Heejin Cho" website: "https://www.linkedin.com/in/heejc/" avatar: "https://avatars.githubusercontent.com/u/169293861" + + +himadri: + name: "Himadri Acharya" + website: "https://www.linkedin.com/in/himadri-acharya-086ba261/" + avatar: "https://avatars.githubusercontent.com/u/14100684?v=4" + + \ No newline at end of file diff --git a/examples/codex/Autofix-github-actions.ipynb b/examples/codex/Autofix-github-actions.ipynb new file mode 100644 index 0000000000..b492626bb1 --- /dev/null +++ b/examples/codex/Autofix-github-actions.ipynb @@ -0,0 +1,223 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "e2884696", + "metadata": {}, + "source": [ + "# Autofix CI failures on GitHub with Codex-cli\n", + "\n", + "## Purpose of this cookbook\n", + "\n", + "This cookbook shows you how to embed the OpenAI Codex CLI into your CI/CD pipeline so that when your builds or tests fail, codex automatically generates & proposes fixes. The following is an example in a node project with CI running in GitHub Actions. \n", + "\n", + "## End to End Flow\n", + "\n", + "Below is the pipeline flow we’ll implement:\n", + "\n", + "![](images/ci-codex-workflow.png)" + ] + }, + { + "cell_type": "markdown", + "id": "f83ce964", + "metadata": {}, + "source": [ + "## Prerequisites\n", + "\n", + "- A GitHub Repo with Actions workflows\n", + "\n", + "- You’ll need to create `OPENAI_API_KEY` as an environment variable in GitHub settings under https://github.com/{org-name}/{repo-name}/settings/secrets/actions. You can also set this at org level(for sharing secrets across multiple repos) \n", + "\n", + "- Codex requires python as a prerequisite to use `codex login`\n", + "\n", + "- You’ll need to check the setting to enable actions to create PRs on your repo, and also in your organization:\n", + "\n", + "![](images/github-pr-settings.png)" + ] + }, + { + "cell_type": "markdown", + "id": "99f5bed1", + "metadata": {}, + "source": [ + "\n", + "## Step 3: Insert Codex in your CI pipeline\n", + "\n", + "The following YAML shows a GitHub action that auto triggers when CI fails, installs Codex, uses codex exec and then makes a PR on the failing branch with the fix. Replace \"CI\" with the name of the workflow you want to monitor. " + ] + }, + { + "cell_type": "markdown", + "id": "a9f9b368", + "metadata": {}, + "source": [ + "```yaml\n", + "\n", + "name: Codex Auto-Fix on Failure\n", + "\n", + "on:\n", + " workflow_run:\n", + " # Trigger this job after any run of the primary CI workflow completes\n", + " workflows: [\"CI\"]\n", + " types: [completed]\n", + "\n", + "permissions:\n", + " contents: write\n", + " pull-requests: write\n", + "\n", + "jobs:\n", + " auto-fix:\n", + " # Only run when the referenced workflow concluded with a failure\n", + " if: ${{ github.event.workflow_run.conclusion == 'failure' }}\n", + " runs-on: ubuntu-latest\n", + " env:\n", + " OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n", + " FAILED_WORKFLOW_NAME: ${{ github.event.workflow_run.name }}\n", + " FAILED_RUN_URL: ${{ github.event.workflow_run.html_url }}\n", + " FAILED_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}\n", + " FAILED_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}\n", + " steps:\n", + " - name: Check prerequisites\n", + " run: |\n", + " if [ -z \"$OPENAI_API_KEY\" ]; then\n", + " echo \"OPENAI_API_KEY secret is not set. Skipping auto-fix.\" >&2\n", + " exit 1\n", + " fi\n", + "\n", + " - name: Checkout failing ref\n", + " uses: actions/checkout@v4\n", + " with:\n", + " ref: ${{ env.FAILED_HEAD_SHA }}\n", + " fetch-depth: 0\n", + "\n", + " - name: Setup Node.js\n", + " uses: actions/setup-node@v4\n", + " with:\n", + " node-version: '20'\n", + " cache: 'npm'\n", + "\n", + " - name: Install dependencies\n", + " run: |\n", + " if [ -f package-lock.json ]; then npm ci; else npm i; fi\n", + "\n", + " - name: Prepare Codex prerequisites\n", + " shell: bash\n", + " run: |\n", + " # Ensure python3 exists for Codex' login helper\n", + " if ! command -v python3 >/dev/null 2>&1; then\n", + " sudo apt-get update\n", + " sudo apt-get install -y python3\n", + " fi\n", + "\n", + " # Ensure Codex config dir exists and is writable\n", + " mkdir -p \"$HOME/.codex\"\n", + " # (Optional) pin an explicit home for Codex config/logs\n", + " echo \"CODEX_HOME=$HOME/.codex\" >> $GITHUB_ENV\n", + "\n", + " - name: Install Codex CLI\n", + " run: npm i -g @openai/codex\n", + "\n", + " - name: Authenticate Codex (non-interactive)\n", + " env:\n", + " # if you set CODEX_HOME above, export it here too\n", + " CODEX_HOME: ${{ env.CODEX_HOME }}\n", + " OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n", + " run: codex login --api-key \"$OPENAI_API_KEY\"\n", + "\n", + " - name: Run Codex to fix CI failure\n", + " run: |\n", + " codex exec --full-auto --sandbox workspace-write \"You are working in a Node.js monorepo with Jest tests and GitHub Actions. Read the repository, run the test suite, identify the minimal change needed to make all tests pass, implement only that change, and stop. Do not refactor unrelated code or files. Keep changes small and surgical.\"\n", + "\n", + " - name: Verify tests\n", + " run: npm test --silent\n", + "\n", + " - name: Create pull request with fixes\n", + " if: success()\n", + " uses: peter-evans/create-pull-request@v6\n", + " with:\n", + " commit-message: \"fix(ci): auto-fix failing tests via Codex\"\n", + " branch: codex/auto-fix-${{ github.event.workflow_run.run_id }}\n", + " base: ${{ env.FAILED_HEAD_BRANCH }}\n", + " title: \"Auto-fix failing CI via Codex\"\n", + " body: |\n", + " Codex automatically generated this PR in response to a CI failure on workflow `${{ env.FAILED_WORKFLOW_NAME }}`.\n", + "\n", + " Failed run: ${{ env.FAILED_RUN_URL }}\n", + " Head branch: `${{ env.FAILED_HEAD_BRANCH }}`\n", + "\n", + " This PR contains minimal changes intended solely to make the CI pass.\n", + "```\n" + ] + }, + { + "cell_type": "markdown", + "id": "8148024b", + "metadata": {}, + "source": [ + "## Step 4: Actions Workflow kicked off\n", + "\n", + "You can navigate to the Actions tab under Repo to view the failing jobs in your Actions workflow. \n", + "\n", + "\n", + "![](images/failing-workflow.png)\n" + ] + }, + { + "cell_type": "markdown", + "id": "64671aae", + "metadata": {}, + "source": [ + "The Codex workflow should be triggered upon completion of the failed workflow. \n", + "\n", + "\n", + "![](images/codex-workflow.png)\n", + "\n" + ] + }, + { + "cell_type": "markdown", + "id": "d08a3ecc", + "metadata": {}, + "source": [ + "## Step 5: Codex generated PR for review\n", + "And after the Codex workflow completes execution, it should open a pull request from the feature branch codex/auto-fix. Check to see if everything looks good and then merge it.\n", + "\n", + "![](images/codex-pr.png)" + ] + }, + { + "cell_type": "markdown", + "id": "f4c1f3a0", + "metadata": {}, + "source": [ + "## Conclusion\n", + "\n", + "This automation seamlessly integrates OpenAI Codex CLI with GitHub Actions to automatically propose fixes for failing CI runs.\n", + "\n", + "By leveraging Codex, you can reduce manual intervention, accelerate code reviews, and keep your main branch healthy. The workflow ensures that test failures are addressed quickly and efficiently, letting developers focus on higher-value tasks. Explore more about codex-cli and its capabilities [here](https://github.com/openai/codex/)." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.13.7" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/examples/codex/images/ci-codex-workflow.png b/examples/codex/images/ci-codex-workflow.png new file mode 100644 index 0000000000..4be3dc4fb4 Binary files /dev/null and b/examples/codex/images/ci-codex-workflow.png differ diff --git a/examples/codex/images/codex-pr.png b/examples/codex/images/codex-pr.png new file mode 100644 index 0000000000..f9ba75ca12 Binary files /dev/null and b/examples/codex/images/codex-pr.png differ diff --git a/examples/codex/images/codex-workflow.png b/examples/codex/images/codex-workflow.png new file mode 100644 index 0000000000..ffa1b7f71f Binary files /dev/null and b/examples/codex/images/codex-workflow.png differ diff --git a/examples/codex/images/failing-workflow.png b/examples/codex/images/failing-workflow.png new file mode 100644 index 0000000000..342f6811b3 Binary files /dev/null and b/examples/codex/images/failing-workflow.png differ diff --git a/examples/codex/images/github-pr-settings.png b/examples/codex/images/github-pr-settings.png new file mode 100644 index 0000000000..723e267179 Binary files /dev/null and b/examples/codex/images/github-pr-settings.png differ diff --git a/registry.yaml b/registry.yaml index 37917de9df..3b38ccbe10 100644 --- a/registry.yaml +++ b/registry.yaml @@ -2529,3 +2529,17 @@ - katiagg tags: - images + + +- title: Codex CLI to automatically fix CI failures + path: examples/codex/codex-cicd.ipynb + date: 2025-09-30 + authors: + - himadri518 + - alwell-kevin + tags: + - codex + + + +