Multi-repo

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 from
checkoutLocation, determining where the repository is cloned (relative to /workspaces). By default, this is the cloned repository name

yml

# example .gitpod.yml from https://github.com/gitpod-io/demo-multi-repo-frontend
additionalRepositories:
    - url: https://github.com/gitpod-io/demo-multi-repo-backend
      checkoutLocation: backend

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:

yml

# example .gitpod.yml from https://github.com/gitpod-io/demo-multi-repo-frontend
additionalRepositories:
    - url: https://github.com/gitpod-io/demo-multi-repo-backend
      checkoutLocation: backend

tasks:
    - name: backend
      # change working directory as per configured in `checkoutLocation`
      # which is configured above as `/workspaces/backend`
      before: |
          cd ../backend
      init: |
          echo npm install
      command: |
          echo npm run dev

      # changing of working directory is not required as these tasks will
      # by default by executed in `/workspaces/demo-multi-repo-frontend`
    - name: frontend
      init: |
          echo npm install
          echo npm run build
      command: |
          echo npm run dev

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.

yml

# example .gitpod.yml from https://github.com/gitpod-io/demo-multi-repo-backend
mainConfiguration: https://github.com/gitpod-io/demo-multi-repo-frontend

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:

json

{
	// All paths are relative to your main repo
	// The additional repos are cloned inside /workspace dir
	"folders": [
		{
			"path": "." // Main repo that you will open in Gitpod (e.g. frontend)
		},
		{
			"path": "../backend" // Additional repo
		},
		{
			"path": "../db" // Additional repo
		}
	]
}

Specify your .code-workspace file path on .gitpod.yml:

yml

workspaceLocation: frontend/main.code-workspace # Relative to /workspace dir

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:

yml

tasks:
    - name: Multi branch
      before: |
          # Get primary repo dir path and name
          main_repo_dir="${GITPOD_REPO_ROOT}"
          primary_repo_name="${main_repo_dir##*/}"

          # Array for BRANCH name(s).
          extra_clone_branches=(
              backend
              docs
              next
          )

          for reference in "${extra_clone_branches[@]}"; do {
              dir="${main_repo_dir}-${reference}"

              if test ! -e "${dir}" && git -C "${main_repo_dir}" show-ref --quiet "refs/heads/${reference}"; then {
                printf 'INFO: %s\n' "Duplicating ${primary_repo_name} to ${dir} with ${reference} branch"
                cp -ra "${main_repo_dir}" "${dir}"
                git -C "${dir}" checkout "${reference}" 2>&1 | grep -v "Switched to branch '${reference}'"
              } fi
          } done

          # Send signal to awaiting task(s)
          gp sync-done multi_branch

    - name: Some other task
      command: |
          # Wait for multi_branch to avoid race condition
          gp sync-await multi_branch

          echo hello
          true 'something'