mintlify__docs/deploy/multi-repo.mdx

---
title: "Multi-repository deployments"
description: "Combine multiple Git repositories into one Mintlify site, with a dedicated URL path for each source repo's content and navigation."
keywords: ["multi-repo", "multiple repositories", "git sources", "url path"]
---

<Info>
  Multi-repository deployments are available on [Enterprise plans](https://mintlify.com/pricing?ref=multi-repo).
</Info>

Use a multi-repository deployment when one site needs content from more than one Git repository. When you configure multiple repositories as sources for the same Mintlify project, content from each repository has its own URL path.

For example, you can combine separate repositories for product documentation, API reference, and SDK guides into one site:

```text
docs.example.com/product
docs.example.com/api
docs.example.com/sdks
```

## How multi-repository deployments work

Each repository in a multi-repository deployment has its own:

- Git provider connection
- Branch
- Optional content directory
- URL path
- `docs.json`

During deployment, Mintlify reads each repository and combines the configured sources into one site. Each source appears under its configured URL path.

The first configured repository's `docs.json` is the root `docs.json` for the deployment. Its site-level configuration controls the combined site, including settings such as theme, colors, logo, integrations, SEO, and other top-level fields. The other sources contribute their navigation and content under their configured URL paths.

<Note>
  Multi-repository deployments are different from a [monorepo setup](/deploy/monorepo). Use a monorepo setup when you store all content in a subdirectory alongside source code in a single repository. Use multi-repository deployments when you store content across separate repositories.
</Note>

## Requirements

- An Enterprise plan
- Admin access to your Mintlify project
- A `docs.json` file in each repository source
- All repository sources must use the same Git provider (all GitHub or all GitLab). Adding a source from a different provider removes all existing sources of the other type

<Warning>
  URL paths must be unique and cannot overlap. For example, do not configure one source at `/docs` and another source at `/docs/api`.
</Warning>

## Configure multiple repositories

<Steps>
  <Step title="Open Git settings">
    Navigate to [Git settings](https://app.mintlify.com/settings/deployment/git-settings) in your dashboard.

    <Frame>
    <img src="/images/deployments/add-repository-light.png" alt="The Git settings page in the Mintlify dashboard. The Add repository button is visible at the bottom." className="block dark:hidden" />
    <img src="/images/deployments/add-repository-dark.png" alt="The Git settings page in the Mintlify dashboard. The Add repository button is visible at the bottom." className="hidden dark:block" />
    </Frame>
  </Step>

  <Step title="Add another repository">
    Click **Add repository**.
  </Step>

  <Step title="Configure the repository source">
    Select the repository, branch, and any required Git provider-specific fields (GitHub or GitLab).
    
    <Frame>
    <img src="/images/deployments/repo-configuration-light.png" alt="The repository configuration panel in the Git settings page. The repository, branch, and GitHub-specific fields are visible." className="block dark:hidden" />
    <img src="/images/deployments/repo-configuration-dark.png" alt="The repository configuration panel in the Git settings page. The repository, branch, and GitHub-specific fields are visible." className="hidden dark:block" />
    </Frame>

    For GitHub sources, the Mintlify GitHub App must have access to the repository. For GitLab sources, provide the project ID and a deploy token with `read_repository` scope.

    If the repository's `docs.json` is in a subdirectory rather than the root, enable **docs.json is in a subdirectory** and enter the path to that directory.
  </Step>

  <Step title="Set the URL path">
    Enter a **URL path** for the repository source.

    The URL path determines where the content from that repository appears on your docs site. For example, a URL path of `api` serves the content under `docs.example.com/api`.

    <Note>
      You can enter the path with or without leading slashes. Mintlify normalizes the value when you save.
    </Note>
  </Step>

  <Step title="Save changes">
    Click **Save changes**. Mintlify saves the configuration and queues a deployment of the combined site.
  </Step>
</Steps>

## Example repository layout

In this example, each source has its own repository and its own `docs.json`.

```text
acme/product-docs
├── docs.json
├── overview.mdx
└── guides/

acme/api-docs
├── docs.json
├── introduction.mdx
└── reference/

acme/sdk-docs
├── docs.json
├── quickstart.mdx
└── javascript/
```

Configure each repository with a URL path:

| Repository | URL path | Published path |
| --- | --- | --- |
| `acme/product-docs` | `product` | `/product` |
| `acme/api-docs` | `api` | `/api` |
| `acme/sdk-docs` | `sdks` | `/sdks` |

## Navigation behavior

Mintlify combines the navigation from each repository into one site navigation. Each repository source becomes a top-level product section under the configured URL path.

The name of each product section comes from the `name` field in the corresponding repository's `docs.json`. For example, if a repository's `docs.json` sets `"name": "API Reference"`, its product section appears as "API Reference" in the combined navigation.

Keep each source's navigation scoped to that repository. For example, pages in the API repository should reference only files that live in the API repository, and pages in the SDK repository should reference only files that live in the SDK repository.

Nested `navigation.products` configurations are not supported inside individual source repositories.

## Removing a repository source

You can remove a repository source from the [Git settings page](https://app.mintlify.com/settings/deployment/git-settings) in your dashboard. When only one repository source remains, Mintlify removes the source URL path and treats the remaining repository as the root source for the deployment.