infisical-patterns

Infisical Patterns

Core patterns for managing secrets with Infisical.

.infisical.json Convention

The .infisical.json file binds a project directory to an Infisical workspace:

{
  "workspaceId": "abc123-def456-ghi789",
  "defaultEnvironment": "dev",
  "gitBranchToEnvironmentMapping": null
}

Rules:

• Commit .infisical.json to git (it contains no secrets, just workspace binding)
• Do NOT commit .env, .env.local, or any file containing secret values

Secret Naming Convention

Use UPPER_SNAKE_CASE for all secret names:

# Correct
DATABASE_URL
REDIS_HOST
STRIPE_SECRET_KEY
AWS_ACCESS_KEY_ID

# Wrong
databaseUrl          # camelCase
redis-host           # kebab-case
stripe.secret.key    # dotted

Folder Organization

Organize secrets by consumer/service so each folder maps directly to an infisical run --path= invocation and machine identity scope.

Pattern A: By Consumer/Service (Recommended)

Best for multi-service projects. Each service gets exactly the secrets it needs via --path.

/ (root)                → Shared secrets (DATABASE_URL, REDIS_URL)
├── /backend            → Backend-only (JWT_SECRET, INTERNAL_API_KEY, SENTRY_DSN)
├── /frontend           → Frontend-only (NEXT_PUBLIC_API_URL, NEXT_PUBLIC_STRIPE_KEY)
├── /mobile             → Mobile-only (PUSH_NOTIFICATION_KEY, DEEP_LINK_SECRET)
└── /ci                 → CI/CD-only (DEPLOY_KEY, DOCKER_TOKEN, CODECOV_TOKEN)

Why this works:

• infisical run --path=/backend injects root secrets + /backend secrets — exactly what backend needs
• Machine identities scoped to /backend can't read /ci secrets
• Maps to team ownership and deployment targets

# Backend gets shared + backend-only secrets
infisical run --env=production --path=/backend -- node server.js

# Frontend gets shared + frontend-only secrets
infisical run --env=production --path=/frontend -- npm run build

# CI gets shared + CI-only secrets
infisical run --env=production --path=/ci -- ./deploy.sh

# Set a secret in a service folder
infisical secrets set JWT_SECRET=supersecret --env=production --path=/backend

# List secrets for a specific service
infisical secrets --env=production --path=/backend