> For the complete documentation index, see [llms.txt](https://docs.valohai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.valohai.com/git-integration/multi-repository-projects.md).

# Multi-Repository Projects

A Valohai project can connect to more than one Git repository. Every project has one **default repository**. You can add **named repositories** next to it, for example `ml-models` or `data-pipeline`, and run steps from any of them in the same project.

Use this when one workflow's code is split across several repositories. For example, a pipeline might run data preparation from one repository and training from another.

> 💡 *Before this feature you needed a separate project for each repository.*

### Concepts <a href="#concepts" id="concepts"></a>

A project has exactly one default repository and any number of named repositories. Each repository has its own URL, branch (`ref`), `valohai.yaml` path, private key, and Git LFS setting.

> :bulb: Even if there is no limit for the number of named repositories, you should only add those that are needed in the project. Each fetch fetches every repository in the project, and the repository selectors list them all, so a project with many repositories will have slower fetches.

|                           | Default Repository          | Named Repository                                          |
| ------------------------- | --------------------------- | --------------------------------------------------------- |
| **Name**                  | None                        | Required, unique within the project                       |
| **How many**              | Exactly one                 | Any number                                                |
| **Commit reference**      | `main`, `latest`, `a1b2c3d` | `ml-models:main`, `ml-models:latest`, `ml-models:a1b2c3d` |
| **Can be renamed**        | No                          | Yes                                                       |
| **Can be deleted**        | No                          | Yes, if none of its commits have been used in executions  |
| **GitHub App linking**    | Yes                         | No, will be added later                                   |
| **Usable in deployments** | Yes                         | Yes                                                       |

#### Referring to Commits <a href="#referring-to-commits" id="referring-to-commits"></a>

A commit in a named repository is written `<repository name>:<selector>`. A commit in the default repository is written with the selector only, as before. The selector can be:

* a commit SHA, or the start of one
* a branch or tag name, such as `main`
* `latest`, the newest commit on any branch, not counting ad-hoc or hidden commits

**Example:** `ml-models:main` is the newest fetched commit on `main` in the `ml-models` repository.

#### Repository Names <a href="#repository-names" id="repository-names"></a>

Names must be lowercase, start with a letter or digit, and contain only letters, digits, dashes, and underscores. These names are not allowed:

* **Reserved names:** `head`, `latest`, `library`, `main`, `master`
* **Hex-only names:** names made only of hex characters, such as `cafe` or `0123`, because they look like commit IDs

### Managing Repositories <a href="#managing-repositories" id="managing-repositories"></a>

You manage repositories under **Project settings → Repositories**.

#### Add a Named Repository <a href="#add-a-named-repository" id="add-a-named-repository"></a>

> **Set up the default repository first.** A project can't have named repositories without one.

1. Click **Add repository**.
2. Enter a **Name**. This is the name you use in `valohai.yaml` and commit references, for example `ml-models`.
3. Enter the URL, branch, `valohai.yaml` path, and a private key if needed, as you would for the default repository.
4. Save. Then fetch the project to load the repository's commits.

#### Switch Between Repositories <a href="#switch-between-repositories" id="switch-between-repositories"></a>

When a project has named repositories, the settings page shows a repository selector. **Default** is always listed first. **View commits** opens the commit list for the selected repository.

<figure><img src="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2FdLhJtyHfZSymfdralbTD%2Fimage.png?alt=media&amp;token=20d45dc0-1e32-4cf1-941d-24992cef506c" alt=""><figcaption></figcaption></figure>

#### Rename or Delete a Named Repository <a href="#rename-or-delete-a-named-repository" id="rename-or-delete-a-named-repository"></a>

* **Rename:** change the **Name** field and save. Existing references such as `old-name:main` in `valohai.yaml`, triggers, or saved pipelines don't update automatically.
* **Delete:** click **Delete repository**.

> **Deletion is blocked once a repository's commits have been used.** Valohai blocks the deletion once any execution, pipeline, or other run has used one of the repository's commits. You can only delete a named repository whose commits have never been used.

#### Default Repository Rules <a href="#default-repository-rules" id="default-repository-rules"></a>

The default repository can't be renamed, deleted, and you can't change a named repository into a new default repository by for example renaming it as default. To point the default repository at different repository, you will need to change its URL and likely also the authentication keys.

### Running Work from a Named Repository <a href="#running-work-from-a-named-repository" id="running-work-from-a-named-repository"></a>

Anywhere you choose a commit, you can choose one from a named repository with a `name:selector` reference. Each step is read from the `valohai.yaml` of the commit you pick.

#### Fetching <a href="#fetching" id="fetching"></a>

**Fetch** loads new commits from every repository in the project: first the default, then the named ones in alphabetical order. If you close the modal or choose "**Continue in background**", fetching the repositories will continue until it has fetched all new commits from all repositories configured for the project or the fetching fails.

<figure><img src="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2FpA49TM4sO7CufYefhebp%2Fimage.png?alt=media&amp;token=0e780f5c-34e7-4847-9078-37a4dcbe98f1" alt=""><figcaption></figcaption></figure>

Errors from a named repository start with its name, for example `ml-models: authentication failed`.

#### Executions, Tasks, and Notebooks <a href="#executions-tasks-and-notebooks" id="executions-tasks-and-notebooks"></a>

In the create view, a **Repository** selector appears above the commit selector when the project has more than one repository. Changing the repository clears the selected commit, step, and configuration.

> **Copying an execution keeps its repository.** If that repository has been deleted, the copy shows "Failed to resolve the repository for the copied commit" instead of switching to the default repository.

<figure><img src="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2F4L0hkVgfZqQBrkMSGJ6b%2Fimage.png?alt=media&amp;token=0fdc208d-3601-4dba-8628-192e9e8dd438" alt=""><figcaption></figcaption></figure>

#### Pipelines <a href="#pipelines" id="pipelines"></a>

In `valohai.yaml`, set `commit` on a node to run it from a named repository. Nodes without `commit` use the commit the pipeline was started from.

```yaml
- pipeline:
    name: prepare-and-train
    nodes:
      - name: prepare
        type: execution
        step: prepare-data
      - name: train
        type: execution
        step: train-model
        commit: ml-models:main
    edges:
      - [prepare.output.*, train.input.dataset]
```

When the pipeline is created, a branch reference like `ml-models:main` is pinned to the exact commit, for example `ml-models:4f2a9c1`. Reruns use the same code.

> :bulb: Note that when running `vh lint` to check that your `valohai.yaml` is valid, any errors in the names for the named repositories or step names will not be validated. The linting applies only to the repository from where you run the command and the YAML file in it.

#### Triggers <a href="#triggers" id="triggers"></a>

* **Fetch repository** action: set **Repository** to a name to fetch only that repository. Leave it empty to fetch the default repository.
* **Run execution** and **Run pipeline** actions: the commit field accepts `name:selector` references.

<figure><img src="https://4109720758-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ff3mjTRQNkASbnMbJqzJ2%2Fuploads%2FkfIyshppEvwMaOHFjdZz%2Fimage.png?alt=media&amp;token=44ab157e-305b-494c-a802-a89e28fae208" alt=""><figcaption></figcaption></figure>

#### Ad-hoc Executions <a href="#ad-hoc-executions" id="ad-hoc-executions"></a>

Ad-hoc code uploads (`vh execution run --adhoc`) use the repository you run the command from. Run it from a named repository's code and the job uses that repository.

#### Validation Errors <a href="#validation-errors" id="validation-errors"></a>

| Case                                                               | Code              | Message                                                                                               |
| ------------------------------------------------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------- |
| **Invalid or reserved name**                                       | `invalid`         | "{name} is a reserved repository name." and similar                                                   |
| **Duplicate name**                                                 | `unique`          | "This project already has a repository by this name."                                                 |
| **No default repository yet**                                      | `invalid`         | "This project needs a default repository before it can have named ones."                              |
| **Renaming the default, or making a named repository the default** | `invalid`         | "A project's default repository can not be named, and a named repository can not become the default." |
| **Deleting the default**                                           | `can_not_delete`  | "A project's default repository can not be deleted."                                                  |
| **Deleting a repository whose commits are in use**                 | `resource_in_use` | "This repository has commits that are still in use, so it can not be deleted."                        |

### Good to Know <a href="#good-to-know" id="good-to-know"></a>

* **Renaming a repository:** existing references to the old name don't update automatically. Update `valohai.yaml`, triggers, and saved pipeline configurations yourself.
* **Copying a project:** all its repositories are copied, but the Git LFS setting isn't. Turn it on again in the copy if you need it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.valohai.com/git-integration/multi-repository-projects.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
