Semaphore UI on Kubernetes without Helm, with Kapitan

Semaphore UI 2.19.17, a web UI and API for Ansible, Terraform, OpenTofu and shell tasks, as one replica with its admin account, rendered by the kadet-hub kubernetes generator 1.14.0 from Semaphore’s Helm chart 16.2.2. The database is the included recipe postgresql.

• Latest version: 1.0.2, published 2026-11-07
• Source chart: oci://ghcr.io/semaphoreui/charts/semaphore:16.2.2@sha256:7b0eb7ccdf20b5f7ecf6b93bd2565d2bfaef089b6e11c023fa2a9d47ac331c2e
• Proof level: deploys, compared with the chart by the kadet-hub/recipes CI
• renders passed in the release run of 2026-11-07 with check 0.18.0, kind v0.33.0
• Output capabilities: none
• Inventory backends: omegaconf
• Prerequisites, installed once per cluster before the recipe: cnpg
• Generators: kubernetes 1.14.0 sha256:787129e1eaed6b9bc868fe4c4aec58d40de6a89fc3cc08424a4cb5822b855080
• Image security: grade F 495 findings, one per advisory and package, in the 1 image of version 1.0.2: CRITICAL 9, HIGH 205, MEDIUM 234, LOW 40, UNKNOWN 7. Scanned 2026-11-07 11:47 UTC. Full report
  The grade rates the upstream images the recipe pins, not the recipe: docker.io/semaphoreui/semaphore.

What it deploys

• recipes.semaphore (init.yml)
• recipes.semaphore.semaphore (semaphore.yml): semaphore

Required parameters

applications.semaphore.admin.username and applications.semaphore.admin.password are the login and password of the admin account. The init container admin creates the account on the first start and leaves it alone afterwards, so a later change of the password in the target does not reach it. Change it in Semaphore.

applications.semaphore.cookie_hash, applications.semaphore.cookie_encryption and applications.semaphore.access_key_encryption each hold 32 random bytes in base64, as openssl rand -base64 32 prints them. Semaphore signs and encrypts its session cookies with the first two. It encrypts the keys and secrets that projects store with the third, so keep that one for the life of the database. applications.semaphore.runner_token is a random string. A runner that presents it registers itself, also while remote runners are off.

Set the password, the three keys and the token to refs with the backend of your choice. Without one of them the compile stops with Interpolation key '<key>' not found. postgresql requires no parameter.

Include

A target includes the recipe and its options as classes and can override anything the recipe sets:

classes:
  - recipes.semaphore
parameters:
  namespace: semaphore
  kapitan:
    vars:
      target: semaphore
  applications:
    semaphore:
      admin:
        username: <login>
        password: <ref>
      cookie_hash: <ref>
      cookie_encryption: <ref>
      access_key_encryption: <ref>
      runner_token: <ref>

Fetching it

The quickstart goes through these steps on a kind cluster with the uptime-kuma recipe, from installing Kapitan to the running app.

A separate fetch inventory pins the recipe by version and digest. This is fetch/targets/recipes.yml for version 1.0.2:

parameters:
  kapitan:
    dependencies:
      - type: oci
        source: ghcr.io/kadet-hub/recipes/semaphore:1.0.2@sha256:ae9f0ec39bbeff18b4c9c08fe09941206d98a301399b9a1df182bb00513ee7f0
        output_path: inventory/classes/recipes/semaphore

Version 1.0.2 includes postgresql 1.1.1. The consumer workflow adds the included recipes at the digests the index lists. Kapitan's --fetch reads no index, so for a local compile pull them by digest first:

tmp=$(mktemp -d)
oras pull -o "$tmp" ghcr.io/kadet-hub/recipes/postgresql@sha256:1e8465058c256cc86995dc8d6f1eb2f095df244fadcaf756935599f4d9ead6a9
mkdir -p inventory/classes/recipes/postgresql
tar -xf "$tmp/postgresql.tar" -C inventory/classes/recipes/postgresql --no-same-owner

The first command fetches the recipe into inventory/classes/recipes/semaphore, the second the generators and compiles:

kapitan compile --inventory-path fetch --fetch --output-path .
kapitan compile --fetch

The first command exits with status 1 because the fetch target compiles nothing. Kapitan's --fetch checks neither the digest nor the attestation. This verifies the attestation of the recipe and of the recipes it includes:

gh attestation verify \
  oci://ghcr.io/kadet-hub/recipes/semaphore@sha256:ae9f0ec39bbeff18b4c9c08fe09941206d98a301399b9a1df182bb00513ee7f0 \
  --owner kadet-hub \
  --cert-identity https://github.com/kadet-hub/registry/.github/workflows/release.yml@refs/heads/main

gh attestation verify \
  oci://ghcr.io/kadet-hub/recipes/postgresql@sha256:1e8465058c256cc86995dc8d6f1eb2f095df244fadcaf756935599f4d9ead6a9 \
  --owner kadet-hub \
  --cert-identity https://github.com/kadet-hub/registry/.github/workflows/release.yml@refs/heads/main

The attested index must also list each digest under its recipe with the pinned version, and not as yanked. Verifying by hand shows how to read it.

Settings

<c> stands for components.semaphore.

The init container takes each variable of the chart from <c>.env by name, so a change there reaches both containers. A variable added to <c>.env reaches the server only. Values are strings, so quote "false" and "0".

The chart sends sslmode=disable to PostgreSQL unless database.options sets one. The recipe sets sslmode=require, as tests/values.yaml does for the chart, because CloudNativePG serves TLS. Both containers run with runAsNonRoot: true, the chart’s podSecurityContext in tests/values.yaml. The image runs as UID 1001.

The pod annotations checksum/* are the chart’s hashes of its ConfigMap and Secrets for the values of tests/values.yaml. They do not follow the target’s values, so after changing a Secret restart Semaphore with kubectl rollout restart deployment/semaphore. The init container’s script and config.json are the chart’s, with its license in semaphore.yml.LICENSE.

The chart’s Ingress, LDAP, OIDC, the mail, Telegram and Slack alerts, extra Python packages and a custom CA bundle are off by default and not part of the recipe. Its MariaDB and PostgreSQL subcharts stay off.

Any list set in the target is appended to the recipe’s list. To replace one, set the key to ~ in a class included after the recipe and the new list in the target.

Proof

check semaphore --level deploys with tests/values.yaml and tests/target.yml, on kind for each Kubernetes minor CI tests, with cnpg installed first. The objects of postgresql are left out of the comparison and applied with the recipe. The Deployment and the Service select on name, the chart on app.kubernetes.io/name and instance, and both select the same pods. The pod and the ServiceAccount set automountServiceAccountToken: true, the API default the chart leaves unset. The chart binds no role. The chart’s Helm test Pod/semaphore-test-connection is left out. tests/target.yml runs one PostgreSQL instance.

tests/smoke waits for the Cluster and gets /api/ping through the Service and the API server’s service proxy. It then logs in as the admin through /api/auth/login, which needs the account the init container wrote into PostgreSQL, and reads /api/user, /api/projects and /api/info with the session cookie. /api/info must report the version of the Deployment’s image tag and remote runners off. It runs no task.

Versions

• 1.0.2, 2026-11-07: sha256:ae9f0ec39bbeff18b4c9c08fe09941206d98a301399b9a1df182bb00513ee7f0
• 1.0.1, 2026-11-04: sha256:69c3a37b8a04d4f5bc447954dec2a7c0fb1ec0349e6bd56fda914d6b808892c2

The recipe's files are in kadet-hub/recipes. All recipes