Skip to content
Kānuka

Working with Monorepos

Kānuka supports two approaches for managing secrets in monorepos. Choose the one that best fits your team’s access control needs.

Option 1: Single secrets store at root

Section titled “Option 1: Single secrets store at root”

Initialize Kānuka once at the monorepo root and use selective encryption to manage secrets across all services.

Setup

Section titled “Setup”
Terminal window
cd my-monorepo
kanuka secrets init

Usage

Section titled “Usage”

Use file arguments to encrypt or decrypt specific services:

Terminal window
# Encrypt only the API service
kanuka secrets encrypt services/api/.env


# Encrypt multiple services
kanuka secrets encrypt services/api/.env services/web/.env


# Use glob patterns for all services
kanuka secrets encrypt "services/*/.env"


# Encrypt a specific directory
kanuka secrets encrypt services/api/


# Decrypt just what you need
kanuka secrets decrypt services/api/.env.kanuka

Pros

Section titled “Pros”
  • Single source of truth - One .kanuka directory for all access control
  • Simpler key management - One set of keys to manage and rotate
  • Easier onboarding - New team members only need to be registered once
  • Unified audit log - All operations logged in one place

Cons

Section titled “Cons”
  • No per-service access control - All registered users can decrypt all secrets
  • Larger key rotation scope - Revoking a user requires re-encrypting all secrets

Best for

Section titled “Best for”
  • Small to medium teams where everyone needs access to all services
  • Projects where access control is handled at the repository level
  • Teams prioritizing simplicity over granular permissions

Option 2: Separate secrets stores per service

Section titled “Option 2: Separate secrets stores per service”

Initialize Kānuka independently in each service that needs secrets management.

Setup

Section titled “Setup”
Terminal window
cd my-monorepo/services/api
kanuka secrets init


cd ../web
kanuka secrets init


cd ../worker
kanuka secrets init

Usage

Section titled “Usage”

Run commands from within each service directory:

Terminal window
# In services/api
cd services/api
kanuka secrets encrypt
kanuka secrets decrypt


# Register a user for just this service
kanuka secrets register --user [email protected]

Pros

Section titled “Pros”
  • Per-service access control - Different teams can access different services
  • Isolated key rotation - Revoking access only affects one service
  • Independent audit logs - Each service has its own operation history

Cons

Section titled “Cons”
  • More management overhead - Multiple .kanuka directories to maintain
  • Repeated onboarding - Users may need to be registered in multiple services
  • Must remember context - Commands must be run from the correct directory

Best for

Section titled “Best for”
  • Large organizations with distinct teams per service
  • Projects with different security classifications per service
  • Situations requiring strict access separation

Unreadable directories are skipped

Section titled “Unreadable directories are skipped”

Monorepos often contain runtime data owned by other users, such as data/postgres/pgdata/ (owned by the container’s postgres user, mode 0700) or caddy/pocketid data directories. These directories are unreadable to your user and typically live in .gitignore — Kānuka never needs to look inside them.

Commands that scan the project tree (encrypt, decrypt, status, doctor, export, sync, rotate, and revoke) skip directories they cannot read instead of failing, and continue with the rest of the tree. Run any of them with --verbose to list skipped directories:

Terminal window
kanuka secrets encrypt --verbose
# [warn] Skipping unreadable directory /path/to/data/postgres/pgdata: open ...: permission denied

If a directory that actually contains .env files is being skipped, fix its permissions or pass the files explicitly as shown above.

Recommendation

Section titled “Recommendation”

Start with Option 1 (single store at root) unless you have a specific need for per-service access control. It’s simpler to manage and you can always migrate to Option 2 later if needed.

Migration between options

Section titled “Migration between options”

From single store to per-service

Section titled “From single store to per-service”
  1. Decrypt all secrets at the root level
  2. Initialize Kānuka in each service directory
  3. Register users as needed per service
  4. Encrypt secrets in each service
  5. Remove the root .kanuka directory

From per-service to single store

Section titled “From per-service to single store”
  1. Decrypt all secrets in each service
  2. Remove .kanuka directories from each service
  3. Initialize Kānuka at the root
  4. Register all users who need access
  5. Encrypt all secrets from the root

CI/CD considerations

Section titled “CI/CD considerations”

Single store approach

Section titled “Single store approach”

Your CI/CD pipeline can decrypt specific services:

Terminal window
# Decrypt only what this job needs
kanuka secrets decrypt services/api/.env.kanuka

Per-service approach

Section titled “Per-service approach”

Your pipeline needs to run from the correct directory:

Terminal window
cd services/api && kanuka secrets decrypt

Or use separate credentials per service for additional isolation.

Next steps

Section titled “Next steps”