Multi-repo
Configure Gitpod to clone multiple repositories into a single workspace.
Suppose your software project comprises of multiple source control repositories. In that case, it’s possible to configure Gitpod to clone these additional repositories through the configuration keys of additionalRepositories
and mainConfiguration
in the .gitpod.yml file, which removes the need to run multiple workspaces. It makes it easier to configure services that need to be aware of each other.
Cloning additional repositories
The additionalRepositories
key is an array of repositories that contains two properties:
url
, specifying the source control URL to clone fromcheckoutLocation
, determining where the repository is cloned (relative to/workspaces
). By default, this is the cloned repository name
When the above configuration is defined, the following additional steps happen when Gitpod workspace starts:
- If you open a workspace on a branch, Gitpod will clone the same-named branch in all repositories. If such a branch doesn’t exist, Gitpod will create it from the default branch.
- The contents of
https://github.com/gitpod-io/demo-multi-repo-frontend
are cloned to/workspaces/demo-multi-repo-frontend
- The contents of
https://github.com/gitpod-io/demo-multi-repo-backend
are cloned to/workspaces/backend
After all of the source control repositories have been cloned, the before
, init
and command
tasks are executed as per usual. If you need to run commands (such as package installation or compilation) on the source control repositories that have been cloned, manually change your working directory of the task to the directory named you defined as the checkoutLocation
for the additional repo, like so:
Try it out at https://github.com/gitpod-io/demo-multi-repo-frontend
Delegating configuration
The optional mainConfiguration
configuration key, when configured with additional repositories points to the repository with the main .gitpod.yml file and makes it possible to open the same workspace from any issue, branch, or other context URL from any of the participating repositories. Since the main configuration is used for prebuilds, those will show up under the main project.
Try it out at https://github.com/gitpod-io/demo-multi-repo-backend.
Adding additional repo folders to VS Code Explorer
VS Code workspace folders
You might want to see the additionalRepositories
on your VS Code.
To do so:
- Create a file called
main.code-workspace
(for example) on your main(e.g. frontend) repository that everyone is expected to open via Gitpod. - Now you can define the folder paths:
- Specify your
.code-workspace
file path on.gitpod.yml
:
- Validate your configuration changes by running
gp validate
in your workspace. - Apply your .gitpod.yml changes by committing and restarting a new workspace.
FAQs
Single repo but instances of multiple branches
If you want to create multiple instances of one repository with different branches, you could use such a method:
Was this page helpful?