Back to blog feed

Salesforce Metadata API Best Practices: 7 Rules and 3 Common Mistakes

Avatar of author Daniel Rosenberg
Daniel RosenbergCo-Founder
Blog

Why Your Admins and Devs Can’t “Just Use Git”: Solving the Clicks vs Code Divide

Admins and Developers collaborating on Salesforce

Most Salesforce teams know the pain: developers live in Git, admins live in sandboxes, and the two worlds often collide.

Architects and DevOps leads are left managing the fallout: overwritten changes, deployment failures, and merge conflicts caused by admins and devs editing the same metadata in different tools, at other times, with no shared system of record.

A typical (but dangerous) suggestion emerges:

“Why can’t the admins just use Git too?”

It sounds reasonable, but it’s a fundamental misunderstanding of how admins work, how Git works, and how Salesforce metadata behaves.

In this article, we’ll break down:

  • Why admins can’t “just use Git” as developers do
  • What makes Salesforce uniquely complex compared to other Git-native platforms
  • How OrgFlow solves the clicks-vs-code divide with a True Git-based DevOps model that works for both sides

Why Git Alone Fails in Mixed Salesforce Teams

Git is a powerful tool, no question. It’s the backbone of modern software development. But Salesforce presents two unique challenges:

1. Most Admins Don’t Work in a Local Development Environment

Developers:

  • Pull branches
  • Run scripts
  • Commit and push changes
  • Use IDEs like VS Code with Salesforce extensions

Admins:

  • Log in to sandboxes
  • Use drag-and-drop tools (Flow Builder, Object Manager, Permission Sets)
  • Don’t touch the command line
  • Often, we don’t even have Git installed

Expecting a no-code admin to run git checkout, sfdx force:source:pull, or git rebase origin/main is unrealistic and unfair.

Even with training, the friction remains high, and the risk of errors increases.

2. Admins Change Metadata That Doesn’t Map Cleanly to Git

Salesforce metadata is notoriously hard to version:

  • Profiles and permission sets are massive and easily overwritten
  • Flows and Process Builders are complex XML files with nested dependencies
  • Changes from the UI don’t always generate clean, deployable source
  • Dependencies often require multiple files to be committed at once to avoid validation errors

When an admin edits a field or flow, it may affect five metadata files, but there is no way to determine that in Git terms.

Git wasn’t designed for this kind of UI-driven, declarative development.

3. Metadata Format Drift Causes Merge Conflicts

Even if both devs and admins commit to Git, there’s still a problem: the metadata format isn’t always consistent.

Different tools (VS Code, SFDX CLI, the UI) can pull metadata in slightly different ways. This leads to:

  • False diffs
  • Redundant changes
  • Unnecessary merge conflicts
  • Misleading history in Git

This is one reason XML merge conflicts are so common in Salesforce teams, and why simply “training admins on Git” doesn’t address the root issue.

Conflict resolution illustration

The Real Problem Isn’t People. It’s the Process.

Architects and DevOps leads aren’t wrong to want a unified release process. But the goal shouldn’t be forcing admins to adopt developer tools.

The goal should be to build a Git-based release model that supports both clicks and code without requiring either side to abandon their existing tools.

That’s where OrgFlow comes in.

How OrgFlow Solves the Clicks-vs-Code Divide

OrgFlow is designed from the ground up to make Git work for both admins and developers without forcing anyone to change how they work.

Here’s how we do it.

1. Admins Can Contribute Changes Safely (No Command Line Required)

OrgFlow allows admins to:

  • Capture metadata changes from a sandbox
  • Compare their changes to a Git branch (visually)
  • Commit those changes into Git with full context

No terminal.
No manual XML editing.
No fear of overwriting someone else’s work.

OrgFlow turns Git into a collaborative workspace for every Salesforce contributor.

2. Developers Keep Their Native Git Workflow

Unlike platforms that abstract Git away, OrgFlow is fully Git-native.

Developers can:

  • Use VS Code or any IDE
  • Work with Git directly (pull, commit, push, merge)
  • Follow their preferred branching strategy (e.g., GitFlow, GitHub Flow).

And they can do so knowing that admin changes won’t disrupt their workflows, because OrgFlow normalizes metadata and handles conflict detection before the merge occurs.

3. Metadata Is Normalized Before Hitting Git

OrgFlow handles one of the most significant pain points in Salesforce DevOps: metadata formatting.

Before any metadata hits Git, OrgFlow:

  • Normalizes the structure
  • Handles complex file relationships (e.g., profiles, flows, permissions)
  • Filters out noise (like non-functional whitespace changes)

This eliminates false diffs and reduces the surface area for merge conflicts.

Developers see a clean Git history. Admins don’t break things accidentally. Architects achieve auditability across the entire team.

4. Merge Conflicts Are Handled Intelligently

In traditional Salesforce workflows, merge conflicts are painful:

  • You have to dig through XML
  • You have no idea what changed in the org
  • You can’t test until you deploy

OrgFlow changes that.

When two contributors touch the same metadata, OrgFlow:

  • Highlights the differences clearly
  • Surfaces them before the merge
  • Helps resolve them safely in a staging environment
  • Ensures changes are validated before reaching production

This is especially important for flows, profiles, and permission sets where the most damage occurs.

5. Git Is the Source of Truth. Orgs Are Just Workspaces

This is the core philosophy that powers OrgFlow.

  • Git tracks what changed.
  • Sandboxes reflect Git branches.
  • Metadata is deployed from Git, not from manually assembled packages.
  • Every change is traceable, auditable, and reversible.

This architecture flips the traditional Salesforce workflow on its head, and it’s the only way to bridge the clicks vs. code divide without sacrificing team velocity or trust.

Still Trying to Make Git Work for Admins? You’re Solving the Wrong Problem.

If your current process looks like this:

  • Devs pushing to Git
  • Admins working directly in the sandbox
  • Manual merge conflict resolution
  • Lost changes and overwritten metadata
  • CI jobs are failing unpredictably

…it’s not a people problem. It’s a system problem.

No amount of “just use Git” will unify your Salesforce team if your tooling treats Git as an afterthought or ignores how admins work.

You need a platform that treats Git as the source of truth and bridges both personas with purpose-built workflows.

Unified Git-native workflow

OrgFlow Was Built for This Moment

  • Your developers don’t want to give up Git.
  • Your admins don’t want to write code.
  • Your architects need a release process they can trust.

OrgFlow makes all of that possible.

With a Git-native, admin-inclusive DevOps platform, you can finally:

  • Eliminate merge conflicts between clicks and code
  • Enable safe, auditable deployments from any contributor
  • Run an accurate CI/CD pipeline that doesn’t break under pressure

Ready to unify your team around a Git-native workflow that actually works for Salesforce?

Book a demo at www.orgflow.io/contact to see how OrgFlow eliminates the clicks vs. code divide for good.

Last updated: