How to Organize a Magento 2 (Adobe Commerce) Repository on GitHub

To organize a Magento 2 repository on GitHub, commit only what your team owns and can rebuild from, namely composer.json and composer.lock, the shared configuration in app/etc/config.php, custom modules, themes and server directives. Leave out everything Composer or the build generates, plus credentials and media. Then protect your main branches and release through reviewed pull requests.

This sounds like a developer concern, and the details are. The consequences are not. For any company that sells through Adobe Commerce, formerly Magento Commerce, the repository is where the store's revenue engine lives. A disorganized repository means slower releases, risky deployments during peak season, credentials exposed to people who should not have them, and a store that only one developer or one agency truly understands. A well-organized one means faster improvements to the customer experience, safer changes and real ownership of a strategic asset.

Why should executives care how a Magento 2 repository is organized?

Every promotion, checkout improvement, integration and security patch passes through the repository before it reaches customers. Its structure determines how quickly and safely the business can change the store.

Research by DORA, the DevOps Research and Assessment program, measures software delivery with a small set of metrics, including deployment frequency, change lead time, change fail rate and failed deployment recovery time. Its guide to the software delivery metrics highlights a finding that matters to any commerce leader. Speed and stability are not trade-offs, and the best teams do well on both. Clean version control is one of the foundations of that performance.

In practical terms, a well-organized repository gives leadership four things.

• Ownership. The company, not a single developer or vendor, holds a complete and understandable copy of its custom code.
• Speed. Teams can ship improvements to search, checkout or pricing in days instead of waiting for risky, bundled releases.
• Security. Credentials and sensitive settings stay out of source control, reducing the impact of any leak.
• Continuity. New team members or a new implementation partner can understand the project quickly, which lowers switching costs.

There is also a commercial angle that is easy to overlook. When an implementation partner keeps the only working copy of the code, or when the repository cannot be understood without its original authors, the company loses negotiating power and pays for it in every future change. A clean, company-owned repository keeps that leverage where it belongs.

What version of Magento 2 should the repository target today?

Many older guides were written for Magento 2.4.x releases that are no longer current. According to Adobe's released versions page, the current general availability release line is Adobe Commerce 2.4.9, released in May 2026 with regular support through May 2029, while 2.4.8 and 2.4.7 continue to receive security patches with earlier end-of-support dates. The repository structure described below applies across the 2.4 line. What matters for leadership is the support calendar. A store running an unsupported version accumulates security and compliance risk, and its repository should make upgrades routine rather than exceptional.

Our guide to Magento migration and version upgrades covers how to plan that process.

Which files belong in a Magento 2 repository on GitHub?

A default Adobe Commerce or Magento Open Source installation contains many folders. The image below shows a typical project root. Only part of it should be versioned.

The configuration rule that prevents most incidents

The most important distinction is inside app/etc. Adobe's documentation on deployment configuration states that the shared configuration in app/etc/config.php should be in source control, while the system-specific configuration in app/etc/env.php should not, because it holds settings unique to each environment and sensitive values. Sensitive settings can be managed through environment variables or the dedicated command for sensitive configuration. Older advice to commit the entire app/etc folder to a private repository is no longer good practice. A private repository still has many readers, and credentials should never depend on who has access to code.

Why vendor and generated code stay out

The vendor directory is fully determined by composer.json and composer.lock. Committing it inflates the repository, hides real changes inside thousands of third-party files and invites manual edits that the next upgrade will silently overwrite. The same logic applies to generated, pub/static and var. Anything the build can recreate should be recreated by the build. The var folder can be worth backing up, but its contents are large and volatile, so a dedicated storage service is a better home than Git. The lib folder holds libraries used by modules and components; it may occasionally need to be versioned, but when Composer orchestrates those libraries, as with vendor, the code itself does not need to be in the repository.

Start from the base .gitignore

Magento Open Source ships with a base .gitignore file that already excludes most generated and environment-specific content. Use it as the starting point, review it after each upgrade and add project-specific rules, such as local IDE folders or deployment artifacts, rather than writing one from scratch. When a file on the ignore list genuinely needs to be versioned, the team should document why, so that the exception is a decision and not an accident.

Where media belongs

Product images and downloadable files change constantly and can grow very large. Remote repositories such as GitHub also impose storage limits, so these files belong in managed storage with its own backup policy, such as AWS S3, Google Drive or Dropbox, not in Git. This also keeps the repository fast to clone, which matters every time a new developer or partner joins the project.

How should the team work with branches and releases?

Structure is only half of the discipline. The other half is how changes move from a developer's laptop to production.

1. Use a branch for every change. Each fix, feature or upgrade lives in its own branch until it is reviewed. This isolates risk and makes every change traceable.
2. Protect the main and release branches. GitHub's protected branches let administrators require a set number of approving reviews before merging, require status checks to pass and restrict who can push. These three settings alone prevent most accidental releases.
3. Automate checks. Run code standards, static analysis and automated tests on every pull request so that reviewers focus on business logic.
4. Keep environments consistent. Development, staging and production should run the same code and the same dependency versions. When environments drift apart, sitting on different commits or versions and filling up with test products, sections or accounts, tests stop predicting what customers will see. Large inconsistencies are a sign of weak development practices, and closing them is exactly what DevOps aims for: faster development, integration and testing with fewer errors.
5. Write meaningful commit messages. Explain the purpose of each change. Generic messages such as "bugfix" or "version X changes" help no one six months later, and everyone forgets details over time, so a few extra seconds per commit pay off.
6. Document the project. A README that explains how to install, configure and deploy the store shortens onboarding and reduces dependence on specific people.
7. Tag releases. Each production deployment should map to a tagged version, so that rolling back is a decision, not an investigation.

A simple branching model for commerce teams

Complex branching strategies rarely survive contact with a busy commerce calendar. Most teams do well with a model that everyone can explain in a minute.

• Main. Always reflects what is running in production and is the only source for production deployments.
• Feature branches. Short-lived branches for each change, merged through reviewed pull requests once tests pass in staging.
• Hotfix branches. Created from main to fix urgent production issues, then merged back so that the fix is never lost.
• Release tags. Mark every production deployment, which makes audits, rollbacks and conversations with partners far simpler.

Every project is different, and there are no definitive rules about what must or must not be versioned. Applying the principles above, however, avoids most problems and lets the team work in a more orderly and secure way. The same discipline applies to everyday store configuration, from features such as configuring the wishlist in Magento to larger releases.

Whatever model the team chooses, the business should also agree on a release calendar. Freezing non-essential changes before peak sales periods, and scheduling upgrades in quieter weeks, protects revenue at the moments when it matters most.

What this means for the C-level

• Convert. A disciplined repository shortens the time between an idea to improve checkout or search and its arrival in front of customers.
• Serve. Fewer failed deployments mean fewer outages, fewer broken carts and fewer service tickets during critical sales periods.
• Retain. A stable store that improves steadily is part of the experience that keeps customers buying again.
• Efficiency. Clear structure and automation reduce rework, lower onboarding time and make it realistic to change implementation partners if needed.

Repository health checklist for commerce leaders

Ask your technology lead or implementation partner to confirm these points. None requires a large project.

1. Does the company own the repository? It should live in an organization account controlled by the business, not a personal or vendor account.
2. Are credentials out of source control? Confirm that env.php, auth.json and any keys are excluded and that past exposures have been rotated.
3. Is the version supported? Check the installed release against Adobe's support calendar and agree on an upgrade plan.
4. Are main branches protected? Reviews, passing checks and restricted push rights should be mandatory.
5. Can the store be rebuilt from the repository? A clean environment should be reproducible from Git, Composer and documented steps.
6. Who has access, and why? Review repository permissions at least when people or partners change, and remove access that is no longer needed.
7. Are delivery metrics tracked? Deployment frequency, lead time, change fail rate and recovery time show whether the team is getting faster and safer.

How ICX helps

ICX Consulting is a commercial strategy and customer experience firm headquartered in Miami, serving companies in the United States and Latin America. We help leadership teams define what their digital commerce channel must achieve for revenue, customer experience and efficiency, and then implement it on Adobe Commerce through our B2B ecommerce consulting and implementation practice, with governance, security and delivery practices that keep the store under the client's control. Our article on essential cybersecurity for your store in Adobe Commerce complements this guide.

If you are evaluating who should build or maintain your store, we invite you to use the ICX Implementer Partner Selection Toolkit, which helps you compare partners on the criteria that protect your investment.

Frequently asked questions

Should app/etc/env.php ever be committed to GitHub?

No. Adobe's documentation states that env.php holds system-specific configuration and should not be in source control, because it contains environment settings and sensitive values such as database credentials. Each environment should have its own env.php, with sensitive settings managed through environment variables or the sensitive configuration command, while config.php is shared through the repository.

Why not commit the vendor folder to be safe?

Because composer.lock already guarantees that every environment installs exactly the same versions. Committing vendor makes the repository heavy, hides your real changes among third-party code and encourages direct edits that are lost on the next upgrade. Customizations belong in your own modules or in patches managed through Composer.

Does this structure apply to Adobe Commerce on cloud infrastructure?

The principles are the same, but cloud projects add their own configuration files and a Git-based deployment workflow defined by Adobe. Teams on Adobe Commerce on cloud infrastructure should follow Adobe's cloud project structure for those files and apply the rules in this guide to custom code, credentials and generated content.

Do these practices only apply to GitHub?

No. The same structure and rules work on GitLab, Bitbucket or Azure Repos, since they rely on Git itself and on how Adobe Commerce separates code, configuration and generated content. Branch protection, required reviews and automated checks exist on all major platforms, so the choice of service should follow the company's existing tools and security policies.

How often should a Magento store be upgraded?

Often enough to stay within Adobe's support window and to apply security patches promptly. Teams with an organized repository, automated checks and consistent environments can treat upgrades as regular maintenance rather than a disruptive project, which lowers both risk and total cost over the life of the store.

A store that the business can change quickly and safely is a competitive advantage that customers feel in every visit. Want to know whether your store is built and governed to move at the speed of your business? Request a diagnostic with an ICX consultant.