Choosing an Insomnia Environment Strategy for Team Workspaces and CI/CD

The Decision: How to Structure Environments for Teams and Pipelines

Insomnia's environment system sits at the center of any team workflow that moves requests from local development through staging to production. The core decision is whether to use Insomnia's built-in two-level hierarchy (base environment + sub-environments) or maintain separate flat environment files per context. This choice affects how secrets are handled, how much duplication lives in version control, and how smoothly CI/CD pipelines can inject runtime values.

Constraints that shape the decision:

• Secrets (API keys, tokens) must never be committed or synced across team members.
• Common defaults (base URLs, shared headers) should be defined once.
• CI/CD pipelines need a deterministic way to inject secrets at runtime without modifying committed files.
• Developers must be able to switch contexts quickly during local testing.

Supported Options Compared

Aspect	Base + Sub-environments (Native Hierarchy)	Flat Environments per Context
Structure	One base environment (required) + optional sub-environments (dev, staging, prod) that inherit and override	Independent environment files: dev.json, staging.json, prod.json
Variable resolution	Base → active sub-environment → request-specific → script-set	Single file per run; no inheritance
Secret handling	Private variables (excluded from sync/export) + CLI --env-file for CI	Entire file excluded from git; CI loads separate secrets file
Duplication	Low — common values live in base	High — each file repeats shared defaults
Team sync	Insomnia Sync handles shared variables; private values stay local	Manual file sharing or git (with secrets stripped)
CI/CD integration	insomnia-cli run --environment=staging --env-file=secrets.env	insomnia-cli run --environment=staging.json --env-file=secrets.env
Insomnia version	2023.5+ adds quick-switch UI and environment-scoped scripts	Works on all versions

Trade-offs

When to Use Base + Sub-environments

Choose the native hierarchy when:

• Your team shares a workspace via Insomnia Sync and wants a single source of truth for shared configuration.
• You have more than two environments (dev, staging, prod, qa, sandbox) and want to avoid copying common variables.
• You need environment-scoped pre-request/after-response scripts (added in 2023.5) to handle auth token refresh differently per environment without conditional logic.
• Developers benefit from the quick-switch UI to toggle contexts instantly.

The main risk is inheritance behavior: sub-environments replace entire variable values — they do not merge arrays or objects. If base.headers is an object and staging overrides it, the base headers are lost unless restated. Plan variable granularity accordingly (e.g., use base_url, auth_header as separate strings rather than a single headers object).

When to Use Flat Environments

Choose flat files when:

• You're a solo developer or a small team without Insomnia Sync.
• Environments differ significantly (different auth schemes, entirely different header sets) so inheritance provides little reuse.
• You prefer explicit, self-contained files that are easy to audit and diff in git.
• You want to avoid the sync conflict edge case where a teammate re-adds a shared variable with the same name as your private variable, potentially overwriting your local value on pull.

The cost is duplication. Every change to a shared default (e.g., updating a default timeout) must be applied to each environment file.

Concrete Implementation: Base + Sub-environments with CI

This walkthrough assumes Insomnia 2023.5+ and insomnia-cli v8+ (Node 18+).

1. Create the Base Environment

In Insomnia → Environments pane, create a base environment named base. Add shared variables:

base_url: https://api.example.com
request_timeout: 30000
default_headers: {"Content-Type": "application/json"}

Mark all as shared (the default). These will be synced and exported.

2. Create Sub-environments

Create three sub-environments: dev, staging, prod. Each inherits from base. Override only what changes:

# dev
base_url: https://dev-api.example.com
# (request_timeout and default_headers inherited)

# staging
base_url: https://staging-api.example.com
# (request_timeout and default_headers inherited)

# prod
base_url: https://api.example.com
request_timeout: 60000
# (default_headers inherited)

3. Add Private Variables for Secrets

In each sub-environment, add a variable named PRIVATE_API_KEY and mark it private. Leave the value empty or put a local placeholder. Private variables:

• Are never synced via Insomnia Sync.
• Are excluded from File → Export output.
• Are not read by insomnia-cli unless provided via --env-file.

