Pipelines - why we recommend starting with a new repository

When setting up Gearset Pipelines, we strongly recommend creating a new repository rather than connecting an existing one. This is not a hard technical requirement, Pipelines can work with an existing repo in some circumstances, but in the vast majority of cases a fresh repository produces a faster, more stable, and more predictable setup.

This article explains the reasoning behind that recommendation, the specific pitfalls of using an existing repository, and addresses concerns such as preserving commit history.

Pipelines is built on the assumption that your main branch is a perfect reflection of Production. A new repository, seeded from Production during onboarding, is the most reliable way to establish and maintain that guarantee.

Pipelines continuously tracks the difference between your environment branches and your main branch. It uses this to power back-propagation, drift detection, and automated CI/CD flows. That tracking logic depends on a clean, consistent branch history from the very start.

An existing repository, however well-maintained has almost always accumulated characteristics that work against this. The sections below cover the most common ones.

Over time, Salesforce orgs accumulate direct changes made in Production that never get committed back to source control. This can include hotfixes, admin changes, declarative updates and updates pushed by Salesforce. This creates a gap between what the repository says Production contains and what is actually there. When you seed environment branches from an out-of-sync main branch, that drift is baked in from day one. The result is comparison errors, unexpected deployment failures, and environments that are harder to reconcile the longer the pipeline runs. A new repository, seeded directly from Production just before setting up a pipeline eliminates this.

Older Salesforce repositories are often structured in the legacy MDAPI format. Gearset Pipelines works best with SFDX-formatted source. Although we do support the use of MDAPI formatted repository's using a SFDX will result in SFDX unlocks more flexibility, and the files are split up more to make merge conflicts easier to handle.
​

In an active repository, feature branches are often created from different points in history. Some from a recent main, some from older commits, some from other feature branches. This creates a situation where Pipelines cannot reliably determine what has and has not been promoted through each environment.

A fresh repository gives every branch a single, shared starting point: a main branch seeded from Production. All environment and feature branches descend from that baseline.

This is the most common concern teams raise, and it is based on a misunderstanding of what starting a new repository means. Starting a new repository does not delete or replace your existing one. Your existing repository with all of its commit history, pull requests, tags, and linked tickets stays exactly as it is. It will continue to be accessible in your Git host indefinitely.

The new repository is created alongside the existing one and is used exclusively for the Gearset Pipelines workflow going forward. Teams that need to reference historical context can continue to do so in the old repository at any time.

In some cases, yes but it is rarely worth the effort. The work required to bring an existing repository into a pipeline-ready state typically involves:

This is a significant undertaking, and mistakes at any step can introduce new inconsistencies. In the time it takes to fix an existing repository, a new one can be seeded, validated, and have the pipeline running in production. For most teams, the new repository path is both faster and lower risk.

If your repository is recent, already in SFDX format, uses merge commits, has a clean branch structure, and has been kept closely in sync with Production — it may be suitable for use with Pipelines. Contact your Gearset onboarding team to assess your specific situation.