> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-repository environments

> Work with multiple repositories in a single environment for microservices and monorepo workflows.

Some projects span multiple repositories - microservices architectures, shared libraries, or related services that need to run together. Ona lets you clone additional repositories into your environment automatically.

This is valuable for agents too. When Ona Agent needs to make coordinated changes across repositories, having them in one environment enables atomic commits and easier testing.

## Using Dev Container Configuration

The Dev Container `onCreateCommand` allows you to clone additional repositories when your environment starts. This method is particularly useful when you want to maintain the repository setup as part of your Dev Container configuration.

Add an `onCreateCommand` entry to your `.devcontainer/devcontainer.json` file:

```json theme={null}
{
  "name": "One extra repository",
  "image": "mcr.microsoft.com/devcontainers/universal:4.0.1-noble",
  "onCreateCommand": "git clone https://github.com/organization/second-repo.git /workspaces/second-repo"
}
```

For multiple repositories:

```json theme={null}
{
  "name": "Multiple repositories",
  "image": "mcr.microsoft.com/devcontainers/universal:4.0.1-noble",
  "onCreateCommand": "git clone https://github.com/organization/second-repo.git /workspaces/second-repo && git clone https://github.com/organization/third-repo.git /workspaces/third-repo"
}
```

## Using Ona Tasks and Services

Alternatively, you can use Ona's [Tasks and Services](/ona/configuration/tasks-and-services/overview) to clone additional repositories. This approach offers more flexibility and can be combined with other automation tasks.

Add a task to your `automations.yaml` file:

```yaml theme={null}
tasks:
    build:
        name: Clone additional repositories
        command: |
            git clone https://github.com/organization/second-repo.git /workspaces/second-repo
            git clone https://github.com/organization/third-repo.git /workspaces/third-repo
        triggeredBy: ['postDevcontainerStart']
```

## Best Practices

When working with multiple repositories, consider the following best practices:

* Clone repositories to `/workspaces`: Always clone additional repositories to `/workspaces/repo-name` (where `repo-name` in that example is the name of your repo). Do this to avoid git tracking issues within your main repository
* Use SSH keys or personal access tokens for authentication with private repositories
* Organize repositories in a consistent directory structure under `/workspaces`
* Configure Git identity globally to ensure consistent commits across repositories

## Working with Multiple Repositories

Once your environment is set up:

1. Navigate between repositories using the file explorer or terminal
2. Make changes in each repository independently
3. Commit and push changes to each repository separately

Example workflow:

```bash theme={null}
cd /workspaces/second-repo
# Make changes
git add .
git commit -m "Update feature X"
git push

cd /workspaces/third-repo
# Make changes
git add .
git commit -m "Fix bug Y"
git push
```

## Troubleshooting

<Accordion title="Authentication failures">
  Ensure you have the correct permissions and authentication method.
</Accordion>

<Accordion title="Path issues">
  Use absolute paths when necessary.
</Accordion>

<Accordion title="Repository not found">
  Verify repository URLs and access permissions.
</Accordion>