Actions Reference

Actions are the functions that kbuild executes on packages. Every action receives a context map containing:

  • :package — the resolved package map for the current package

  • :packages — all resolved packages (the full set, after filtering)

  • :project? — boolean indicating if the package is a project (under systems/)

  • :root — monorepo root path

Plus any extra options passed on the command line or merged from implicits.

Invoke an action directly:

clojure -T:kbuild run :action <namespace/fn> :package <name>

Packaging

kbuild.uber/jar

Builds a standard Clojure uberjar. All dependencies (except local monorepo deps, which are inlined as sources) are merged into a single jar.

When :entry-point is provided the namespace is AOT-compiled and Main-Class is set in the manifest, making the jar executable with java -jar.

Option Default Description

:entry-point

 — 

Main namespace. Triggers AOT compilation and sets Main-Class.

:uber-file

<group>.<name>-<version>.jar

Output jar filename.
Examples
clojure -T:kbuild run :action kbuild.uber/jar :package janus/chm-api

clojure -T:kbuild run :action kbuild.uber/jar :package janus/chm-api \
  :entry-point io.forward-publishing.janus.facade.main

kbuild.uber/rama-jar

Builds a Rama-compatible uberjar. Same as kbuild.uber/jar but never performs AOT compilation — the :entry-point option is ignored.

Option Default Description

:uber-file

<group>.<name>-<version>.jar

Output jar filename.
Example
clojure -T:kbuild run :action kbuild.uber/rama-jar :package janus/chm-backend

kbuild.pack/skinny

Builds a skinny jar with dependencies copied to a separate lib/ directory. The main jar’s Class-Path manifest entry points to the jars in lib/, preserving the correct classpath order.

When :entry-point is provided the namespace is AOT-compiled and Main-Class is set.

Option Default Description

:entry-point

 — 

Main namespace. Triggers AOT compilation and sets Main-Class.

:jar-file

<group>.<name>-<version>.jar

Output jar filename.

Output structure:

target/
  <package>.jar
  lib/
    dep1.jar
    dep2.jar
    ...
Example
clojure -T:kbuild run :action kbuild.pack/skinny :package janus/my-app

kbuild.pack/one-jar

Builds a self-executable One-JAR using pack.alpha. All dependencies are bundled inside a single jar and loaded via a custom classloader, avoiding file-name conflicts that can occur with traditional uberjars.

When :entry-point is provided the namespace is AOT-compiled and Main-Class is set. Without it, the jar defaults to clojure.main.

Option Default Description

:entry-point

 — 

Main namespace. Triggers AOT compilation and sets Main-Class.

:jar-file

<group>.<name>-<version>.jar

Output jar filename.
Example
clojure -T:kbuild run :action kbuild.pack/one-jar :package janus/my-app

Deployment

kbuild.maven/deploy

Deploys a package jar to a Maven repository. The jar must already exist in target/ (i.e. run a packaging action first).

Option Default Description

:mvn/repo

 — 

Required. Maven repository name (must match a <server> id in ~/.m2/settings.xml).

:jar-file

<group>.<name>-<version>.jar

Jar filename override.
Example
clojure -T:kbuild run :action kbuild.maven/deploy :package janus/chm-backend \
  :mvn/repo '"janus"'

Version control

kbuild.git/tag-version

Creates a git tag for the package’s current version. The tag format is determined by kmono’s versioning system.

This is the default action for the release implicit — it runs automatically when you invoke clojure -T:kbuild release, with no per-package configuration needed. Override per-package with :kbuild/implicits {:release {:kbuild/action custom/fn}}.

Option Default Description

:push-tags

false

Push tags to the remote after creating them.
Examples
# Via the release implicit (recommended)
clojure -T:kbuild release :package janus/chm-backend
clojure -T:kbuild release :package janus/chm-backend :push-tags true

# Direct invocation
clojure -T:kbuild run :action kbuild.git/tag-version :package janus/chm-backend \
  :push-tags true

Testing

kbuild.test/test

Runs clojure -M<aliases> in the package directory (defaults to -M:test). This is the default action for the test implicit — it works out-of-the-box for any package that has a :test alias in its deps.edn.

