Kiri Developers

WINDOW PLACES

Checks before pull, build and run

A check is a handler Kiri calls before it pulls an image, starts a build or creates a container. You answer allow, warn or block, with a reason. Kiri’s engine asks, so your check sees every request that reaches it: docker, Compose, Kiri’s window, kiri and CI jobs alike. A check needs no screen of its own: what it decides shows wherever the pull or the run already shows. What people see will be in the Kiri docs under Checks when 1.0 ships.

The three hooks

Hook Kiri calls you The event has
before-pull Before it pulls an image, including the base images a build pulls image as it was asked for, platform, client
before-build Before a build starts, whether from docker build, docker buildx build, docker compose build, kiri build or the window build.name (the tag) and build.base (the images the Dockerfile names), platform, client
before-run Before it creates a container image, run.name, run.ports, the folders it mounts, whether it asks for privileged mode, client

client is docker, compose, window, kiri or api. A check never gets environment values, the files in a build’s context, or the files in an image. Kiri’s own pulls, such as the images its builder needs, skip checks, so a check can’t stop Kiri from working. Starting a container that already exists isn’t checked again, and in 1.0 the images Kubernetes pulls for pods aren’t checked.

Declare and answer

Name the hooks under [adds] checks. A check has 2 seconds to answer; one that needs longer, such as one that reads its own saved scans or asks a server, can ask for up to 10 with timeout:

[adds]
checks = [{ on = "before-pull" }, { on = "before-run", timeout = "5s" }]

The install prompt shows one line for them: Check before pull and run and answer allow, warn or block. Then register a handler per hook and answer with allow, warn or block:

import { plugin } from "@kiri/sdk";

plugin.check("before-pull", async (pull) => {
  if (pinned(pull.image)) return plugin.allow();
  return plugin.block(`${pull.image} has no fixed version. Name one, such as nginx:1.27-alpine.`);
});

plugin.check("before-run", async (run, kiri) => {
  const scan = await kiri.store.get(`scan:${run.image}`);
  if (scan?.critical) return plugin.warn(`${run.image} has ${scan.critical} critical vulnerabilities.`);
  return plugin.allow();
});
plugin.Check("before-pull", func(ev plugin.CheckEvent, k *plugin.Kiri) plugin.Verdict {
	if pinned(ev.Image) {
		return plugin.Allow("")
	}
	return plugin.Block(ev.Image + " has no fixed version. Name one, such as nginx:1.27-alpine.")
})

plugin.Check("before-run", func(ev plugin.CheckEvent, k *plugin.Kiri) plugin.Verdict {
	if n := criticalFindings(k, ev.Image); n > 0 { // your own code, reading k.Store
		return plugin.Warn(fmt.Sprintf("%s has %d critical vulnerabilities.", ev.Image, n))
	}
	return plugin.Allow("")
})
plugin::check("before-pull", |ev, _kiri| async move {
    if pinned(&ev.image) {
        return plugin::allow("");
    }
    plugin::block(format!("{} has no fixed version. Name one, such as nginx:1.27-alpine.", ev.image))
});

plugin::check("before-run", |ev, kiri| async move {
    match critical_findings(&kiri, &ev.image).await {   // your own code, reading kiri.store()
        n if n > 0 => plugin::warn(format!("{} has {} critical vulnerabilities.", ev.image, n)),
        _ => plugin::allow(""),
    }
});
from kiri import plugin

@plugin.check("before-pull")
def no_latest(ev, kiri):
    if pinned(ev.image):
        return plugin.allow()
    return plugin.block(f"{ev.image} has no fixed version. Name one, such as nginx:1.27-alpine.")

A check runs like the rest of your plugin, in Kiri’s Linux side with the pass the person agreed to, so it’s the same on a Mac, on Windows and on Linux. It runs on every pull, so it should be quick: Rust and Go plugins start fastest, and a check that needs data should read it from its own store, filled earlier by an event, rather than fetch it while someone waits.

How the answers add up

Kiri asks every check for a step at once and waits for all of them, never longer than each one’s time. One block stops the request. Warns let it go ahead, and each reason is shown. A check that doesn’t answer in time counts as a warn, “your plugin didn’t answer in n s”, and so does a handler that throws.

How Kiri adds up the answers of several checksdocker · docker compose · Kiri’s window · kiri · CIa pull, build or runKiri’s engine holds itand asks every check at onceasks2 s to answerasksno-latestfixed version: allowTrivy2 critical: warnAcme policyno answer in 2 s: warnallowwarncounts as warnKiri adds up the answersAny block stops it, naming the plugin and its reason. Warns go ahead, each one shown.Here: the container is created, with two warnings.
A run with three checks. Kiri holds the request and asks all three at once. no-latest allows, Trivy warns, and the company check doesn't answer in 2 seconds, which counts as a warn. Nothing blocked, so the container is created and both warnings are shown.

Two things change what your block means, and neither is up to you:

  • Going ahead anyway. A block from a check someone installed themselves can be overridden once, with Pull anyway in the window or --anyway on kiri pull, kiri build and kiri run. Every override goes in the activity record.
  • Company rules. A company that requires your plugin can make its silence count as a block, and its blocks can’t be overridden. So a required check that’s slow stops people’s work: answer well inside your time. See Company plugins.

Write a reason people can act on

A warn or a block needs a reason: one sentence, up to 200 characters, that says what’s wrong and what to do instead. Kiri shows it with your plugin’s name everywhere the request shows: a row in the window, the Run panel, and docker’s own output.

zsh
$ docker pull nginx
Using default tag: latest
Error response from daemon: no-latest blocked this pull: nginx has no fixed version. Name one, such as nginx:1.27-alpine.
$ docker run -d -p 8080:80 nginx:1.27
WARNING: Trivy: nginx:1.27 has 2 critical vulnerabilities. Both have a fix.
9c2f4e1b7a3d0e6f

A block reaches docker as an error from the engine, and a warn as a warning in Docker’s own words: a WARNING: line from docker run, and a status line during docker pull. plugin.allow(reason) takes a reason too; it goes only in the activity record.

Test a check

kiri plugin test runs your check against requests you describe, with the same pass it gets when installed. A case’s job names the hook and the image; expect names the verdict and words the reason must contain:

# tests/no-latest.toml
[[case]]
name = "a registry port isn't a tag"
job = { check = "before-pull", image = "localhost:5000/app" }
expect = { verdict = "block", reason = "no fixed version" }

[[case]]
name = "a pinned tag goes through"
job = { check = "before-pull", image = "nginx:1.27-alpine" }
expect = { verdict = "allow" }
zsh
$ kiri plugin test
  no-latest 1.0.0 · 2 cases
  ✓ a registry port isn't a tag
  ✓ a pinned tag goes through
  2 passed in 0.2 s

Test and publish has the whole test format, and Your first plugin builds no-latest from an empty folder.

© 2026 Kiri · The SDK is open source under the Apache License 2.0 · Docs · runkiri.com