Git

Velrix runs your Git server as an app: Forgejo, from the Library. Git servers then connects it to the realm, so people sign in with their Velrix accounts, CI runs as Velrix jobs, and a push deploys your apps.

Set it up

1. In the Library, deploy Forgejo. It gets a volume for its repositories, backed up with your other volumes. Give it a hostname under a domain you have proved.
2. Open Git servers and choose Connect a Git server. Pick the app; the address is its first hostname. Sign-in, the CI runner and the webhook are set up for you.
3. Once it says ready, people sign in to Forgejo with Velrix. For an organisation’s server, its members join a members team with write access to every repository, and its admins the Owners team, kept in step at every sign-in.

Sync sets it all up again; Edit takes a new name or address and keeps the rules.

A Forgejo you already run, made by hand, can be connected too: give an access token of one of its admins instead. Sign-in then stays Forgejo’s own; CI and deploys work the same.

SSH

HTTPS clone and push work through the app’s hostname. For Git over SSH, put a load balancer with a TCP port onto the container’s port 2222 in front of the app (Floating IPs and load balancers). The server’s page then shows the SSH address.

CI

Each workflow job runs as a Velrix job, in a sandbox of its own, and its output reaches Forgejo while it runs. runs-on picks the kind:

• the default label: a container;
• velrix-vm: a microVM of its own, with its own kernel;
• velrix-builder: builds images with buildah.

run steps and checkout work. Other actions, if:, matrices and services do not: such a job fails at once with one line saying why. A job may ask for cores, memory, disk and time, within your organisation’s job limits.

A build job gets a registry key for that run alone, able to push only to the repositories its commit’s deploy rules name and their build cache. Any other job, and a pull request from a fork, gets a key that can only pull. The run finds them as VELRIX_REGISTRY, VELRIX_REGISTRY_USER, VELRIX_REGISTRY_PASSWORD, VELRIX_IMAGE and VELRIX_BUILD_CACHE. Layers are kept in the registry between runs, so a build whose dependencies have not changed reuses them (Registry).

CI runs on the server’s page lists recent runs: each step with its time, the image build’s steps with the cached ones marked, and the pushed image’s digest and size.

Deploys

A deploy rule says: a push to this branch of this repository deploys this image to this app. The image name may use {sha}, {short} or {branch}. On the app, the same rule shows as Settings › Source:

• Deploys when pushed: off keeps the rule and builds, and deploys nothing.
• Wait for CI: deploy once the commit’s image build passed, not on the push itself.

Settings › Build holds the Containerfile’s path and build-time variables, sealed and handed to the CI build as $VELRIX_BUILD_ARGS.

Each deploy is a revision like any other, rolled out without downtime and rolled back if it fails, with the commit, its author and the CI run on its page (Apps).

velrix.json

An app can carry its build and deploy settings in its repository, as velrix.json (or velrix.toml) at the root. Every deploy reads the file at the deployed commit, and what it sets wins: those fields read Set in velrix.json in the app’s Settings. A commit without the file hands them back to Settings. The Details of any revision shows its settings as this file, to copy.

{
  "build": { "containerfile": "deploy/Containerfile", "args": ["API_BASE_URL"] },
  "deploy": {
    "command": "bun run start",
    "healthcheck": { "path": "/healthz" },
    "warmPaths": ["/", "/pricing"],
    "replicas": 2,
    "size": "g.medium",
    "restart": { "policy": "on-failure", "maxRetries": 5 }
  },
  "networking": { "hostnames": ["www.example.se"] }
}

• build.args names build-time variables; their values stay sealed in Settings › Build.
• deploy.warmPaths: pages asked on each new copy before it gets visitors (Apps).
• deploy.size names a catalogue size; or give deploy.memoryMib and deploy.cpuCores.
• networking.hostnames is taken only when Settings › Source › velrix.json may set hostnames is on, since it changes routing.

Unknown keys and wrong values are refused by name: the commit’s CI run fails with a line such as velrix.json: unknown key deploy.replica, and nothing deploys. The full JSON Schema is in your realm’s Docs window, to save beside the file so your editor checks it too.