Your first build

Goal: submit a build, watch the logs, get the artifacts back.

Before you start

Two things:

  • An account. Sign the CLI in signs the CLI in with your Gitea or GitHub account, so the build lands in a project of yours.

  • A runner. saggar.dev builds nothing itself; a job with no eligible runner stays queued. Pair your own runners pairs a machine in a few minutes.

1. Submit

Point saggar submit at any source: a git URL or a local tree.

$ saggar submit https://github.com/me/my-project
$ saggar submit ./my-project            # a directory with a Dockerfile
$ saggar submit ./my-project.tar.gz     # or a tarball

What the tree is decides what gets built, with no build script required:

  • A .debian/ or debian/ directory builds a .deb (the changelog’s series decides the environment).

  • A Dockerfile builds an image.

  • snapcraft.yaml builds a snap, a flatpak manifest a flatpak bundle, a root *.spec rpms, appimagebuilder.yml an AppImage.

  • CMakeLists.txt, meson.build, Cargo.toml, go.mod, Makefile and friends get a native build. It answers whether the tree compiles; what the build produces is collected, and a green compile with nothing to collect is a build-check success.

The CLI follows the build: live log in the terminal, then the verdict.

Overrides for this push: --format deb (skip detection), --arch arm64 or --env "debian:12 + rust" (target override), --project web (which of your projects owns the build).

2. Follow the logs

The follow loop already streams the log. For an existing job, the full log is one command:

$ saggar logs j-567bf3b889d9bb70

If you submitted with --no-wait (or you are scripting and passed --quiet, which prints only the id), poll the job and stream in your browser or via the SSE endpoint (see The management API).

When a build fails, the failure is classified: real is a genuine defect in your code or packaging; infra-retryable is environment noise (retried silently, you never see it); infra-permanent is a fault no retry fixes. saggar logs and the API’s failure metadata tell you which.

3. Download the artifacts

$ saggar download j-567bf3b889d9bb70 --extract -o out/

Job downloads default to this machine’s arch; --arch riscv64 fetches another target, and arch-independent (all) artifacts always come along. --extract unpacks tarballs preserving executable bits. For a fan-out group, everything at once:

$ saggar download --group g-1a2b3c4d -o out/

Next steps