Verification: Export the workspace (File → Export → Insomnia Workspace) and open the JSON. Confirm PRIVATE_API_KEY does not appear in any environment object.

4. Commit the Workspace Definition

Export the workspace to insomnia-workspace.json and commit it. The file contains base, dev, staging, prod with shared variables only. Private values are absent.

5. Local Developer Setup

Each developer clones the repo, imports the workspace in Insomnia, then edits each sub-environment locally to fill in their personal PRIVATE_API_KEY values. These stay in the local Insomnia database and are never committed.

6. CI/CD Pipeline Configuration

Create a secrets.env file in your CI secret store (GitHub Actions secrets, GitLab CI variables, etc.) with lines like:

PRIVATE_API_KEY=ci-staging-key-123

In your pipeline, export the workspace first (required because insomnia-cli v8+ reads from the exported file, not the live app), then run:

# Export step (run in an environment with Insomnia CLI installed)
npx insomnia-cli export --workspace=insomnia-workspace.json --output=export.json

# Test run against staging
npx insomnia-cli run \
  --workspace=export.json \
  --environment=staging \
  --env-file=secrets.env

The --environment=staging flag activates the staging sub-environment (which inherits from base). The --env-file=secrets.env injects PRIVATE_API_KEY at runtime, overriding the empty private variable.

7. Validation in CI Logs

Add a temporary request with a pre-request script to verify variable resolution:

console.log('base_url:', environment.get('base_url'));
console.log('request_timeout:', environment.get('request_timeout'));
console.log('PRIVATE_API_KEY present:', !!environment.get('PRIVATE_API_KEY'));

Run the pipeline and check logs. You should see staging's base_url, inherited request_timeout (30000), and the injected secret present.

Environment-Scoped Scripts (2023.5+)

If your auth flow differs per environment (e.g., dev uses a static token, staging/prod use OAuth client credentials), use environment-scoped pre-request scripts instead of conditional logic in a global script.

In the Environments pane, select staging → Scripts tab → Pre-request. Add:

// Runs only when staging is active
await refreshStagingToken();

In prod → Scripts tab → Pre-request:

// Runs only when prod is active
await refreshProdToken();

These run after global pre-request scripts. Order matters: if a global script sets an auth header, the environment-scoped script can override it. Test by switching environments in the quick-switch dropdown and sending a request — the console output will show which script executed.

Limitations and Gotchas

• Private variables are not encrypted at rest. They are only excluded from sync/export. Treat the local Insomnia workspace database (~/.config/Insomnia on Linux/macOS, %APPDATA%\Insomnia on Windows) as sensitive.
• No deep merge. Overriding an object or array replaces it entirely. Use flat variable names (header_auth, header_accept) instead of a single headers object.
• Sync conflicts. If two teammates edit the same shared variable, Insomnia Sync merges last-write-wins. A teammate re-adding a variable you marked private can cause your private value to be overwritten on sync. Mitigation: prefix private variables with PRIVATE_ and document the convention.
• CLI reads exported file only. Always run insomnia-cli export before insomnia-cli run in CI. The live app state is not read.
• Node 18+ required. insomnia-cli v8+ drops support for older Node versions. Ensure CI agents meet this.

Quick Verification Checklist

1. Open Insomnia → Environments → create base + sub-environment → mark a variable private → File → Export → verify private variable absent in JSON.
2. Run npx insomnia-cli run --workspace=export.json --environment=staging --env-file=secrets.env and observe variable substitution in request logs.
3. Add a pre-request script console.log(environment.get('base_url')) in a sub-environment script tab; switch environments and confirm value changes.
4. Test sync conflict: two users edit same shared variable → sync → inspect merge result in Insomnia activity log.

Decision Summary

For most teams using Insomnia Sync with three or more environments, the base + sub-environment hierarchy reduces duplication, keeps secrets out of git, and integrates cleanly with CI via --env-file. The flat-file alternative remains viable for solo work or highly divergent environments. Whichever you choose, export the workspace before every CI run, keep private variables out of sync, and verify variable resolution in pipeline logs before relying on the setup for production deployments.