Give kanman your team's toolchain

Define once which image, variables, secrets and setup your repositories need. kanman's coding work and bulk changes run in it, on your runners and in kanman Cloud.

Your repositories need a toolchain: a Go version, a JDK, Python with its packages, credentials for private modules. Instead of installing it on every runner, you describe it once for the team as its environment. kanman then works inside it:

  • the coding agent writes and tests code in it,
  • bulk changes across many repositories run their update commands in it.

All of them use the identical image, on your own runners and in kanman Cloud.

Set up the environment

Open Team > Checks and delivery and find Team environment. Owners and admins can edit it.

Field What it means
Base image The container image with your toolchain, for example golang:1.25, eclipse-temurin:21 or python:3.12, or an image from your own registry, for example registry.gitlab.example.com/platform/go-toolchain:1.25. Use an image based on Debian, Ubuntu or Red Hat; Alpine images are not supported for the coding agent.
Variables Plain settings every command needs, one NAME=value per line, for example GOPRIVATE=gitlab.example.com. Not for secrets.
Secrets passed in Workspace secrets the environment needs, chosen from the secrets this team may use (the secrets under What I may change in Team > Limits and budgets), for example a read token for private modules. Their values never appear in logs.
Caches kept between runs Folders kept between runs so downloads are not repeated, one per line. Name the whole folder a tool writes, for example /go/pkg for Go (its modules and their checksums), not a folder inside it. A path starting with ~/ is in the home folder of the environment.
Setup step A shell command that runs before the coding agent starts, for example a git setting that uses a secret to fetch private modules. It must be safe to run more than once.
Network Host network reaches everything your runner reaches, including hosts behind your VPN. Isolated network gives the container its own network with internet access only.

The commands themselves stay in your repositories: the coding agent runs your repository’s own build and test commands, for example make test, inside the environment.

An example for Go services whose private modules come from your GitLab, with a read token granted to the team as the secret FM_GITLAB_READ_TOKEN:

Field Value
Base image golang:1.25
Variables GOPRIVATE=gitlab.example.com and GONOSUMDB=gitlab.example.com
Secrets passed in FM_GITLAB_READ_TOKEN
Caches kept between runs /go/pkg and ~/.cache/go-build
Setup step git config --global url."https://oauth2:${FM_GITLAB_READ_TOKEN}@gitlab.example.com/".insteadOf https://gitlab.example.com/
Network Host network

The credential lives only inside the environment, never in your runner’s own git configuration.

If your GitLab is connected through the runner, you do not need to store a separate read token: the coding agent reads from your GitLab through your runner, read-only, and no token enters its environment.

Images from your own registry

A team can bring a fully customized image from any registry: GitLab’s container registry, Harbor, GitHub Container Registry, a private Docker Hub repository or any other OCI registry. Give your runners read access under Registry credentials, below the environment’s status (owners and admins, workspaces whose work runs on their own runners):

  1. Choose Add registry credentials.
  2. Enter the registry’s host, for example registry.gitlab.example.com or harbor.example.com:8443, a username and a password or token. A token with read access to the registry is enough: a GitLab deploy token with read_registry, a Harbor robot account, a GitHub token with read:packages.
  3. Choose Save. The password is never shown again; the list shows the registry, who set it and when.

The runner uses these credentials only to pull this team’s image: each pull gets a Docker configuration of its own that is removed right after it, never the runner’s own Docker login, and no other team can use them. An image a runner pulled with a team’s credentials stays that team’s: another team starts it only with its own access. kanman Cloud builds team images only from images it can pull without credentials.

The image is checked before it is saved. When you change the base image and choose Save environment in a workspace that runs on its own runners, one of your runners pulls the image with the team’s credentials and checks that the coding agent can run in it. You see “Checking … on your runner”, then the tools it found (“Checked on your runner: go go1.25.1”), and the environment is saved. If the check fails, the environment stays unsaved and the reason says what to fix:

Message What to do
The runner may not pull this image Add or correct the registry credentials for the image’s registry.
The image does not exist Check the name and the tag.
The runner cannot reach the registry Check the runner’s network and proxy settings.
The image has no /bin/sh Use an image with a shell.
The image is based on Alpine (musl) Use an image based on Debian, Ubuntu or Red Hat.

If no runner is online to check the image, choose Save without the check; the first run then reports the same problem if there is one.

Environment status

Choose Save environment to keep your changes (an environment is saved as a whole; Cancel drops your edits). Under Environment status you see:

  • the version of the environment, which changes whenever you change a field,
  • the tools found in the image with their versions, for example go1.25.1,
  • the kanman Cloud image with the status and time of its last build.

Where it runs

On your runners. The runner builds the team’s image once (your image plus kanman’s small layer with the coding agent) and reuses it for every run. For each run it starts the coding agent in a container of that image, with the repository checkout mounted. Only the environment’s variables, its secrets and the one model credential the agent needs go into the container. The runner’s own tokens, its home folder and its Docker access stay outside. When the agent is done, the runner pushes the branch itself, outside the container. An image from your own registry is pulled with the team’s registry credentials. Your runner needs nothing but Docker; see Run the self-hosted runner.

In kanman Cloud. kanman builds your team’s image once per version of the environment. The first run after a change waits for the build, usually one to two minutes; the run shows that it is waiting. Later runs start right away from the built image. If the build fails, the run stops with the reason, for example an image name that does not exist, and the team page tells you what to fix.

Teams without an environment work as before.

See which environment a run used

The run page shows the environment of each attempt: the image, the main tool version and whether it ran in a container on your runner or from the team image in kanman Cloud.

Repositories with their own setup

Every repository of the team uses the team environment. A repository that needs a different toolchain belongs in a team with that environment.

Last updated: January 1, 0001

Open kanman