Workspace runs shows error "Failed to ingress slug Failed to clone Failed updating submodules exit status 1"

Problem

In VCS-driven Terraform Enterprise (TFE) or HCP Terraform workspaces, runs may fail during the configuration retrieval step if the repository uses Git submodules. The run logs display an error message indicating an authentication failure when cloning a submodule.

The error message in the workspace logs may include the following output:

Fatal: Authentication failed for 'https://github.com/$companyname/$path/'
Fatal: clone of 'https://github.com/$companyname/$path/' into submodule path '/local/slug-ingressXXXX/clone/$module-name' failed
failed to clone '$submodule-name', Retry Scheduled

Cause

The problem occurs because the .gitmodules file in your repository is configured to use an https URL for the submodule. TFE and HCP Terraform require ssh for authenticating to repositories to access submodules.

An incorrect .gitmodules configuration may look like this:

[submodule "modules"]
  path = modules
  url = https://github.com/$companyname/$path

Solution

To resolve this issue, you must update the url setting in your .gitmodules file to use the ssh protocol.

1. Open the .gitmodules file in the root of your repository.
2. Locate the submodule definition that is causing the failure.

3. Change the url value from the https format to the ssh format (git@github.com:...).

   For example, change this:

   [submodule "modules"]
     path = modules
     url = https://github.com/$companyname/$path

   To this:

   [submodule "modules"]
     path = modules
     url = git@github.com:companyname/path.git

4. Commit the changes to your .gitmodules file and push them to your VCS provider.
5. Trigger a new run in your TFE or HCP Terraform workspace to confirm the issue is resolved.

Additional Information

For more details on version control integration, refer to the VCS Troubleshooting for Terraform Enterprise documentation.