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:

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:

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:

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):

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:

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).

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:

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:

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, 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:

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

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 and here).