# Repositories

> Cordium documentation. Canonical page: <https://octelium.com/docs/cordium/latest/workspaces/repositories>.

A *Workspace* can clone a primary git repository as well as any number of additional repositories when it is initialized. Repositories are cloned on fresh runs only (i.e. the first run of a persistent *Workspace* and every run of an ephemeral one), and they are part of the *Workspace*'s persistent storage afterwards.

## Primary Repository

The `spec.repository` field defines the primary repository, which is cloned into `/workspace/repo`. Only HTTPS URLs are supported:

```yaml
spec:
  repository:
    url: https://github.com/acme-corp/payments-api
    cloneOptions:
      branch: main
```

Here are all the clone options:

| Field                  | Description                                                                              |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| `branch`               | The branch to clone. Defaults to the repository's default branch.                        |
| `checkout`             | A commit or a tag to check out after cloning.                                            |
| `singleBranch`         | Fetches the chosen branch only.                                                          |
| `shallowSubmodules`    | Clones the submodules with a depth of 1.                                                 |
| `disableLazyUnshallow` | Disables Cordium's default lazy unshallowing (see below).                                |
| `depth`                | The number of commits to fetch. It is only effective when `disableLazyUnshallow` is set. |

By default, Cordium performs a shallow clone at initialization time for a fast startup, and then fetches the full history asynchronously in the background, which means that `git log`, `git blame` and branch operations work normally a few moments after the *Workspace* starts. For CI runs and AI agent runs that only need the latest commit, disable the background fetch and keep a shallow clone:

```yaml
spec:
  repository:
    url: https://github.com/acme-corp/monorepo
    cloneOptions:
      branch: main
      singleBranch: true
      depth: 1
      disableLazyUnshallow: true
```

You can also set the repository via the CLI flags:

```bash
cordium run --repository https://github.com/acme-corp/payments-api --branch develop
cordium run --repository https://github.com/acme-corp/payments-api --checkout v2.18.3
```

## Private Repositories

There are two ways to clone private repositories:

**Via a *GitProvider***, which is the recommended way for interactive *Users*. Once a *GitProvider* (e.g. a GitHub or GitLab OAuth2 application) is attached to the *Workspace*'s *Template*, each *User* signs in to the git hosting service with their own account from the *Workspace*'s page in the web portal, and their OAuth2 token is automatically used to clone, pull and push without any further configuration (read more [here](https://octelium.com/docs/cordium/latest/workspaces/secrets.md#gitproviders)):

```yaml
spec:
  gitProvider: github.payments.cordium
  repository:
    url: https://github.com/acme-corp/payments-api
```

**Via HTTP basic authentication** with a *Secret* of the *Workspace*'s *Space*, which is typically a personal access token, a deploy token or a GitHub App installation token. The *Secret* is referred to by its full name:

```yaml
spec:
  repository:
    url: https://github.com/acme-corp/payments-api
    authentication:
      http:
        username: x-access-token
        password:
          fromSecret: github-token.payments.cordium
```

> **Note:**
>
> In both cases, the token is available to the processes running inside the *Workspace* through git (e.g. via `git credential fill`), which is what allows them to pull and push. If the *Workspace* runs untrusted code or AI agents and only needs read access, prefer a read-only, repository-scoped token. Alternatively, you can expose your git host as an Octelium *Service* and keep the token entirely out of the *Workspace* via secretless access (read more [here](https://octelium.com/docs/cordium/latest/examples/ai/claude-code.md)).

## Additional Repositories

You can clone additional repositories alongside the primary one. Each additional repository has a unique name and is cloned into `/workspace/additional-repos/<NAME>`. The additional repositories support the same clone options and authentication as the primary one:

```yaml
spec:
  repository:
    url: https://github.com/acme-corp/payments-api
  additionalRepositories:
    - name: shared-libs
      repository:
        url: https://github.com/acme-corp/shared-libs
        cloneOptions:
          branch: main
    - name: k8s-config
      repository:
        url: https://github.com/acme-corp/k8s-config
        authentication:
          http:
            username: x-access-token
            password:
              fromSecret: config-repo-token.payments.cordium
```

Or via the CLI:

```bash
cordium run --repository https://github.com/acme-corp/payments-api \
  --additional-repo shared-libs=https://github.com/acme-corp/shared-libs \
  --additional-repo proto=https://github.com/acme-corp/proto-defs
```

## Parameterized Repositories

The repository URL supports [variables](https://octelium.com/docs/cordium/latest/workspaces/overview.md#variables), which makes it easy to reuse a single *Template* for several repositories. Since the URL is validated before the variables are substituted, write the variable without spaces. The branch or commit to work on can be parameterized via an `ON_CREATE` task that checks it out. Here is an example:

```yaml
spec:
  vars:
    - name: REPO
      value: acme-corp/payments-api
    - name: REF
      value: main
  repository:
    url: https://github.com/${{vars.REPO}}
  runtime:
    tasks:
      - name: checkout
        type: ON_CREATE
        workingDir: /workspace/repo
        onFailure: ON_FAILURE_ABORT
        run: git fetch -q origin "${{ vars.REF }}" && git checkout -q FETCH_HEAD
```

```bash
cordium run --template review.payments.cordium --var REPO=acme-corp/ledger --var REF=fix/rounding
```

## Repository Configuration Files

After cloning the primary repository, Cordium merges any `.cordium/workspace.yaml`, `.cordium/workspace.yml`, `.cordium.yaml` or `.cordium.yml` file found at its root into the *Workspace*'s configuration, and uses its devcontainer spec if the image is built from the repository (read more [here](https://octelium.com/docs/cordium/latest/workspaces/overview.md#repository-configuration-files) and [here](https://octelium.com/docs/cordium/latest/workspaces/image.md#devcontainers)).