MetaLens360Help Center

Set up a promotion pipeline

Describe how code moves through your branches and Salesforce environments so MetaLens360 can track where every change has reached and what is stuck.

Updated in Source control & promotion

Overview

A promotion pipeline tells MetaLens360 how code moves in your team — for example develop → sit → uat → main — and which Salesforce environment each branch deploys to. MetaLens360 never assumes a path. Promotion tracking on Source Code Repo Insights → Promotion works entirely from what you configure here, so it fits any branch strategy and any number of stages.

You set it up in Settings → Promotion Pipeline.

Before you start

  • Connect the Git repository. See Connect a Git repository.
  • Saving, editing or deleting a pipeline needs the Manage org/Git connections permission (Admin, Architect and DevOps by default).
  • Optional: connect the Salesforce orgs each stage deploys to, so MetaLens360 can also show whether an org is running a change.

Steps

  1. Open Settings → Promotion Pipeline.
  2. Choose the Repository.
  3. Click Suggest from repository to draft a pipeline from that repository's pull-request history. The draft opens marked draft — nothing saved yet; click Use this draft to edit it. If there is no useful history, click New Pipeline from Scratch instead.
  4. Enter a Pipeline name and, if your team uses one, a Feature branch pattern (optional).
  5. Under Stages · in promotion order, set up each stage:
    • Stage name — what your team calls it, such as "SIT".
    • Branch — the branch that is this stage.
    • Salesforce environment — the connected org it deploys to, or Not linked. You can type an Environment name (optional) for an org that isn't connected yet.
  6. Click Promotion rules on a stage to fine-tune it: a Required tag pattern, Also accepts PRs from (comma-separated), and switches such as Promotion goes through a pull request and Merging here deploys to the environment automatically.
  7. Use Add stage, Move earlier, Move later and Remove this stage until the order is right. The Enabled switch skips a stage without deleting it.
  8. Check the path diagram at the top, then click Save pipeline.
  9. Go to Source Code Repo Insights → Promotion and run Sync promotion history to start tracking.

Check setup readiness

The Setup readiness chain lists each dependency in order: Org sync, Org index, Promotion pipeline, Repository, Promotion branches, Branch history fetched and Promotion Intelligence. Each shows Ready, Not set up, Unknown or Out of date. The first step that isn't ready is where setup stops. Some steps offer a fix button, such as Add to schedule or Run sync.

Example

Priya's team works in feature/* branches, merges to develop, then promotes by pull request to qa and main. She clicks Suggest from repository, gets a three-stage draft, links develop to acme-dev, qa to acme-uat and main to acme-prod, turns on Promotion goes through a pull request, and saves.

FAQs

Can I reuse a pipeline for another repository?

Yes. Click Clone on a saved pipeline, choose the target repository, and click Create copy.

Why is "Suggest from repository" disabled?

Choose a specific repository first. It is also disabled when that repository already has a pipeline — edit the existing one instead.

What happens if I delete a pipeline?

Promotion tracking for that repository stops until another pipeline is configured. Synced Git history is kept.

Troubleshooting

"Could not save the pipeline"

Check the message shown. Missing permission is a common cause — see Fix permission denied errors.

"Could not read the repository to build a suggestion"

MetaLens360 couldn't read the pull requests. Test the repository connection, or start with New Pipeline from Scratch. See Fix Git repository access.

Promotion shows changes moving backwards

The stage order is reversed. Edit the pipeline, fix the order with Move earlier / Move later, save, and sync again.

Was this article helpful?

Related articles