Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Documentation: .env.local only works for agentcore dev, not agentcore deploy

Aperta Adatta ai principianti
  • Qualcosa non va?
#1,378 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
Mezza giornata
Idoneità per principianti
74/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
aws
Ambito
cli, cloud, documentation

Direzione di ricerca

Inizia dalla sezione sulle variabili d’ambiente del README e dalla documentazione relativa a agentcore dev e agentcore deploy; esamina come vengono attualmente descritti .env.local, envVars in agentcore.json e AWS Secrets Manager. Il lavoro è completo quando l’ambito esclusivamente locale, il comportamento del deployment e le opzioni più sicure per la produzione sono espliciti, e qualsiasi avviso CLI richiesto viene gestito se viene identificato il punto di ingresso pertinente.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

documentation

Title:

Documentation: .env.local only works for agentcore dev, not agentcore deploy

Labels:

documentation, enhancement

Description:

Problem

The documentation doesn't clearly explain that .env.local only provides environment variables for local development (agentcore dev), and is not deployed to AWS when running agentcore deploy. This leads to confusion when agents work locally but fail in production due to missing environment variables.

Expected Behavior

Documentation should clearly state:

  1. .env.local is loaded during agentcore dev only
  2. .env.local is gitignored and NOT uploaded during deployment
  3. For production deployments, users must use either:
    • envVars array in agentcore.json (not recommended for secrets)
    • AWS Secrets Manager (recommended for sensitive data)
Actual Behavior

Current documentation mentions .env.local but doesn't clarify its scope. Users naturally assume that if .env.local works locally, it will also work when deployed.

Current project structure documentation:

agentcore/
├── .env.local          # Secrets — API keys (gitignored)

This suggests .env.local is for secrets, but doesn't explain it's local-only.

User Impact
  1. Confusion: Agent works with agentcore dev, fails after agentcore deploy
  2. Debugging time: Users spend time troubleshooting why environment variables are missing in production
  3. Security risk: Some users might add credentials to envVars in agentcore.json and accidentally commit to git
Real-World Example

Use case: Deploying an agent that needs external API credentials

Local (works):

# .env.local
API_KEY=xxx
API_SECRET=yyy

# Agent code
api_key = os.getenv("API_KEY")  # ✅ Works with agentcore dev

Deployed (fails):

agentcore deploy  # .env.local not uploaded
# Runtime error: Missing API_KEY
Suggested Documentation Improvements
  1. Add clear section in README:
## Environment Variables

### Local Development
Use `.env.local` for local development with `agentcore dev`:
- Automatically loaded by the CLI
- Gitignored (never committed)
- **NOT deployed to AWS**

### Production Deployment
For deployed agents, choose one:

**Option A: envVars in agentcore.json** (not recommended for secrets)
```json
{
  "runtimes": [{
    "envVars": [
      {"name": "API_KEY", "value": "xxx"}
    ]
  }]
}

⚠️ Warning: This file is typically committed to git. Do not store secrets here.

Option B: AWS Secrets Manager (recommended)

import boto3
client = boto3.client("secretsmanager")
secrets = json.loads(client.get_secret_value(SecretId="my-secret")["SecretString"])


2. **Add warning in CLI output:**

$ agentcore deploy
⚠️ Note: .env.local is not deployed. Use envVars in agentcore.json or AWS Secrets Manager for production credentials.


### Additional Context
- This is a common pattern confusion in serverless deployments
- Similar tools (Vercel, Netlify) clearly document local vs production env behavior
- AgentCore CDK constructs don't have built-in Secrets Manager integration

### Related Issues
- Missing: Built-in pattern for AWS Secrets Manager integration
- Missing: Example templates showing production credential management
Lingua principale
TypeScript
Stelle
291
Fork
96
Merge medio
20h 50m
PR unite (30g)
214

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di aws/agentcore-cli

Tutte le issue di aws/agentcore-cli

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.