Push modes and PRs

ChatGPT can do almost all coding work before GitHub direct push is enabled: clone, inspect, edit, test, and commit. This page covers the write step after the local commit exists.

Use this quick rule:

• use publish-pr when you want review
• use request-push when ChatGPT should ask for one repo-scoped push window
• use grant-push when the operator should approve remotely
• use github mode yolo when repeated approvals are slowing down a trusted session

Open a pull request

After committing locally, ChatGPT can publish a generated branch and open a PR without gh or a direct push grant:

zodex-agent github publish-pr \
  --repo amxv/zodex \
  --title "Improve zodex runtime docs" \
  --base main \
  --body "Adds detailed runtime, grant, and operations documentation."

For a draft PR:

zodex-agent github publish-pr \
  --repo amxv/zodex \
  --title "Improve zodex runtime docs" \
  --base main \
  --draft

publish-pr sends a bundle of the current committed HEAD to the publisher daemon. The daemon mints short-lived writer-app credentials, pushes a generated branch, opens the PR, and keeps credentials inside the daemon.

Request access from the Sprite

When a direct push should be allowed from inside the ChatGPT session, request a repo-scoped push grant:

zodex-agent github request-push --repo amxv/zodex

The command runs a GitHub App device-flow authorization. It prints a verification URL and user code, tries to open the URL, and activates the grant after approval.

The default grant TTL is 30m:

zodex-agent github request-push --repo amxv/zodex --ttl 30m

For a longer grant:

zodex-agent github request-push --repo amxv/zodex --ttl 2h

For a grant without TTL enforcement:

zodex-agent github request-push --repo amxv/zodex --no-ttl

Use --no-ttl only for an intentional operator-controlled window.

Push normally

After the grant is active, use Git directly:

git push origin main

For branch-based work:

git switch -c docs-runtime-guide
git push origin docs-runtime-guide

The zodex Git credential helper uses the active repo grant. It does not make unrelated repositories writable.

List grants

On the Sprite:

zodex-agent github list-grants

From the operator machine:

zodex github list-grants --sprite dev-sprite

Use this before assuming a push failure is caused by code, branch protection, or GitHub permissions.

Revoke when finished

Revoke after the push step:

zodex-agent github revoke-push --repo amxv/zodex

To also clear local device-flow auth state:

zodex-agent github revoke-push --repo amxv/zodex --forget-local-auth

When to use YOLO instead

Use YOLO mode when direct push should remain available across repeated commits in a trusted session:

zodex github mode yolo --sprite dev-sprite --repo amxv/zodex --ttl 4h

Return to the default policy when finished:

zodex github mode default --sprite dev-sprite

For the full decision guide, see Write modes.