Description

Based on Coolify issue #2731 and its community-discovered solutions, the documentation should be updated to explain how to properly configure private Git submodules when deploying applications.

Problem

Users encounter authentication failures when trying to clone private Git submodules, with errors like:

fatal: could not read Username for 'https://github.com': No such device or address
fatal: clone of 'https://github.com/???/submodule.git' into submodule path failed

Solutions to Document

Prerequisites

GitHub App Permissions:

• The GitHub App must have access permissions to both the main repository AND all submodule repositories

Solution 1: Use Relative Paths in .gitmodules (Recommended)

The most reliable solution is to use relative paths instead of absolute URLs in the .gitmodules file:

Before:

[submodule "prisma"]
    path = prisma
    url = https://github.com/organization/prisma.git

After:

[submodule "prisma"]
    path = prisma
    url = ../prisma.git

Important Notes:

• This approach works because Coolify uses SSH protocol for authentication
• All submodules must be from the same GitHub organization/user when using relative paths
• The "Submodules" checkbox in Advanced settings should remain checked

Solution 2: Alternative Workaround

Some users report success by:

1. Unchecking the "Submodules" option in the Advanced tab
2. This is counter-intuitive but has worked in some cases

Solution 3: SSH Key Configuration

For cases where relative paths don't work:

1. Add the server's SSH key to the GitHub account's SSH keys
2. Ensure the GitHub App has access to all submodule repositories

Suggested Documentation Location

This information should be added to:

• The Applications page under the Git Submodules section
• Consider adding a dedicated troubleshooting section for common Git submodule issues

Additional Context

• Multiple issues report the same problem (#2731, #3354)
• The solution has helped many users (15+ positive reactions on the original solution)
• This is a common pain point that deserves proper documentation

References

• Original issue: [Bug]: Failed to clone Git submodule coolify#2731
• Related issue: [Bug]: Unable to clone private Git submodules when deploying with GitHub App integration coolify#3354