Llega un desarrollador nuevo, o empieza un colaborador externo, y lo primero que necesita es el .env que hace funcionar el proyecto. Ese archivo suele mezclar ajustes inofensivos con los valores más sensibles que tiene el equipo, y por eso acaba tantas veces en un mensaje directo o en un correo con un adjunto llamado «config».
Para enviar de forma segura un archivo de configuración a un desarrollador, trátalo como dos cosas: la configuración, que puede viajar por cualquier canal, y los secretos, que viajan una sola vez por un canal que no guarda copias. Esta guía explica cómo separar las dos partes, cómo enviar la parte secreta y qué decirle al desarrollador para que el archivo siga a salvo cuando le llegue.
Lee el archivo como si cada línea fuera pública
Abre el archivo y clasifica cada línea en uno de dos grupos.
- Configuración: niveles de registro, puertos, indicadores de funciones, endpoints que no son de producción, ID de cliente públicos. Esto va en el repositorio como archivo de ejemplo y puede enviarse como quieras.
- Secretos: contraseñas de bases de datos, claves de API, secretos de firma, claves privadas, secretos de cliente de OAuth y cualquier cosa que dé acceso. Busca
PASSWORD,SECRET,TOKEN,KEYyPRIVATE, y después lee el resto, porque una cadena de conexión con la contraseña dentro no avisa de lo que es.
Luego pregúntate qué va a hacer el desarrollador. El desarrollo local contra staging necesita los valores de staging. No necesita las claves de producción, ni la clave real del proveedor de pagos solo porque el archivo resulte tener una.
Deja los secretos fuera del archivo del repositorio
El .env.example que se sube al repositorio documenta cada variable con un marcador de posición. Los valores reales se inyectan en tiempo de ejecución desde el entorno, un gestor de secretos o el almacén de secretos de la propia plataforma. Con este patrón, lo que envías son solo los valores secretos, y la copia local del desarrollador es el único sitio donde están todos juntos.
# .env.example (committed)
DATABASE_URL=postgres://app:CHANGE_ME@staging-db.internal:5432/app
STRIPE_SECRET_KEY=sk_test_CHANGE_ME
SESSION_SECRET=CHANGE_ME
LOG_LEVEL=debug
Añade .env a .gitignore antes de que nadie tenga uno real, y plantéate un hook de pre-commit como gitleaks para que un commit con secretos falle enseguida.
Dale al desarrollador sus propias credenciales siempre que puedas
Una entrega también es una ocasión para dejar de compartir. Si la base de datos admite usuarios individuales, crea uno para el desarrollador con los permisos que necesita su trabajo y una fecha de expiración. Si la API ofrece claves restringidas, emite una a su nombre. La guía sobre el acceso temporal a la base de datos para colaboradores externos explica ese patrón. Las credenciales creadas para una persona se pueden retirar a esa persona sin afectar a nadie más.
Cómo enviar los valores secretos
Hay dos vías que funcionan, y ninguna deja el archivo en un mensaje.
Pega las líneas secretas en un enlace de un solo uso. Abre la herramienta de enlaces secretos, pega solo las líneas que contienen secretos y crea el enlace. El texto se cifra en tu navegador antes de guardarse, la copia almacenada se destruye la primera vez que se abre el enlace y, si nadie lo abre, el enlace expira a la hora, a las 24 horas o a los siete días. Sin cuenta caben hasta 10.000 caracteres, que dan para la mayoría de los archivos .env varias veces.
Adjunta el archivo completo a un enlace secreto. Con una sesión iniciada en una cuenta de LinkPilot puedes adjuntar a un secreto hasta tres archivos de 9 MB cada uno. Cada archivo se cifra en tu navegador con una clave derivada de la clave del propio secreto, así que el servidor nunca tiene el archivo sin cifrar, y el adjunto se elimina tras la única descarga. Es la mejor vía cuando el archivo tiene que llegar idéntico byte a byte, por ejemplo un archivo JSON de cuenta de servicio o un almacén de claves.
En los dos casos:
- Verifica la identidad del desarrollador por el canal de contratación o del contrato, no por la dirección que pidió el archivo.
- Ajusta la expiración al margen que de verdad va a usar: una hora si está esperando, un día si está en otra zona horaria.
- Pon el límite de visualizaciones en uno.
- Añade una frase de contraseña con una cuenta Pro para los valores de producción, y envíala por otro canal.
- Envía el enlace con una nota de una línea que diga qué es y dónde va el archivo. Envía la configuración no secreta aparte o remite al archivo de ejemplo del repositorio.
Una invitación a la bóveda es la mejor vía cuando el desarrollador es una contratación fija y tu equipo ya usa un gestor de secretos con acceso por desarrollador. Usa el enlace de un solo uso mientras eso no esté configurado, y para quien nunca vaya a estar en la bóveda.
Dile al desarrollador dónde va el archivo
Una entrega limpia puede acabar mal si el archivo termina en una carpeta compartida. Envía estas indicaciones junto con los datos de conexión:
- Guárdalo como
.enven la raíz del proyecto y en ningún otro sitio. Comprueba que.gitignorelo cubre antes del primer commit. - No pegues valores en tickets ni en el chat para preguntar si son correctos. Si falta una variable o no es válida, indica solo su nombre, y quien la envió emitirá un valor nuevo.
- Rotación al terminar. Cuando acabe el proyecto, los valores de ese archivo se rotan. Dilo desde el principio para que nadie se sorprenda.
Confirma y después limpia
Pide al desarrollador que confirme el nombre del archivo, el entorno y una marca no secreta, como un comentario de versión en la primera línea. Si un enlace de un solo uso indica que se abrió antes de que él llegara, da por expuestos todos sus valores y rótalos.
Cuando termine la entrega, revoca cualquier enlace que no se haya abierto, elimina cualquier copia temporal que hayas guardado y anota quién recibió los valores de qué entorno y cuándo. Ese registro es el historial de auditoría. El archivo en sí solo debería existir en el dispositivo que lo necesita.