Environnements et secrets

Disponible en anglais

Utilisez Infisical comme source de vérité lisible par l’équipe, gardez les fichiers .env hors des dépôts et déployez sur Cloudflare sans exposer de secrets dans le code ou les logs CI.

Modèle recommandé

Layer	Source of truth	How apps receive values
Local development	Infisical project	infisical run -- pnpm dev injects env vars into the process
Scripts and migrations	Infisical project	infisical run -- pnpm db:migrate or scoped command
Cloudflare runtime secrets	Infisical synced to Cloudflare Workers secrets, or injected during deploy	Worker env bindings / alchemy.secret(...)
Non-secret config	Git-tracked config or Cloudflare vars	Plain bindings, vars, or Alchemy string values
CI deploy identity	GitHub OIDC or one short-lived machine identity	Infisical fetches deploy-time secrets, then runs Alchemy/Wrangler

Infisical should store secrets. Cloudflare should receive only the secrets each deployed Worker needs. Application code should still validate everything at startup.

Classification des secrets

À stocker dans Infisical

• API tokens: CLOUDFLARE_API_TOKEN, email provider keys, analytics tokens
• Auth/session secrets: BETTER_AUTH_SECRET
• OAuth client secrets: GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_SECRET
• Webhook URLs that can trigger deploys or mutations
• Alchemy password/state encryption secrets, when used

À garder comme configuration non secrète

• public URLs: BETTER_AUTH_URL, PUBLIC_API_URL, SITE_URL
• environment/stage names: STAGE=dev|staging|prod
• Cloudflare account ID and zone ID only if your threat model allows it; otherwise keep them in Infisical too
• feature flags that reveal no private behavior

À ne jamais commiter

• .env, .env.local, .dev.vars, production Wrangler secret values
• Cloudflare API tokens
• Infisical machine identity client secrets
• database exports or backups containing real user data

Configuration du projet

Install and connect the CLI once per project:

brew install infisical/get-cli/infisical
infisical login
infisical init

infisical init creates infisical.json, which is safe to commit because it identifies the Infisical project but does not contain secret values.

Suggested Infisical environments:

Infisical environment	App stage	Notes
dev	dev / local	Developer-safe credentials and local-only callbacks
staging	staging	Mirrors production topology but disables risky side effects like real email
prod	prod	Production credentials; protect with approvals

Suggested secret paths:

Path	Rôle
/	Shared app secrets used by most commands
/cloudflare	Cloudflare deploy credentials and account-level tokens
/email	Transactional email provider keys
/oauth	OAuth client IDs/secrets

Commandes locales

Prefer command injection over generating local .env files:

# Run the whole monorepo with dev secrets
infisical run --env=dev -- pnpm dev

# Run a specific app/package
infisical run --env=dev -- pnpm --filter server dev

# Run migrations or scripts with deploy credentials
infisical run --env=dev --path=/cloudflare -- pnpm db:migrate

If a tool absolutely requires dotenv files, generate them ephemerally and delete them after use:

infisical export --env=dev --format=dotenv > .env.local
# run the tool
rm .env.local

Do not make generated dotenv files part of the normal workflow.

Options de déploiement Cloudflare

Option A: Infisical Cloudflare Workers Sync

Utilisez this when you want Cloudflare to hold the runtime secrets before deploy.

1. In Infisical, create a Cloudflare connection with a token scoped to the account and target Workers.
2. Add a Cloudflare Workers secret sync for each Worker/environment.
3. Sync only runtime secrets, not every project secret.
4. In alchemy.run.ts, bind required secret names with alchemy.secret(...) or reference existing Worker secrets.
5. Deploy with Alchemy/Wrangler using deploy identity credentials from Infisical or CI.

This is the cleanest path for Cloudflare Workers because secrets live in Cloudflare as encrypted Worker secrets at runtime.

Option B: Deploy-time Infisical injection

