PAS7 Studio
← Back to all articles

git-env-vault for monorepos: encrypted .env files in Git

A practical guide to git-env-vault for monorepos: how secrets stay encrypted in Git, how developers pull local .env files, and where SOPS, age, and CI fit into the workflow.

12 Mar 2026· 8 min read· Technology
npmTalk to PAS7 Studio about secrets workflow hardening
Best forPlatform engineersDevOps engineersFull-stack teams running monoreposTech leads cleaning up secrets workflows
Editorial cover showing encrypted secrets in Git, per-service local env files, and a monorepo workflow around git-env-vault

quick read

What git-env-vault changes in practice

The main point is not only that secrets are encrypted. The repo also gets a cleaner workflow around them.

Encrypted secret files live in Git instead of plaintext .env files being passed around. [1][3]
Developers still get local .env files where each service expects them. [1][3]
The tool has a lighter onboarding path for pull and a fuller admin path for editing and access changes. [1][2][4]
Local-only values such as bot tokens can stay local instead of being overwritten or pushed into shared state. [1][3][4]
CI can either verify repository state or receive an encrypted payload when a job needs a dotenv file. [2][4][5]

What git-env-vault is

git-env-vault is a Node-based CLI and TUI built around encrypted .env secrets for monorepos. The repo describes it in a straightforward way: encrypted secret files in Git, SOPS + age underneath, and local and CI workflows on top. [1]

It is not trying to be a hosted secret manager. The model is repository-based. Secret files stay encrypted in Git, service mappings decide where decrypted local files go, and the CLI handles pull, diff, push, access changes, and CI checks. [1][2][3][4]

The tool can be installed locally, globally, or used through npx or bunx, which lowers the barrier for a first pull. [1][2]

Plain definition

It connects encrypted secrets in the repo with the local .env files that each service still needs. [1][3]

How the storage model works

It helps to think about the system as a few separate files with separate jobs.

01

Encrypted secrets live under secrets/

The configuration docs show a layout like secrets/<env>/<service>.sops.yaml. Those files stay encrypted in the repository. [3]

02

envvault.policy.json controls recipients

This file defines who can decrypt which environment or service. The docs also recommend keeping recipient lists small and using separate CI and human keys. [3][5]

03

envvault.config.json maps services to local outputs

Each service points to an envOutput path such as apps/api/.env, so local decrypted files end up where the monorepo actually needs them. [3]

04

The CLI ties the model to daily work

Commands such as pull, diff, status, push, refresh, and ci-verify are the practical surface of the setup. [1][2][4]

What to keep in mind

Storage, access, local output, and workflow are different jobs. The tool keeps them aligned. [1][2][3][4]

Easy mode vs full mode

This is the first boundary worth learning, because it keeps onboarding simpler without pretending every machine needs the full admin stack on day one.

Comparison pointEasy modeFull mode
What it usesJS decrypt fallback, usually through cryptoBackend: "auto"System sops + age installed locally
Best forLocal pull and read-oriented onboardingEditing, grant, revoke, updatekeys, rotate, and push
What it does not try to doIt does not replace system SOPS for shared write and key-management tasksIt is the expected path when shared encrypted state or recipients need to change

Simple rule

Use easy mode to start working locally. Use full mode when shared encrypted data or access needs to change. [1][2][4]

A normal developer flow

The common path is short, which makes it easier to adopt.

01

Pull local secrets

Start with git pull and envvault pull --env dev. The workflow docs also show service-specific and pattern-based pull for larger repos. [1][4]

02

Preview differences

Use envvault diff --env dev --service api and envvault pull --env dev --service api --confirm when you want a safer update path. The CLI also supports --plan and --json for preview-only output. [2][4]

03

Check drift

envvault status --env dev shows what is out of sync between local files and the vault state. [1][2][4]

04

Push back deliberately

push supports --dry-run and --confirm, and it stays on the full SOPS path. That keeps shared write-back more intentional than a casual local edit. [1][2][4]

What changes

The workflow becomes pull, diff, status, then push when needed, instead of a vague mix of stale local files and ad-hoc dotenv sharing. [1][2][4]

Local-only values are treated as a real use case

This is one of the most practical parts of the tool, especially in repos with bots, local tokens, or developer-specific credentials.

A short config example from the docs shows the idea clearly:

