From Prompt to Merge: A Complete Codex GitHub Workflow · vibeshub

Most “how to use Codex” guides stop at the diff. You prompt, the agent edits, you get working code. But on a team, the code is only half the job. The other half is getting that change reviewed and merged on GitHub without your reviewer reverse-engineering what the agent did.

This is the full Codex GitHub workflow: from the first prompt to a merged pull request. Seven steps, each one a thing you actually do, plus the team tips that keep it smooth.

Step 1: Set up the session

Start in the repo you are working in, on a branch for the change. The Codex CLI reads your actual codebase, so the more context it has, the better its edits.

Branch first: git checkout -b fix-auth-timeout. Every session maps to one branch, which later maps to one pull request.
Give the agent a clear goal in the first prompt. “Fix the auth timeout that logs users out after 5 minutes” beats “fix the bug.”
Let it investigate before it edits. Codex will read files and run commands to orient itself. That exploration is part of the reasoning you will want to keep.

Step 2: Run the session

Work the problem in a normal back-and-forth. Prompt, review the proposed change, correct course, repeat. This is the AI pair-programming loop: you set direction, the agent does the mechanical work, you keep judgment in the chair.

A few habits pay off later:

Correct in the session, not after. If the agent heads the wrong way, say so. The correction becomes part of the record.
Keep one session to one concern. A session that drifts from a bug fix into a refactor produces a pull request that is hard to review.
Run the tests inside the session. When the agent runs your test suite and reacts to failures, the reviewer can see the code was exercised, not just written.

Step 3: Capture the trace

When the session ends, the reasoning normally vanishes with your terminal. A session trace keeps it: the prompts you gave, the files Codex read, the commands it ran, the edits in order, and the points where it changed direction.

vibeshub captures the session locally as you work, so by the time you are ready to open a pull request, the trace already exists. No copy-pasting logs, no screenshots.

Step 4: Redact secrets

A raw session can contain API keys, tokens, environment variables, and internal paths. None of that belongs in a pull request.

Redaction runs locally first, so secrets are stripped before anything leaves your machine. A second pass runs server-side as a backstop. Two stages, not one, so a missed value on either side still gets caught.

Step 5: Post the trace to the pull request

Open the pull request the way you always do, then attach the trace to it. Now the PR carries both artifacts in one place: the diff and the reasoning behind it.

Intent is stated, not guessed. The prompts say what the change was for.
Odd-looking edits trace back to the step that produced them.
Scope is visible. What the session set out to do and what it actually touched are both on the page.

Access mirrors your GitHub permissions. If a teammate can see the repo, they can see the trace. If they cannot, they cannot. There are no separate access lists to manage.

Step 6: Review with the session in view

This is where the workflow earns its keep. Reviewing an AI-generated PR from the diff alone is detective work: read the change, guess the intent, check the code against the guess. With the trace attached, the reviewer reads the actual session instead.

Confident-looking code gets a real check, because the path that produced it is visible.
A hallucinated API or a misread file shows up in the trace, not just in production.
The reviewer spends their time on judgment calls, not on reconstructing context.

Step 7: Merge

Once the review is satisfied, merge as usual. The trace stays attached to the pull request, so six months from now, when someone asks why this function looks the way it does, the answer is on the PR instead of lost.

Team tips

One session, one branch, one PR. Keeping the mapping clean makes every trace easy to follow.
Make trace-on-PR the norm, not the exception. Reviewers stop asking “what was this trying to do” once the answer is always attached.
Use standalone traces for the non-PR work too. Debugging sessions and spikes are worth sharing with the same redaction and access rules, without forcing a pull request to exist first.
Let the trace carry the context, not the PR description. You do not need to write a paragraph explaining the agent’s reasoning when the session already shows it.

The Codex part of this workflow is the easy half. The hard half has always been getting AI-generated changes through review and into main with the context intact. Capture the session, redact it, and post it where the review happens, and the whole path from prompt to merge stays legible.

If your team is shipping Codex PRs and reviewing them by guessing at intent, vibeshub is the missing half of the artifact. It works the same way for Claude Code sessions, so a mixed-agent team gets one review workflow instead of two.