Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto Apto para principiantes
  • ¿Algo no está bien?
#1,378 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
2/5
Tiempo estimado
Medio día
Aptitud para principiantes
74/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
aws
Área
cli, cloud, documentation

Línea de trabajo

Comienza con la sección de variables de entorno del README y la documentación sobre agentcore dev y agentcore deploy; revisa cómo se describen actualmente .env.local, envVars en agentcore.json y AWS Secrets Manager. Se considera terminado cuando el alcance exclusivamente local, el comportamiento del despliegue y las opciones más seguras para producción queden explícitos, y se aborde cualquier advertencia solicitada de la CLI si se identifica el punto de entrada relevante.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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
Lenguaje dominante
TypeScript
Estrellas
291
Forks
96
Merge medio
20 h 50 min
PR fusionados (30 d)
214

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de aws/agentcore-cli

Todos los issues de aws/agentcore-cli

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.