Guides

Repos

A novem repo is a git repository that novem builds into a runnable image — the building block you reference from jobs to run your own code on the platform.

AI assisted, human approved — novem uses AI to review and keep our documentation up to date.

A repo is a git repository hosted on novem. You push code to it like any other git remote, and novem builds that code into a container image. That image is what a job runs — repos hold the code, jobs orchestrate and run it.

Impatient? Jump to the quick start.

Every repo has a config/type. Repos default to the job type, which tells novem to build each push into a chain-runnable image and publish it to your private novem registry under a canonical reference:

@<your_username>/<repo_name>:latest

Each pushed branch and tag becomes a label on the image, with latest tracking your default branch. A job references this image by name when it builds a chain.

Note: The build runs on every push, driven by the repo's config/type. The default job type is set for you at creation, so a fresh repo builds on its very first push.

If you only want to host a git repository — no image, no build — set config/type to code. Pushes are stored and browsable just like a job repo, but novem skips building an image entirely, so there is nothing for a chain to reference. This makes a repo suitable for plain git hosting.

novem --post /code/repos/data_fetcher/config/type code

A job repo is built into a container image on every push. How that image is produced depends on whether you ship a Dockerfile.

If your repo has no Dockerfile, novem inspects the contents and generates one for you. Today's heuristics cover the common Python case:

  • A single .py file in the repo root → a minimal image that runs it.
  • A single .py file plus a requirements.txt → the same, with your dependencies pip-installed first.

The generated Dockerfile is roughly equivalent to:

FROM python:3-slim
COPY . /app
WORKDIR /app
# only when requirements.txt is present:
RUN pip3 install -r requirements.txt
ENTRYPOINT ["python3", "/app/main.py"]

The repo's log records which heuristic ran (e.g. python_single_file_with_requirements), so you can confirm what novem detected.

For anything beyond the simple cases — another language, system packages, a build step — add a Dockerfile to the repo root and novem uses it as-is. There is no required base image or layout.

Prefer ENTRYPOINT over CMD. When novem runs your image it appends two arguments — the paths /input and /output (see how a job runs). With ENTRYPOINT those arguments are passed to your program. With CMD, Docker replaces your command with the appended arguments, so your program never runs. Don't hardcode /input / /output into the ENTRYPOINT either — they arrive as arguments at run time.

Like other novem resources, a repo is a hierarchical folder structure. Below is an illustrative example.

data_fetcher              => Repo name
├── config                => Configuration options
│   ├── type              => Build type (job)
│   └── branch
│       └── default       => Default branch (main)
├── url                   => Git clone URL
├── files                 => Browse the repo's files
├── branches              => Branches
├── commits               => Commit history
├── log                   => Build log
├── description           => Description (meta)
├── name                  => Name (meta)
├── shortname             => Auto-generated short id
└── shared                => Who can view / use the repo
    ├── +org~group        => Shared with an org group
    ├── @username~group   => Shared with a user group
    └── public            => Shared with everyone

A repo is created with an HTTP PUT to the https://api.novem.io/v1/code/repos/REPO_NAME endpoint — from our web app, or from the command line. The CLI has no dedicated repo flag, but its raw HTTP interface (--get, --post, --put) can target any API path directly — the path is everything after /v1/.

novem --put /code/repos/data_fetcher

New repos come up as the job type, so there is usually nothing more to configure before your first push.

novem speaks plain git over both SSH and HTTPS. To push over SSH, register a public key on your profile once. Keys live under your profile, not the repo, so a single key works for all of your repos.

PUT/admin/keys/laptop
POST/admin/keys/laptop/key
ssh-ed25519 AAAAC3NzaC1lZDI1... you@laptop

Clone, commit and push with the git tooling you already use. Your repo's clone URL is published at its url path (/code/repos/<repo>/url).

# authenticate as the git user with your novem token
git clone https://x-token:$NOVEM_TOKEN@novem.io/u/<your_username>/r/data_fetcher.git
cd data_fetcher

# add your code, then push — this triggers a build
git add main.py
git commit -m "initial commit"
git push origin main

Each push builds the commit into @<your_username>/data_fetcher:latest. Follow the build on the repo's log, and once it completes the image is ready to be referenced from a job.

  • Repo quick start — create, push and build your first repo end to end.
  • Jobs — run your built image, alone or as a chain.
Next
Jobs