Handling Git Submodule Changes with Codex

Coding with ChatGPT
,
1

I’m currently testing the new Codex product and have it connected successfully to a monorepo. Everything works well: the agent is able to clone the repo, initialize submodules with git submodule update --init --recursive, and even make and build changes across the codebase. I setup another environment that has direct access to the submodule repo as well.

However, I’ve run into a limitation when it comes to submodules.

:light_bulb: The Problem

When Codex modifies files inside a submodule, the changes are made locally and the submodule commit reference in the parent repo is updated, as expected. But Codex is unable to push those changes to the submodule’s remote repository, nor can it create a pull request for the submodule itself.

This creates a broken PR in the parent repository: it references a submodule commit that doesn’t yet exist upstream. Since Codex can’t push to the submodule, it leaves the submodule state incomplete and the overall change unusable unless manually fixed.

:hammer_and_wrench: Proposed Workflow (Implemented via AGENTS.md)

To work around this, I’ve added instructions in the root AGENTS.md to guide Codex through a safe and collaborative process:

  1. Codex is allowed to make direct changes to submodule files for development and build purposes.
  2. Upon task completion, Codex creates a patch from the submodule diff and resets the submodule to its devbranch commit.
  3. A human developer manually applies the patch in the submodule repo, creates a PR, and pushes the new branch.

It’s pretty clunky and sometimes the patch isn’t created properly so there’s a lot of manual intervention and fixes involved.

:magnifying_glass_tilted_left: Feature Request

Would love to see native support in Codex for:

  • Automatically creating a second PR for submodule changes (with repo access).
  • Detecting when a submodule commit is missing from the remote and offering fallback behavior (e.g., patch creation).
  • Native AGENTS.md support for multi-repo workflows with submodules, such as orchestrating tasks between environments.

Let me know if others are running into this too or if there’s a better way to handle submodules in Codex.

3 Likes
2

@baseme Can I ask you how to set up “git submodule update --init --recursive” successfully? When I try to run the command, it always give me the error code: “Please make sure you have the correct access rights and the repository exists.”

3

You have to setup a second environment for access to the submodule directly, treating it as a standalone repo. When you have the two environments up, it will have access to pulling the submodule from the first environment.

For reference, my parent repo’s environment setup script looks like this:

corepack enable pnpm
git submodule update --init --recursive
pnpm install

And my submodule’s environment setup script is below, although it it doesn’t affect the parent’s environment:

corepack enable pnpm
pnpm install
4

@baseme Thanks for the response. I have a python repo and followed your steps to create a second environment. But it still gives me error below:

Cloning into '/workspace/ask_agent/common'... ssh: connect to host github.com port 22: Network is unreachable fatal: Could not read from remote repository. `` Please make sure you have the correct access rights and the repository exists.

5

are you able to run tasks directly on the submodule? if you can get past that I think it should work as a submodule from the other environment

6

yeah, I am able to run tasks directly on submodule. But the git submodule update always fail.

7

I realize the difference is the submodule I’m using is public which explains why in my case it can read from it from another environment, but unfortunately still can’t create multiple PRs. Your case has an additional blocker where an environment needs to have access to multiple repos. I’m not sure if there’s a way for this, hopefully this is a known issue being worked on as well or maybe something we’re missing.

8

I’ve automated the following flow to fix this:

  1. Flatten the submodules i.e. convert the submodules to plain files.
  2. Let codex work in this flat environment.
  3. Deflatten the submodules. I.e. opposite of step 1.
  4. Make PRs for all changes on all submodules.

This is all done in a small WinForms project made with (you guessed it) Codex.

Can’t share the project itself since it is company property, but I hope the guidelines can help you replicate my tool.

I’m here to help if needed.

1 Like
9

Thanks for sharing the approach. Are you telling Codex do this in the AGENT.md or are you flattening the submodules in the environment setup script? If so, can you share the prompt or command that does this? I can imagine Codex doing this flattened step for every ephemeral task it starts.

10

I do the flattening external of codex.
Flattening in codex would yield really big diffs. It’d be impossible to tell what is the real diff in such a workflow. By pre-flattening the repository you ensure codex works in a clean flat space. The conversion from flat space to submodule space is again done externally, once codex is done implementing what you need.

11

Ended up making my own open source tool afterall, not sure how can I link it here since it doesn’t let me put links in comments.