Option Default Description

:aliases

[:test]

Vector of alias keywords to append to -M. Override to run multiple aliases, e.g. [:test :integration].

A typical :test alias using Kaocha:

:test {:extra-paths ["test"]
       :extra-deps  {lambdaisland/kaocha {:mvn/version "..."}}
       :main-opts   ["-m" "kaocha.runner"]}
Examples
# Direct invocation
clojure -T:kbuild run :action kbuild.test/test :package janus/core

# Via the test implicit (equivalent when no per-package override)
clojure -T:kbuild run :action test :package janus/core

# Shorthand
clojure -T:kbuild test :package janus/core

Cleanup

kbuild.build/clean

Deletes the package’s entire target/ directory.

Takes no action-specific options.

Example
clojure -T:kbuild run :action kbuild.build/clean :package janus/chm-backend

There is also a top-level shorthand:

clojure -T:kbuild clean :package janus/chm-backend

Docker

kbuild.docker/build

Builds a Docker image for the package by running docker build -t <local-ref> . in the package directory.

The image is tagged with two local refs (no registry prefix): a versioned ref derived from the package’s group, name, and version (e.g. janus-chm-api:1.0.0), and a stable <name>:latest ref. The versioned ref is the canonical intermediate image used by kbuild.docker/push; the :latest ref is used by kbuild.grype/scan.

Takes no action-specific options (:docker/image-refs is used only by push).

Example
clojure -T:kbuild run :action kbuild.docker/build :package janus/chm-api

kbuild.docker/push

Pushes the Docker image for the package to every image ref in :docker/image-refs.

For each image ref, retags the local image (docker tag) and pushes the resulting ref (docker push). The version tag is appended automatically to each image ref. The local image must already exist (i.e. kbuild.docker/build must have been run first).

Option Default Description

:docker/image-refs

 — 

Required. Vector of fully qualified image references (without tag) to push to.
Example
clojure -T:kbuild run :action kbuild.docker/push :package janus/chm-api

kbuild.docker/build+push

Combines <<`kbuild.docker/build`>> and <<`kbuild.docker/push`>> into a single action. The image is built once and pushed to every image ref in :docker/image-refs.

Option Default Description

:docker/image-refs

 — 

Required. Vector of fully qualified image references (without tag) to build and push to.
Example — single image ref
clojure -T:kbuild run :action kbuild.docker/build+push :package janus/chm-api
Example — multiple image refs via implicits
;; deps.edn
:kbuild/implicits
{:publish {:kbuild/action kbuild.docker/build+push
           :docker/image-refs ["ghcr.io/my-org/my-app"
                               "123456789.dkr.ecr.eu-west-1.amazonaws.com/chm-api/my-app"]}}

Vulnerability scanning

kbuild.grype/scan

Scans a locally-built Docker image with Grype and fails the build if any CRITICAL vulnerabilities are found. Use this as the verify implicit action by declaring it explicitly in the package’s deps.edn.

Grype must be installed and available on PATH (grype version should succeed).

The image ref is derived from the package’s group and name with a :latest suffix (e.g. janus-chm-api:latest), matching the tag added by kbuild.docker/build. Pass :docker/image to override.

Option Default Description

:docker/image

<group>-<name>:latest

Local image ref to scan (e.g. "janus-chm-api:latest").

:root

monorepo root

Root path for writing the report. Provided automatically by kbuild.core.

Output:

  • Prints a colored per-severity count table (Critical, High, Medium, Low, Negligible, Unknown).

  • Lists each CRITICAL finding with CVE id, package name, version, and available fix versions.

  • Writes a JSON report to reports/grype/<image-name>-grype-report.json.

  • Throws if any CRITICAL vulnerabilities are found, failing the build.

Example
clojure -T:kbuild run :action kbuild.grype/scan :package janus.chm/api
Example — via verify implicit
clojure -T:kbuild run :action verify :package janus.chm/api
Example — via implicits in deps.edn
;; systems/chm/api/deps.edn
:kbuild/implicits
{:verify {:kbuild/action kbuild.grype/scan}}