Skip to content
zoryn/ maintainer-assistant

zoryn submit

Full build cycle: commit, tag, push, and submit for build — all in one command.

Synopsis

zoryn submit [-B repo] [--with spec] [--replace[=TASK_ID[:N]]]
             [--run] [--no-run] [--test-only] [--commit]
             [--dry-run] [--skip-check] [--batch-pkgs=PKGS]
             [--allow-overwrite-tag] [-d]

By default, creates a task but does not run it (test-only mode). Use --run to start the build, and --commit to publish instead of test-only. Default behaviour can be configured in ~/.zoryn under [submit]:

[submit]
run = true
test_only = false

If the previous commit has the same version-release subject (e.g. after re-running submit), the commits are automatically squashed into one.

With -B, submits to the specified repository and automatically adds dependencies on tasks from fresher repositories. Multiple repositories can be specified as a comma-separated list (e.g. sisyphus,p11) — each subsequent submit depends on the previous task.

Options

  • -B, --branch <repo> — target repository (default: sisyphus), supports TAB completion.
  • --with <spec> — add to existing task with subtask positioning. Syntax:
    • PKG — find task, append to end.
    • ^PKG — find task, place before PKG.
    • PKG: — find task, place after PKG.
    • TASK_ID — append to task.
    • TASK_ID:REF — after REF.
    • TASK_ID^REF — before REF.
    • PKG is a package name or pkg.git=tag (finds the task containing that exact subtask — useful when several tasks carry the same package).
    • REF is a package name, subtask number, or pkg.git=tag.
    • If the same tag already exists in the task, auto-replaces. If the package exists with a different tag, prompts for action.
  • --replace[=TASK_ID[:N]] — replace subtask in an existing task. Without argument: auto-finds the task and subtask by current package (with interactive confirmation). With TASK_ID: replaces in specified task. With TASK_ID:N: also specifies the subtask number. With multi-branch -B sisyphus,p11 and no TASK_ID, auto-search runs once per branch and replaces in each branch's task; --replace=TASK_ID is single-target and cannot be combined with multiple branches.
  • --run — run the task after creating/modifying.
  • -n, --no-run — don't run the task (override config).
  • --test-only — mark the task as test-only (don't publish).
  • --commit — mark the task for publishing (opposite of --test-only).
  • --dry-run — preview all actions without executing.
  • --skip-check — skip spec file validation (see zoryn check spec).
  • --batch-pkgs=PKGS — submit only specified batch values (comma-separated) instead of all values from [batch].
  • --allow-overwrite-tag — force-recreate an existing local tag, bypassing the gears/ancestor safety checks.

Tag overwrite safety

By default submit refuses to overwrite an existing local tag that points to a different commit if either of these is true:

  • the tag is already published in git.altlinux.org/gears/<X>/<pkg>.git (immutable build history), or
  • the tag commit is not an ancestor of HEAD (likely belongs to a different ALT branch tracked in another git branch).

In the first case, bump the release (e.g. alt0.c10f2.2). In the second, switch to the right branch or delete the local tag manually if you are sure. The flag --allow-overwrite-tag skips both checks for cases you know are safe (e.g. cleaning up a stale tag left from an aborted attempt).

Brand-new packages exception. When the gears repository is provably missing (ls-remote fails with exit 128 — repository not found) and the package is unknown to RDB (never built in Sisyphus), the ancestor check is bypassed automatically and the local tag is recreated with a warning. The reasoning: no remote consumer can exist yet, so any pre-existing local tag is by construction stale from a previous local attempt.

--replace implies --allow-overwrite-tag. Replacing an in-progress subtask after git commit --amend or git rebase legitimately moves the tag to a new commit. submit --replace enables overwrite automatically and prints a dim notice when it does. The gears-immutability check still runs (a published task in gears would have already left --replace's search results, since task ls only lists open tasks).

task batch --refresh always overwrites the local tag (that is the whole point of refresh), so --allow-overwrite-tag is only relevant on non-refresh submits.

Kernel modules

When run inside a kernel-module template repo, zoryn submit automatically detects the template layout and creates per-flavour specsubst tags — replacing the manual km-create-tag workflow from kernel-build-tools.

Detection — all three conditions must hold:

  • The current git branch matches template/<module>/<dist> (e.g. template/zfs/sisyphus).
  • .gear/rules declares specsubst: kflavour karch.
  • A kernel-modules-<module>.spec file exists in the repo root.

When detected, submit creates one tag per kernel flavour named <dist>/kernel-modules-<module>-<flavour>-<version>-<release>. Each tag carries two specsubst headers:

X-gear-specsubst: kflavour=<flavour>
X-gear-specsubst: karch=<karch>

karch (the arches the module is built for) is resolved as: an explicit .gear/km-karch glob match, else the arches the kernel itself is built for (from Repoteka — so a module is never built on an arch where its kernel doesn't exist), else the default %ix86 x86_64 aarch64. The NVR comes from gear --describe.

Flavour sources

Flavours are resolved from the first non-empty source:

  1. -k / --kernel FLAVOUR — explicit list. Repeatable and comma-separated: -k std-def,un-def or -k std-def -k un-def. TAB-completes from Repoteka kernel-image-* source packages.
  2. .gear/kflavours file — one flavour per line, # comments ignored.
  3. The module's existing builds — flavours for which a kernel-modules-<module>-<flavour> binary already exists in the target branch. This is the default: submit rebuilds only the kernels the module is already shipped for, not every kernel-image-*. If the module has no existing builds, you must pass -k.

Kernel module options

  • -k, --kernel <FLAVOUR> — build for this flavour (repeatable and comma-separated, TAB-completes from Repoteka).
  • --no-kernel-module — disable autodetection even when the template layout is present.
  • --dry-run — print the predicted tag names without creating them.

All flavour tags become subtasks of a single build task, the same as batch submit.

--with <spec> adds every flavour tag to an existing task (e.g. the kernel's own task): zoryn submit -k std-def -k un-def --with zfs.

--replace is also supported: each new flavour tag replaces the subtask in the target task that holds the same flavour (and adds one if that flavour has no build yet), leaving other flavours untouched. This per-value replace is shared with batch specsubst submits (a repo with several tags). --batch-pkgs is not used in kernel-module mode.

# inside a kernel-modules template repo, on branch template/zfs/sisyphus
zoryn submit -k std-def -k un-def

# add the module rebuilds to the task that already contains zfs
zoryn submit -k std-def -k un-def --with zfs

# preview without creating tags
zoryn submit --dry-run

Kernel images

The kernel itself is detected too: a repo whose .gear/rules declares specsubst: kflavour (without karch) and whose spec Name: contains the @kflavour@ placeholder (e.g. Name: kernel-image-@kflavour@). Without this mode, gear-create-tag fails with specsubst variable "kflavour" is not defined in the tag message.

submit creates one tag per flavour named kernel-image-<flavour>-<version>-<release> carrying X-gear-specsubst: kflavour=<flavour> — the same format as the official kernel-image-* gears. Version and Release come from the spec.

The flavour is resolved from the first non-empty source:

  1. -k / --kernel FLAVOUR — explicit, repeatable and comma-separated.
  2. kflavour in the [specsubst] section of .gear/version-up (comma-separated).
  3. The branch's <flavour>/<dist> prefix — recognised only when <dist> is a known ALT branch, so a topic branch like fix/typo never becomes a flavour. On branch for-vm/sisyphus the flavour is for-vm, and the <dist> part becomes the default -B target.

--no-kernel-module disables this autodetection as well, and an explicit [batch] config with values in .gear/version-up takes precedence over it (the repo is then submitted through the batch specsubst path). --batch-pkgs and multi-repository -B are rejected in kernel mode. --dry-run, --with and the per-value --replace work the same as in kernel-module mode.

# on branch for-vm/sisyphus: tag kernel-image-for-vm-<ver>-<rel>, target sisyphus
zoryn submit

# explicit flavour
zoryn submit -k 6.18

# or pin it in .gear/version-up
# [specsubst]
# kflavour = "for-vm"

Examples

zoryn submit                     # create task (default: don't run, test-only)
zoryn submit --run               # create and run test build
zoryn submit --run --commit      # create and run for publishing
zoryn submit -B p11              # submit to p11, --deps on sisyphus tasks
zoryn submit -B sisyphus,p11     # submit to sisyphus first, then p11 with --deps
zoryn submit --with libva        # add to task containing libva (append to end)
zoryn submit --with ^libva       # add before libva in task
zoryn submit --with libva:       # add after libva in task
zoryn submit --with 12345        # append to task 12345
zoryn submit --with 12345^libva  # before libva in task 12345
zoryn submit --with 12345:libva  # after libva in task 12345
zoryn submit --replace           # replace subtask (auto-find with confirmation)
zoryn submit --replace --run     # replace and run
zoryn submit --replace=12345     # replace in specific task
zoryn submit --replace=12345:3   # replace specific subtask
zoryn submit --replace -B sisyphus,p11  # replace in each branch's task (one auto-search per branch)
zoryn submit --no-run            # explicitly don't run (override config)
zoryn submit --dry-run           # preview all actions

When submitting to stable branches, the build reason is detected automatically (new version, bugfix release, new package). If CVEs are found in the spec changelog between versions, the reason is marked "with security fixes".