Cómo organizar un repositorio de GitHub en Magento 2

Un repositorio de GitHub bien organizado en Adobe Commerce (Magento 2) incluye solo lo que el equipo escribe y configura, como composer.json, composer.lock, el código propio y app/etc/config.php, y deja fuera lo que se genera o es sensible, como vendor, generated, var y env.php. Esa disciplina protege las credenciales de la tienda y hace que cada despliegue sea reproducible.

Imagine una aseguradora que lanza el lunes una campaña de renovación de pólizas en su tienda en línea. El viernes por la tarde un desarrollador corrige un error directamente en el servidor de producción para no perder tiempo. El sábado, un compañero despliega la versión del repositorio, que no incluye esa corrección, y el error regresa justo cuando la campaña empieza a generar tráfico. Nadie sabe con certeza qué código está en producción, quién lo cambió ni cómo volver atrás. El director de tecnología promete una explicación para el comité del martes, y la directora comercial quiere saber una sola cosa, cuánto costó ese fin de semana.

La escena no depende de la plataforma, sino de la ausencia de un acuerdo sobre qué se guarda, dónde y quién lo aprueba. Cuando se crea una instalación de Magento 2 aparecen muchas carpetas y archivos en el directorio de la instalación, y este artículo ayuda a entender cuáles deben agregarse al repositorio del proyecto y cuáles no son necesarios o incluso pueden ser problemáticos. Primero se explica por qué es un tema que interesa a la dirección y después se recorre, archivo por archivo, una estructura recomendada para Adobe Commerce, la plataforma antes conocida como Magento.

¿Por qué el repositorio es un tema de la dirección?

Un repositorio es la memoria del proyecto. Cuando funciona bien, cualquier persona autorizada puede ver qué cambió, quién lo cambió y por qué, y puede reconstruir la tienda en un ambiente nuevo. Cuando funciona mal, la empresa depende de la memoria de dos o tres personas, los despliegues se vuelven eventos de riesgo y la incorporación de un desarrollador nuevo toma semanas en lugar de días. Para quien responde por la continuidad del negocio, esa dependencia es un riesgo operativo comparable al de un proveedor único sin contrato.

La investigación sobre entrega de software que dio origen al libro Accelerate identifica el control de versiones como una de las 24 capacidades que mejoran el desempeño de la entrega. Según el resumen publicado por IT Revolution, se trata de usar un sistema de control de versiones, como GitHub, para todos los artefactos de producción, lo que incluye el código de la aplicación, las configuraciones y los scripts de compilación y de ambientes. El mismo texto señala que el conjunto de capacidades mejora el desempeño de entrega de forma estadísticamente significativa. No es un argumento para obsesionarse con la herramienta, pero sí para exigir que las decisiones sobre el repositorio estén escritas y se cumplan.

En una tienda de Adobe Commerce esto importa más que en otros sistemas por una razón concreta. La instalación mezcla código propio, módulos de terceros, archivos generados automáticamente, contenido multimedia del catálogo y configuraciones con datos sensibles. Si todo se sube sin criterio, el repositorio se vuelve pesado, lento y peligroso. Si se sube muy poco, nadie puede reproducir el sitio. La tarea consiste en trazar bien esa línea.

¿Qué es GitHub y qué hay dentro de una instalación de Magento 2?

GitHub es una plataforma que permite administrar el código, hacer seguimiento de los cambios y mantener el orden en proyectos complejos. Existen alternativas equivalentes, como GitLab o Bitbucket, y todo lo que sigue aplica igual a ellas. Para sacar el máximo provecho conviene un entendimiento básico de Git, aunque los conceptos son útiles para cualquiera que quiera aprender acerca de los archivos y carpetas de un proyecto de Magento 2.

Un proyecto típico incluye múltiples módulos, temas personalizados, extensiones de terceros y archivos de configuración, y de esa mezcla nace la dificultad de gestionarlo. Para ubicarse, el punto de partida es el repositorio por defecto de Magento 2.4, que muestra la estructura base de carpetas y archivos que trae cualquier instalación.

