Advanced Topic
This article assumes you are already familiar with Git submodules, what they are, and how to use them. Please refer to the official Git submodule documentation for more information.
While Stoplight does not directly support Git submodule usage from within the Studio interface directly, if your repository relies on submodules then there are still ways to work with them. Each is discussed in greater detail below.
Sanity Check - Is the submodule content really needed by Stoplight?
There are many reasons to leverage Git submodules, but not all of them mean that the content stored in a submodule is relevant to Stoplight. Before continuing, make sure that the submodule is required by content exposed in Stoplight. This can include:
- OpenAPI / Swagger / JSON Schema files
- Markdown documents
- Images
If the submodule does not contain any of these artifacts, then you may not need to resolve them, and you may not need to take any action at all.
Editing Projects that Contain Submodules
Studio does not resolve submodules directly, however Studio can work with repositories that contain submodules without issue. This means that any content present in a submodule will not be present from the Studio editor interface, but you can still work in a repository that contains submodules without fear of modifying them.
In the case you need to interact with submodule content, you have two options:
- From Studio (web or desktop), clone and modify the submodule repository directly. Instead of cloning the parent repository (the repo containing the submodule), you would work within the submodule repository directly instead.
- From Studio (desktop only), clone the parent repository locally to your computer and manually resolve submodules using a local Git client. This way Studio interacts with the repository as if the submodule was part of the parent repository. While this allows you to modify submodule content, it will be up to you for committing and pushing submodule changes to the respective repositories.
Publishing Submodule Content
If you are using Stoplight's built-in webhook automation, then you will find that submodule content is not analyzed as part of the typical webhook event. In order to publish content that requires resolving a submodule, you will need to setup your own CLI-based workflow (CI/CD automation, etc.) that pulls submodules prior to publishing. For example:
# navigate to repo directory
cd my-project/
# update submodule content
git submodule update --init --recursive
# publish to Stoplight
npx @stoplight/cli@4 push --ci-token XXXXX --url https://example.stoplight.io
Reach out to support@stoplight.io with any questions.