JSON
{
  "placeholderPolicy": {
    "preserveExistingOnPlaceholder": true,
    "patterns": ["__MISSING__", "CHANGEME*", "*PLACEHOLDER*"]
  },
  "localProtection": {
    "global": ["BOT_TOKEN"],
    "services": {
      "api": ["TELEGRAM_BOT_TOKEN"]
    }
  },
  "services": {
    "api": { "envOutput": "apps/api/.env" },
    "worker": { "envOutput": "apps/worker/.env" }
  }
}

localProtection preserves selected local keys

If a key is protected, pull keeps the local value and push does not write that value into the shared encrypted secret. The docs call out keys such as BOT_TOKEN and TELEGRAM_BOT_TOKEN. [1][3][4]

Placeholder-safe pull avoids pointless breakage

If schema validation generates a placeholder like __MISSING__, pull can keep an existing local non-empty value instead of replacing it. [1][3][4]

Promotion exists for the opposite case

When a local override should become shared encrypted state, the CLI includes promote and promote-all instead of leaving that step to copy-paste habits. [2][3]

Why teams care

A lot of dotenv pain comes from local values being overwritten or accidentally shared. This part of the workflow handles that directly. [1][3][4]

Two CI patterns, two different jobs

The docs split CI into verification and payload delivery, because those are different tasks.

Use ci-verify

Best when CI should validate policy, .sops.yaml consistency, encrypted secret structure, plaintext .env mistakes, and dirty .env* git state. [2][4][5]

Use ci-seal and ci-unseal

Best when a job really needs an encrypted dotenv payload. The documented flow uses a dedicated CI key and a CI blob that is unsealed in the pipeline. [1][2][4]

Keep CI keys separate

The configuration and security docs recommend separate keys for CI and humans. That keeps access boundaries easier to reason about. [3][5]

Quick read

ci-verify protects repository state. ci-seal and ci-unseal handle runtime secret delivery when a job really needs it. [2][4][5]

Common mistakes when adopting it

The tool is easier to use well when the boundaries are clear.

Treating it like a hosted secret platform instead of a repo-native encrypted workflow. [1][3][5]

Forgetting that JS fallback is mainly for decrypt-oriented onboarding, not for write, rotation, or recipient changes. [1][2][4]

Giving too many people access to too many environments instead of keeping recipient lists narrow. [3][5]

Ignoring .gitignore hygiene and CI checks until plaintext files appear in the repo. [3][4][5]

Revoking access without rotating afterward in sensitive cases. The docs explicitly call for revoke plus rotate. [3][4][5]

Acting as if encryption removes endpoint risk. Private age keys and developer machines still matter. [5][6][7]

Healthy expectation

git-env-vault makes the workflow safer and clearer, but it still depends on key hygiene, review, and disciplined offboarding. [3][5][6][7]

Sources

These sources support the command behavior, configuration model, and security guidance used in this article.

Reviewed: 12 Mar 2026Applies to: Node.js 18+ environmentsApplies to: Monorepos with multiple servicesApplies to: Teams using SOPS + age for encrypted secrets in Git

Need help cleaning up a monorepo secrets workflow?

The hard part is usually not encryption itself. It is the workflow around it: local overrides, access changes, CI checks, and repo hygiene.

PAS7 Studio can help shape that into a cleaner setup with clearer service boundaries, safer defaults, and fewer places for secrets drift to grow.

Plan a secrets workflow auditOpen the git-env-vault repository

Related Articles

growth

AI SEO / GEO in 2026: Your Next Customers Aren’t Humans — They’re Agents

Search is shifting from clicks to answers. Bots and AI agents crawl, cite, recommend, and increasingly buy. Learn what AI SEO / GEO means, why classic SEO is no longer enough, and how PAS7 Studio helps brands win visibility in the agentic web.

Read ->
blogs

The most powerful Apple chip yet? M5 Pro and M5 Max are breaking records

A data-backed March 2026 analysis of Apple M5 Pro and M5 Max. We break down why these chips can credibly be called Apple's most powerful pro laptop silicon, how they compare with M4 Pro, M4 Max, M1 Pro, M1 Max, and how they stack up against Intel and AMD laptop rivals.

Read ->
telegram-media-saver

Automatic Tagging & Search for Saved Links

Integrate with GDrive/S3/Notion for automatic tagging and fast search via search APIs

Read ->
services

Bot Development & Automation Services

Professional Telegram bot development and business process automation: chatbots, AI assistants, CRM integrations, workflow automation.

Read ->

Professional development for your business

We create modern web solutions and bots for businesses. Learn how we can help you achieve your goals.

Our Services