¿Qué archivos y carpetas deben estar siempre en el repositorio?

Hay cuatro elementos que no admiten discusión. El primero es composer.json, que contiene la información de los módulos y sus dependencias en el proyecto. El segundo es composer.lock, que especifica las versiones exactas de los componentes, y es lo que permite que el ambiente de pruebas y el de producción instalen exactamente lo mismo. El tercero son los archivos .htaccess de la raíz y de las carpetas pub, pub/media y pub/static, que contienen encabezados y directivas para que el servidor pueda ejecutar las solicitudes de los usuarios en el sitio web. El cuarto es .gitignore, que reúne las especificaciones de todos los archivos y directorios que no deben incluirse en el repositorio, ya sea porque se generan en el proceso de compilación o porque consumen espacio innecesario.

Conviene detenerse en el último, porque es el que más se subestima. Un buen .gitignore es una política de la empresa escrita en un archivo: define de antemano qué nunca debe llegar al repositorio, de modo que nadie tenga que acordarse de ello un viernes por la tarde. La documentación de Adobe sobre el sistema de desarrollo lo confirma al indicar que el archivo .gitignore resuelve la mayor parte de las exclusiones necesarias.

¿Qué más puede incluirse y con qué cuidado?

Además de los cuatro elementos anteriores, un proyecto suele versionar sus propias piezas de código. En app/code se ubican los módulos del proyecto que no fueron instalados mediante Composer, y en app/design se encuentran los temas disponibles en el comercio. Ambos son el activo diferencial de la tienda, lo que la distingue de otra instalada con el mismo producto, y por eso deben estar protegidos por el historial de cambios.

La carpeta app/etc exige más atención porque mezcla dos tipos de archivos. Por un lado está config.php, que según la documentación de archivos de despliegue de Adobe contiene la lista de módulos, temas y paquetes de idioma instalados, además de configuraciones compartidas, y se recomienda incorporarlo al control de versiones y usarlo en los sistemas de desarrollo, pruebas y producción. Por otro lado está env.php, que contiene los ajustes específicos de cada ambiente. En la práctica de los equipos de desarrollo, ese archivo concentra las credenciales de acceso a la base de datos y datos de acceso al sitio administrativo, y por eso la guía de Adobe para el sistema de desarrollo pide excluirlo del control de versiones junto con las carpetas vendor, generated y pub/static. Si la empresa decide guardar la carpeta completa como respaldo, solo debería hacerlo en un repositorio privado y accesible únicamente a personas autorizadas, y con la certeza de que ninguna credencial viaja con él.

Queda pub/media, que contiene las imágenes del catálogo, de los bloques de contenido y otros archivos públicos como PDFs o videos. Debido a su tamaño, a menudo se excluye del repositorio por las limitaciones de almacenamiento que ofrecen los repositorios remotos como GitHub, y se recomienda guardar esos archivos en servicios como Google Drive, Dropbox o AWS S3. Para un comercio con un catálogo grande, esta separación también tiene una razón de negocio: el contenido cambia a diario por decisión del equipo comercial, mientras que el código cambia por decisión del equipo técnico, y mezclar ambos ritmos complica las revisiones. Si la tienda carga productos de forma masiva, la guía sobre el proceso de carga de productos explica cómo ordenar ese flujo.

¿Qué debe quedar fuera del repositorio?

Los archivos y carpetas que conviene evitar agregar deben estar en .gitignore. La carpeta pub/static, con excepción del archivo .htaccess, contiene los archivos estáticos generados en el proceso de setup:static-content:deploy, por lo que cargarlos al repositorio es innecesario. La carpeta generated se autogenera en la compilación del sitio, así que no hay motivo para agregarla. En var se almacenan contenidos de carácter temporal, bitácoras y reportes. Puede resultar útil respaldarla, pero por ser grande y volátil se recomienda usar un servicio de almacenamiento dedicado.