Utilisez this when Alchemy needs the secret value while creating/updating resources:

infisical run --env=staging -- pnpm deploy:staging
infisical run --env=prod -- pnpm deploy:prod

Example alchemy.run.ts pattern:

const stage = process.env.STAGE ?? "dev";

export const server = await Worker("server", {
  name: `my-app-server-${stage}`,
  bindings: {
    BETTER_AUTH_SECRET: alchemy.secret(process.env.BETTER_AUTH_SECRET!),
    BETTER_AUTH_URL:
      stage === "prod" ? "https://api.example.com" : "https://api.staging.example.com",
  },
});

This matches the CAPM pattern: stage-scoped resource names, domain mapping in code, secrets injected only into the deploy process.

Option C: CI runtime fetch with OIDC

Utilisez this for GitHub Actions:

1. Create an Infisical machine identity that trusts GitHub OIDC for the repo/workflow.
2. Utilisez Infisical’s GitHub action to fetch secrets at job runtime.
3. Run pnpm predeploy and pnpm deploy:* with those environment variables.
4. Keep only the Infisical identity/bootstrap configuration in GitHub; avoid duplicating app secrets in GitHub Secrets.

Scripts package.json recommandés

{
  "scripts": {
    "predeploy": "pnpm fmt && pnpm lint && pnpm typecheck && pnpm doctor:react:diff",
    "deploy": "pnpm predeploy && pnpm exec alchemy deploy",
    "deploy:staging": "STAGE=staging pnpm deploy",
    "deploy:prod": "STAGE=prod pnpm deploy",
    "deploy:staging:secrets": "infisical run --env=staging -- pnpm deploy:staging",
    "deploy:prod:secrets": "infisical run --env=prod -- pnpm deploy:prod"
  }
}

Keep the plain scripts useful for CI jobs that already fetched secrets. Utilisez the :*:secrets scripts locally.

Pattern runtime Cloudflare Worker

Validate bindings, not process.env, inside Worker request code:

import { z } from "zod";

export const envSchema = z.object({
  DB: z.custom<D1Database>(),
  BETTER_AUTH_SECRET: z.string().min(32),
  BETTER_AUTH_URL: z.string().url(),
});

export type Env = z.infer<typeof envSchema>;

export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const parsedEnv = envSchema.parse(env);
    // use parsedEnv.DB, parsedEnv.BETTER_AUTH_SECRET, ...
  },
};

Utilisez process.env only in Node-side tooling such as Alchemy, Drizzle config, scripts, and CI.

CAPM-Inspired Deployment Hardening

Bring these patterns into new Fenod projects:

• Utilisez a single STAGE variable (dev, staging, prod) and derive resource names from it.
• Keep domain maps in alchemy.run.ts so staging/prod hostnames are explicit and reviewable.
• Utilisez isolated D1/R2/KV/Queue resources per stage.
• Adopt existing Cloudflare resources only when migrating an already-live project.
• Disable real outbound email in staging by injecting empty provider credentials or a sandbox provider.
• Require backups before production D1 migrations, destructive R2 operations, or DNS changes.
• Keep production deploys approval-gated even if preview/staging deploys are autonomous.

Checklist

Nouveau projet

• Create Infisical project with dev, staging, and prod environments.
• Commit infisical.json; do not commit dotenv files.
• Add .env.local, .dev.vars, and backup dumps to .gitignore.
• Add Zod validation for Cloudflare bindings and Node-side deploy env.
• Decide whether runtime secrets reach Cloudflare via Workers Sync or deploy-time injection.
• Add deploy:*:secrets scripts for local use.

Avant le déploiement en production

• pnpm predeploy passes.
• Infisical prod secrets are complete and reviewed.
• Cloudflare runtime secrets are synced or deploy-time injection is tested.
• D1 migrations are backed up and rehearsed on staging.
• Staging uses production-like domains/resources but safe side effects.
• Production deploy command is run from CI or an approved local session.