A small feature can turn into a coordination problem when its code, tests, and deployment configuration live in different projects. The same team may have to prepare several merge requests, arrange their release order, and explain the relationship each time. At the other extreme, a project can grow to include services whose teams need different access and release schedules.
The right arrangement depends on how the work happens. Looking at a few recent changes will tell you more than choosing a repository pattern first. You're looking for places where keeping work together would remove unnecessary handoffs, or where separating it would let a team take responsibility without waiting on everyone else.
Follow a change from the request to its release
A feature that crossed several projects is a good starting point. The people who delivered it can explain which changes had to happen together, who reviewed them, and what determined the release order. An incident or urgent fix may reveal a different problem: perhaps the team responsible for the service couldn't change its configuration without finding another project's maintainer.
Those conversations help distinguish collaboration from coordination imposed by the project structure. A database specialist reviewing an application change doesn't necessarily call for a separate project. An independently maintained library with several consumers probably does, because its compatibility promises and releases extend beyond one application.
The same reasoning applies to ownership. A project should make it clear who accepts changes, who releases them, and who responds when something goes wrong. These responsibilities can belong to different teams. What matters is that contributors can find them and that the teams have agreed how work passes between them.
Keep together what usually changes together
Application code, its tests, and the documentation needed to operate it often benefit from sharing a project. A merge request can then explain a behavior change alongside the checks and instructions that make it ready to release. Reviewers don't have to reconstruct the change from several unrelated conversations.
Separate projects make more sense when they support a real difference in responsibility. A shared library may have its own maintainers and release schedule. Customer work may have access or legal requirements that don't apply to the rest of the product. Production configuration may be reviewed by a team that doesn't need to approve every application change.
Separation also creates ongoing work. For an application and its deployment configuration, the teams need a clear connection between the application version and the configuration that deploys it. For a library, consumers need to know which versions they can adopt and how compatibility is checked. If every release still requires the same people to coordinate all the projects, the split may have moved the work rather than made it easier.
Group placement is a related decision, but it answers a different question: which access and shared settings should a project inherit? A group structure that fits your teams explains that choice. A change in reporting lines alone doesn't have to trigger a repository move.
Address repository friction before reorganizing
A slow pipeline isn't enough on its own to justify splitting a repository. It helps to separate time spent fetching code from time spent running jobs. Large files, long history, repeated clones, and unnecessary jobs call for different remedies. A split can leave the expensive work in place and add coordination between repositories.
For a repository containing several applications, jobs that run only for affected work can reduce waiting. Shared code still needs checks that exercise its consumers; skipping those checks would trade faster feedback for missed failures. GitLab's monorepo guidance covers repository and pipeline techniques you can consider before changing ownership or release arrangements.
A split is more convincing when a team can describe what becomes independent afterward. “We can release this service without scheduling a release with the other teams” is a stronger reason than “this repository is large.” Conversely, repeated changes across the same projects may be a reason to bring them together.
Introduce a move without losing the surrounding work
Moving code is only part of changing a project's home. Merge request discussions, issues, registry references, webhooks, runners, credentials, and downstream jobs may all depend on the existing project. Before choosing a transfer or migration method, agree which of these must be preserved and who will check them. Different methods preserve different information, so a successful Git clone isn't a complete migration check.
A project transfer also changes inherited access: membership inherited from the old group is lost, while the destination can grant new access. Transfers across top-level groups remove assigned compliance frameworks.1 Registry and path restrictions can affect whether a transfer is possible. These details are worth reviewing while the move is still a proposal, when you can choose another approach without interrupting contributors.
One representative project can expose missing dependencies before a wider move. Its contributors should be able to find the new location, open and review a change, run the pipeline, and complete the usual release. Any required updates to consumers or integrations belong in the move plan, with someone responsible for them. People also need to know when to stop using the old location and where to ask for help.
Revisit the choice through ordinary work
After the change, the question is whether teams can deliver with fewer handoffs and clearer responsibility. A recent contribution and release will show that more directly than counting projects. New waiting points, repeated copies of shared code, or uncertainty about who owns a failure are reasons to revisit the arrangement.
The project's README.md should keep that agreement easy to find: what the project is for, who maintains and operates it, how to contribute, and where its dependencies are documented. When ownership changes or the project is retired, updating those details is part of the handover.
Further Reading
Notes
-
Compliance frameworks are available in Premium and Ultimate. If your project uses them, review its assignments after a transfer; the framework label alone doesn't enforce a control. ↩
- Organize work with projects explains what a GitLab project brings together.
- Managing monorepos covers repository and pipeline choices for larger codebases.
- Transfer a project describes requirements, restrictions, and changes to inherited access.