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
TheadditionalRepositories
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
.gitpod.yml
- 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
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:
.gitpod.yml
Delegating configuration
The optionalmainConfiguration
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.
.gitpod.yml
Adding additional repo folders to VS Code Explorer

VS Code workspace folders
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
:
.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:.gitpod.yml