La carpeta vendor no debe modificarse manualmente, solo mediante Composer, de modo que composer.json y composer.lock bastan para determinar su contenido sin necesidad de subir el código en sí. La carpeta lib alberga librerías usadas por módulos y componentes. Podría ser necesario agregarla, pero se recomienda usar Composer para orquestar las librerías, en cuyo caso, al igual que con vendor, no hace falta subir el código.

Un matiz merece mención porque evita malentendidos entre equipos. La documentación de Adobe para el sistema de compilación describe un esquema distinto, en el que el repositorio de compilación sí versiona config.php, generated, pub/media y pub/static porque el código ya compilado se promueve de un ambiente a otro sin volver a generarse. Son dos modelos válidos para dos formas de desplegar. Lo que no es válido es mezclarlos sin saberlo, por ejemplo excluir generated en un equipo que despliega como si estuviera incluido. La dirección no necesita decidir cuál usar, pero sí exigir que el equipo lo haya decidido y lo documente.

Prácticas que evitan errores y ordenan el trabajo

Además de la estructura, cuatro prácticas facilitan la administración del código y de los recursos del repositorio. La primera es usar una rama para cada modificación. Crear una rama es rápido y fácil, permite controlar versiones, hacer pruebas de integración, analizar los cambios de forma ordenada y, por supuesto, evitar que errores graves lleguen a la rama principal. Para una aseguradora como la de nuestro ejemplo, esa disciplina habría convertido la corrección del viernes en un cambio revisado en lugar de una edición directa en producción.

La segunda es mantener la consistencia entre los ambientes de desarrollo, pruebas y producción. Es común que con el tiempo los ambientes acumulen diferencias porque no están en los mismos commits o versiones del repositorio. Cuando las inconsistencias son muchas, es una señal de malas prácticas de desarrollo, porque para probar y modificar con seguridad se necesitan ambientes lo más idénticos posible. Este procedimiento pertenece al ámbito de DevOps, que busca agilizar el desarrollo, la integración y las pruebas, y reducir errores en el proceso. La nota sobre cuándo actualizar el software a la última versión disponible muestra por qué ese orden es lo que permite actualizar sin sobresaltos.

La tercera es agregar un archivo README.md, cuyo propósito es explicar la naturaleza y el contenido del repositorio y ayudar a los nuevos colaboradores a entender y utilizar el código con eficacia. La cuarta es escribir mensajes de commit significativos. Mensajes genéricos como bugfix o cambios v4 no permiten a otras personas identificar a simple vista el propósito del cambio, y todos olvidamos con el tiempo, así que dedicar unos segundos a escribir mensajes claros cada vez que se hace un commit ahorra horas cuando hay que investigar un incidente.

Definir convenciones para ramas, solicitudes de cambio y documentación permite que los equipos trabajen de forma más ordenada y eviten conflictos innecesarios. Separar el código de la plataforma del código personalizado, mantener historiales limpios y usar nombres descriptivos en las ramas reduce la confusión y evita acumular deuda técnica. Una documentación clara dentro del repositorio fomenta además la transparencia y la coherencia entre todos los colaboradores.

Qué significa para la alta dirección

Para quien responde por la eficiencia, un repositorio ordenado reduce el costo de cada despliegue y el de cada persona nueva que se incorpora. Cuando todo está en su sitio, publicar una corrección deja de ser una operación de riesgo que se pospone hasta el fin de semana y pasa a ser una rutina que se puede hacer en horario laboral, con respaldo y con posibilidad de volver atrás. Esa previsibilidad se traduce en menos horas extra, menos incidentes y menos dependencia de personas clave.

Para quien responde por la relación con el cliente, la conexión es directa. Las campañas, las promociones y los cambios de precio dependen de que la tienda funcione el día que se prometió. Un error que reaparece por un despliegue mal hecho se convierte en una venta perdida o en un cliente que no vuelve, y la tienda de nuestra aseguradora lo ilustra bien. Para quien responde por el riesgo y el cumplimiento, el asunto es todavía más serio. Una credencial de base de datos publicada por error en un repositorio es un incidente de seguridad, con consecuencias legales y reputacionales que pueden afectar a clientes y a socios, y una de las defensas más baratas es una política clara de qué no se sube nunca. La nota sobre ciberseguridad esencial para su tienda en Adobe Commerce profundiza en esas medidas.

