Work on an external repository

Enterprise

Link an existing git repository as an Arena project, work on it in a branch from the dashboard, push it, and open a pull request on the host.

Prerequisites

Enterprise enabled (enterprise.enabled=true; see Install with a License).
A workspace with the Editor role, and a privacy-api (the workspace’s spec.privacy).
An https git repository, and an account on its host that can push to it.
A gitHost Connection in the workspace whose hosts include the repository’s host. A workspace Editor creates it once for everyone; each person then links their own account.

Create the Connection

A workspace Editor does this once. The install must set the chart value connections.browserSession.encryption, which the dashboard writes into the Connection as the key that seals linked credentials. Without it, the dashboard refuses to create the Connection.

For a github or gitlab provider, register an OAuth app with the host. Set its callback URL to your dashboard’s base URL (OMNIA_BASE_URL) followed by /api/git-credentials/callback; the Add connection form prints the exact URL once you select GitHub or GitLab. One URL serves every workspace and Connection.
Put the app’s client secret in a Secret in the Connection’s namespace, under the key clientSecret, or under the key that clientSecretRef.key names.
In Connections, select Add connection and select Git host. Enter a name, the host’s address, the provider and, for GitHub or GitLab, the OAuth app’s client ID, the Secret and, for GitHub Enterprise Server or a self-managed GitLab, the server address. For any other https host, select Personal access token; each person then pastes a token.

Link your account

Open Connections and find the git host’s row.
Select Link your GitHub account or Link your GitLab account and approve the app on the host, or select Add a token and paste a personal access token that can read and push the repository.
The row reads “Linked as <account>” with the time you last used it.

Every clone, pull and push you make on an external project uses this account, so the host records each commit and push as yours.

Link the repository

Open Projects and select New project.
Select Link a repository.
Enter a project name and the repository’s https:// URL.
Set the Default branch (the branch runs and deploys use when they name none) and how often Omnia checks for new commits.
For a private repository, pick a Read Secret with username and password, or token. Runs and deploys fetch with it, since they act for no one. A public repository needs none, so leave it at None. Only Secrets labelled omnia.altairalabs.ai/credential-for: git are offered, and only those are used:
Terminal window
```
kubectl -n <namespace> create secret generic evals-read --from-literal=token=<token>
kubectl -n <namespace> label secret evals-read omnia.altairalabs.ai/credential-for=git
```
Select Link repository.

Omnia creates an ArenaProject with spec.repository.external and clones the repository into your workspace. If you have no account linked on the host, the project is still created and the form asks you to link one; your copy is cloned the next time you open the project.

The equivalent resource:

apiVersion: omnia.altairalabs.ai/v1alpha1
kind: ArenaProject
metadata:
  name: evals
  namespace: team-a
spec:
  repository:
    external:
      url: https://github.com/acme/evals.git
      defaultBranch: main
      readSecretRef:
        name: evals-read

Trust a host behind a private CA

A self-hosted GitLab, Gitea or Bitbucket whose certificate is signed by your own certificate authority needs that CA named on the project. Without it, every clone, pull, push and fetch fails with x509: certificate signed by unknown authority. The dashboard’s form does not set this, so do it with kubectl:

Put the CA’s PEM certificate in a ConfigMap in the project’s namespace:
Terminal window
```
kubectl -n team-a create configmap company-git-ca --from-file=ca.crt=./company-ca.pem
```
A Secret works too, for a CA kept in one, such as a cert-manager CA Secret’s ca.crt. Use secretKeyRef in place of configMapKeyRef below.

Point the project at it:

kubectl -n team-a patch arenaproject evals --type=merge \
  -p '{"spec":{"repository":{"external":{"caBundleRef":{"configMapKeyRef":{"name":"company-git-ca","key":"ca.crt"}}}}}}'

The CA is added to the system roots, not used in their place. It applies to your own clone, pull and push, and to the controller’s polls and the fetches runs and deploys make. Nothing is restarted. The bundle is read every time the host is dialled, so to rotate the CA, update the ConfigMap; the next fetch uses it.

Work in a branch

Open the editor and select the Source control tab. Linking a repository opens the editor for you (select Open the project if the form asks you to link an account first). To return later, open the project’s page and select Edit. The page also names the repository the project lives in.
Select New branch, enter a name such as feature/tone, and select Create and switch. To work on a branch that exists on the host, pick it in Branch.
Edit files in the editor. The tab lists each changed file and its diff.
Enter a commit message and select Commit all, or tick files first to commit only those.
Select Push. The button shows how many commits it sends (Push 2).

A switch with uncommitted changes is refused: commit or discard them first. Pull shows how many commits the host has that you do not, and fast-forwards your branch to them.

Open a pull request

After a push, the tab shows Open a pull request (GitHub) or Open a merge request (GitLab). It opens the host’s page for a request from your branch into the default branch. Review and merge there; Omnia never merges.

Deploy a branch

A deploy may name only the refs in the project’s spec.deploy.allowedRefs, by default the default branch and every tag. To deploy other branches, widen the list:

kubectl -n team-a patch arenaproject evals --type=merge \
  -p '{"spec":{"deploy":{"allowedRefs":["refs/heads/main","refs/tags/**","refs/heads/feature/**"]}}}'

An evaluation run may use any pushed ref, whatever allowedRefs says.

Verify

The branch appears on the host with your commit, authored as you.
Source control shows Push 0 for the branch.
A deploy of a ref outside allowedRefs answers 403, listing the allowed refs.

Troubleshooting

”Link your `<host>` account”

No gitHost Connection covers the host, you have not linked an account under it, or the host refuses your token. Link your account again on Connections.

”the git host refused access to the repository”

Your account cannot read or push the repository. Ask for access on the host.

”diverged: merge or rebase in a sandbox or locally”

Your branch and the host’s both have new commits. Reconcile them in the builder’s sandbox or a local clone, then push.

”the canonical branch has commits this workspace lacks: pull first”

Someone pushed to the branch since your last pull. Pull, then push again.

The project stays in `Error`

Runs and deploys cannot fetch the repository. Check readSecretRef and the ArenaProject’s Ready condition.

”x509: certificate signed by unknown authority”

The host’s certificate is signed by a CA the cluster does not trust. Name that CA in the project’s caBundleRef; see Trust a host behind a private CA.

`CABundleInvalid`, or “the project’s caBundleRef cannot be used”

The ConfigMap, Secret or key that caBundleRef names does not exist in the project’s namespace, or its value holds no PEM certificate. The message names which. Omnia does not fall back to the system roots alone; fix the reference or the value, and the project fetches again.