TLDR: Los despliegues preview fallaban por variables de entorno ausentes y scopes del token mal configurados. He consolidado la gestión de variables con GitHub Environments y secretos encriptados y añadido un paso preflight para validar las variables requeridas antes del deploy para fallar rápido si algo falta.

Contexto: Estaba integrando un dashboard Next.js con Supabase y Vercel. En local todo funcionaba pero la CI/CD empezó a fallar en los builds preview. La causa principal fue que variables de entorno y scopes del token no fluían correctamente en GitHub Actions, provocando despliegues vacíos o fallidos.

Solución resumida. 1) Centralizar env y secretos: usar GitHub Environments Preview y Production para valores dependientes del entorno y almacenar en GitHub Secrets solo lo imprescindible como VERCEL_TOKEN VERCEL_ORG_ID VERCEL_PROJECT_ID SUPABASE_URL SUPABASE_ANON_KEY y las variables NEXT_PUBLIC necesarias en tiempo de build. Para proyectos y aplicaciones a medida podemos enlazar buenas prácticas con aplicaciones a medida.

2) Paso de preflight: añadir una tarea al pipeline que compruebe explícitamente la presencia de cada variable requerida y que haga exit 1 si alguna falta, así se detecta el problema antes de intentar el deploy y se evita ruido en Vercel. 3) Desplegar con token con scope limitado: crear VERCEL_TOKEN con permisos mínimos por proyecto para mejorar seguridad. 4) Flujo típico en Actions: disparar en pull_request sobre main, job preview en ubuntu-latest con environment preview y permisos mínimos, pasos: checkout, setup node 20, preflight de variables, npm ci, npm run build con NEXT_PUBLIC_SUPABASE_URL y NEXT_PUBLIC_SUPABASE_ANON_KEY inyectadas, y finalmente npx vercel pull build deploy usando el VERCEL_TOKEN almacenado en secrets.

Buenas prácticas y gotchas: no mezclar variables NEXT_PUBLIC con claves de servidor; mantener fuera del repositorio la service_role de Supabase salvo que sea absolutamente necesario; crear las variables en Vercel dentro del entorno correcto Preview o Production o el pull devolverá valores vacíos; usar tokens con el scope mínimo para reducir riesgo.

Validación del drift entre Vercel y GitHub: implementar una comprobación periódica que consulte la API de Vercel y compare con los secretos de GitHub Actions para detectar diferencias y alertar. Para escaneo ligero de secretos antes del merge recomiendo integrar un escáner como gitleaks en un job de pre-merge o usar acciones ya disponibles en el marketplace y hooks pre-commit para evitar que credenciales lleguen al repositorio. También es recomendable activar GitHub Secret Scanning si está disponible en la organización.

En Q2BSTUDIO, empresa de desarrollo de software y aplicaciones a medida, ayudamos a empresas a implementar pipelines robustos y seguros, con experiencia en inteligencia artificial, ciberseguridad y servicios cloud aws y azure. Si buscas soporte para asegurar tus despliegues, optimizar la gestión de secretos o integrar soluciones de inteligencia de negocio y power bi, contamos con servicios para ia para empresas, agentes IA y más. Consulta nuestras soluciones de inteligencia artificial en Inteligencia artificial para empresas o contacta para una auditoría de CI/CD y ciberseguridad.

Palabras clave incluidas para mejorar posicionamiento: aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA, power bi.