Cómo empezar el lunes

Un consultor con experiencia en estas operaciones sugeriría comenzar con una revisión de media hora. Pida al responsable técnico que le muestre el archivo .gitignore, la lista de ramas activas y la última vez que se restauró la tienda desde cero en un ambiente de pruebas. Si alguna de las tres respuestas incomoda, ya tiene la agenda del trimestre. Después, solicite que por escrito se definan tres cosas, qué se versiona, qué se excluye y dónde viven los archivos que no se versionan, como las imágenes del catálogo y las credenciales.

El segundo paso es acordar quién aprueba los cambios que llegan a producción y con qué evidencia. No hace falta una burocracia pesada, basta una regla simple, como que ningún cambio llegue a la rama principal sin revisión de otra persona. Por último, revise el repositorio con una pregunta sencilla, si mañana el servidor se perdiera, cuánto tardaría el equipo en levantar la tienda otra vez. Si la respuesta es en horas y con un procedimiento documentado, la empresa está bien protegida. Si es en días y depende de una persona, hay trabajo por hacer. Para el flujo de trabajo del equipo, la guía para crear un webservice en Adobe Commerce es un buen ejemplo de módulo propio que debe vivir en el repositorio.

Cómo le ayuda ICX

ICX Consulting, firma de consultoría en experiencia del cliente y estrategia comercial con sede en Miami, ayuda a empresas de Estados Unidos y Latinoamérica a definir cómo se organiza el trabajo alrededor de su tienda antes de que los desarrollos se multipliquen. Desde nuestra práctica de arquitectura empresarial y de ciberseguridad establecemos los acuerdos de gobierno que protegen a la empresa, y los implementamos sobre Adobe Commerce con nuestro equipo de comercio electrónico B2C y de comercio electrónico B2B. ¿Quiere saber qué tan reproducible es hoy su tienda? Solicite un diagnóstico con un consultor de ICX.

Para definir roles, responsabilidades y procesos del equipo que mantiene su tienda, el Kit Modelo Operativo Objetivo (TOM) de ICX ofrece un diagnóstico, una plantilla de situación actual y futura y una hoja de ruta.

Preguntas frecuentes

¿Se puede subir app/etc/env.php a GitHub?

No se recomienda. Es el archivo de ajustes específicos de cada ambiente, y según la práctica habitual contiene credenciales de la base de datos y del acceso administrativo. La guía de Adobe para el sistema de desarrollo pide excluirlo del control de versiones. El archivo que sí se comparte entre ambientes es config.php.

¿Qué diferencia hay entre config.php y env.php?

Config.php reúne la lista de módulos, temas y paquetes de idioma instalados y las configuraciones compartidas, y se versiona para usarse igual en todos los ambientes. Env.php guarda lo que cambia entre desarrollo, pruebas y producción. Separarlos permite desplegar el mismo código con configuraciones distintas.

¿Las imágenes del catálogo deben ir en el repositorio?

Por lo general no. La carpeta pub/media crece con el catálogo y los repositorios remotos tienen límites de almacenamiento. Lo habitual es guardarla en un servicio de almacenamiento dedicado, como AWS S3, con respaldos propios. La excepción son modelos de despliegue específicos que la versionan de forma deliberada.

¿Sirve esta estructura si usamos GitLab o Bitbucket?

Sí. Las reglas sobre qué versionar y qué excluir dependen de cómo funciona Adobe Commerce y no de la herramienta que aloje el código. Lo que cambia son detalles de la plataforma, como la forma de configurar las revisiones de cambios y los permisos de cada rama.

Un repositorio ordenado rara vez aparece en un informe de resultados, pero se nota el día en que la tienda tiene que recuperarse de un error en plena campaña. Si quiere que los despliegues de su tienda sean previsibles, que sus credenciales estén protegidas y que su equipo pueda crecer sin depender de una sola persona, hable con un consultor de ICX y revise junto con él la forma en que hoy se cuida el código de su negocio.