How to Safely Manage Environment Variables and Secrets in Antigravity

Antigravity is designed to read files across your project and build deep context for its AI agents. While this makes development incredibly productive, it also means you need to be intentional about how you handle sensitive information like API keys, database credentials, and service tokens.

Why This Matters in Antigravity

Antigravity's agents scan your project directory to build context. If your .env file contains raw API keys, those values could end up in the agent's context window. This creates several risks:

• Accidental commits: A .env file gets pushed to a public repository, exposing credentials to the world
• Unintended AI exposure: Secrets appear in the agent's context and could leak into generated code or output
• Configuration drift: Team members use different values across environments, causing hard-to-debug failures

Proper environment variable management eliminates these risks while letting you take full advantage of Antigravity's context-aware capabilities.

The Basics: .env Files and .gitignore

Start by creating a .env file at your project root and making sure it's excluded from version control.

# Add to .gitignore
.env
.env.local
.env.production
.env.*.local

Then create a .env.example file that documents the required variables without including actual values. This file should be committed to your repository.

# .env.example (values left blank)
DATABASE_URL=
STRIPE_SECRET_KEY=
NEXT_PUBLIC_API_URL=
GOOGLE_AI_API_KEY=

For Antigravity specifically, you want .env.example in your project context but .env excluded from it.

Leveraging Antigravity's Context Files

Antigravity's .gemini/context.md file and Brain system let you communicate project conventions to the AI agent. Use them to set clear boundaries around secret handling.

<!-- Add to .gemini/context.md -->
## Environment Variable Policy
 
- Secrets and API keys are stored in `.env` (never committed)
- Do not reference `.env` contents in generated code
- When adding a new service integration, update `.env.example` as well
- Production secrets are managed via `wrangler secret` on Cloudflare Workers

By spelling this out explicitly, you reduce the chance of the agent embedding secrets in generated code or creating logging statements that would expose sensitive values.

Managing Variables Across Environments

Real projects need different configurations for development, staging, and production. Here's a recommended setup for Antigravity projects.

Local Development

.env.local          # Your local overrides (gitignored)
.env.development    # Shared development defaults
.env.example        # Template for required variables (committed)

Production Deployment

Use your hosting platform's built-in secrets management rather than relying on files.

Cloudflare Workers / Pages:

# Set secrets via wrangler CLI
wrangler secret put STRIPE_SECRET_KEY
wrangler secret put DATABASE_URL

Vercel:

vercel env add STRIPE_SECRET_KEY production

Firebase:

firebase functions:config:set stripe.key="sk_live_xxx"

When asking Antigravity's agent to handle deployment tasks, mention in your context that production secrets are already configured through the CLI. This prevents the agent from trying to hardcode values or create deployment scripts that embed credentials.

Team Workflows

When multiple developers use Antigravity on the same project, you need shared conventions for handling secrets.

Recommended Practices

1. Keep .env.example up to date: Every PR that introduces a new environment variable should include an update to .env.example
2. Document key rotation procedures: Write down how to rotate API keys in your README or internal wiki
3. Set explicit rules in Antigravity context: Add a line to .gemini/context.md stating that generated code must never log or expose secrets
4. Use pre-commit hooks to catch leaks: Tools like git-secrets or detect-secrets block commits that contain credential patterns

Setting Up Pre-commit Hooks

# Install and configure git-secrets
brew install git-secrets
cd your-project
git secrets --install
git secrets --register-aws  # Register AWS key patterns
 
# Add custom patterns
git secrets --add 'sk_live_[a-zA-Z0-9]+'   # Stripe Live Key
git secrets --add 'sk-[a-zA-Z0-9]{48}'      # OpenAI API Key

With this in place, even if you accidentally stage your .env file, the commit will be rejected before any damage is done.

Working Safely with Antigravity's Agent

Avoid pasting API keys directly into Antigravity's chat or agent interface. Instead, use these patterns.

Ask the Agent to Reference Environment Variables

Example prompt:
"Write a function that calls the Stripe payment API.
Read the API key from process.env.STRIPE_SECRET_KEY.
Do not hardcode any credentials."

Handle .env Edits Manually

Rather than letting the agent write to your .env file directly, ask it to generate the variable names and descriptions you need. Then fill in the actual values yourself.

Example prompt:
"List the environment variables needed for the new Supabase
integration and show me what to add to .env.example.
Don't modify the actual .env file."

Common Issues and Fixes

The Agent Hardcoded a Secret

Add explicit rules to your context file and always review generated code with git diff before committing. Look for any string that resembles a key or token.

A .env File Was Accidentally Committed

Simply deleting the file doesn't remove it from Git history. Use BFG Repo-Cleaner or git filter-branch to scrub the file from all commits, then rotate every exposed credential immediately.

# Remove .env from entire Git history with BFG
bfg --delete-files .env
git reflog expire --expire=now --all
git gc --prune=now --aggressive

Environment Variables Aren't Loading

In Next.js projects, client-side variables require the NEXT_PUBLIC_ prefix. Make sure to mention this convention when prompting Antigravity to generate frontend code, so the agent uses the correct variable names.

Wrapping Up

Antigravity's deep context awareness is a powerful asset, but it works best when paired with disciplined secret management. A solid .gitignore setup, clear guidelines in your Context Files, and consistent team practices will keep your credentials safe while you enjoy the full benefits of AI-assisted development.

Environment variable hygiene might not be the most exciting part of a project, but it's one of those things that pays dividends as your codebase grows. Start by tidying up your .env.example and updating your Context Files today.