Skip to content

Metadata Governance Gates

The gates on this page govern metadata: scheduled surveillance that detects drift between the org and the repository, and the PR-time gates for destructive changes, deployment validation, risk classification and dependency impact. They are two of the three distinct pipeline concerns set out in Section 4, which also covers the third, the push-time feedback that comes before a PR exists.

Scheduled: Metadata Drift Detection

Drift is the cumulative divergence between what the repository says the org contains and what the org actually contains. It accumulates through direct org changes - fixes applied in production under pressure, sandbox experiments never committed, declarative changes made by administrators outside the developer workflow - and it compounds silently until a deployment surfaces the inconsistency at the worst possible moment.

Drift detection requires a scheduled GitHub Actions workflow - not a PR gate - that runs on a defined cadence and compares org state to repository state. The sf project retrieve start command retrieves current org metadata over a fresh checkout of the repository, and a subsequent git diff against the last commit surfaces divergence. This workflow has no merge-blocking role; its output is informational, feeding into one of three response patterns:

  • Alerting only: The workflow posts a structured drift summary to a Slack channel or creates a GitHub issue; engineers investigate and resolve manually.
  • PR generation: The workflow creates a pull request that brings the repository into alignment with the org, triggering the full PR-time quality gate chain before the drift is accepted into source.
  • Hard failure: For orgs where source-driven deployment is strictly enforced, any detected drift fails the scheduled workflow and blocks further deployments until resolved.

The right pattern depends on the org's deployment maturity. Teams transitioning from change set deployments will typically start with alerting and progress toward hard failure as the source-driven model matures.

PR-Time: Destructive Change Detection and Governance

Destructive changes - field deletions, component removals, object deprecations - are the highest-risk category of Salesforce deployment. Unlike additive changes, destructive changes are frequently irreversible in production and can cascade across dependent metadata, integrations, and data in ways that a deployment validator alone will not surface.

In a source-driven pipeline, destructive changes are expressed in a destructiveChanges.xml manifest. The presence of this file in a pull request is the primary signal that elevated scrutiny is warranted. A GitHub Actions PR workflow can detect and respond to this explicitly:

  • Scanning the PR diff for the presence or modification of destructiveChanges.xml or destructiveChangesPre.xml.
  • Labeling the PR automatically with a destructive-change tag to trigger mandatory reviewer assignment.
  • Blocking auto-merge policies regardless of quality gate status - destructive changes should require explicit human approval even when all automated gates pass.
  • Posting a structured comment to the PR summarising the components marked for deletion and their metadata type, giving reviewers an immediate impact surface without requiring them to parse the XML manually.

Beyond manifest detection, the workflow can perform dependency analysis before a destructive change is allowed to proceed. The sf CLI's metadata dependency tooling can identify which other components reference the component marked for deletion - surfacing blast radius before the change reaches a validation org.

PR-Time: Metadata Validation and Deployment Integrity

A change that passes static analysis and unit tests can still fail in the target org due to metadata conflicts, missing dependencies, or org-specific configuration state. sf project deploy start --dry-run runs a full server-side validation against the target org without committing any changes - it is the definitive check that metadata is deployable in context, not just syntactically correct in isolation.

Key design decisions for this gate:

  • Target org selection: Validation should run against the closest available approximation of the production org - typically a full-copy sandbox or a dedicated CI sandbox kept in sync with production metadata.
  • Test level: The validation carries the pull request's Apex tests, so it runs the tests that bear on the change and not every local test: RunRelevantTests (Beta, API 66.0 and later), or RunSpecifiedTests with a computed list where that cannot be used. RunLocalTests runs on a schedule and at the deployment to production. Refer to Section 5 for the full test level discussion; this section covers the corresponding metadata validation pattern.
  • Failure surfacing: Deployment validation errors should be parsed from the CLI output and posted as structured PR annotations rather than left as raw log output for the developer to interpret.
  • Concurrency handling: GitHub Actions concurrency groups prevent simultaneous validations against the same org from producing conflicting results and consuming test execution locks.
  • Empty delta guard: Before executing validation, the workflow should verify that the delta package contains deployable metadata via grep -q '<types>' delta/package/package.xml. If the delta package is empty - for example on a documentation-only change - validation should be skipped cleanly rather than erroring against an empty manifest.

PR-Time: Metadata Type Risk Classification

Not all metadata types carry equal risk. A metadata type risk classification framework assigns each metadata type one of four risk tiers, ranked by the blast radius of an erroneous change: the breadth of its impact, how reversible it is, and how likely it is to cascade into dependent components or data. The tier drives PR workflow behaviour automatically. The tiers classify metadata deployed to the org. Secrets and credentials are never metadata and are governed separately in Section 7, and configuration stored as records rather than metadata, such as permission set assignments, follows the Configuration Data standard.

Tier 0 - Prohibited: Metadata types that never enter version control, because they are managed directly in each org and committing them provides no governance benefit or creates conflicts. Tier 0 is a defined group of metadata types, listed in Appendix B, with a mechanism for keeping the whole group out of version control. The pipeline does not route Tier 0 changes to reviewers; it blocks them outright, at five layers:

  • .forceignore lists the Tier 0 paths, so the Salesforce CLI never retrieves or deploys them and they do not arrive in the project in the first place.
  • .gitignore lists the same paths, so they are not staged by accident. This is a convenience rather than a control, since git add --force overrides it.
  • A GitHub push ruleset with a file path restriction rejects any push that contains a Tier 0 path, so the commit never reaches the remote repository. Push rulesets are not available on every GitHub plan.
  • A required PR status check fails if the PR diff contains a Tier 0 path. It is the fallback where push rulesets are unavailable, and a second line of defence where they are.
  • A static analysis rule takes the list of Tier 0 types as a property and reports every metadata file of a listed type at severity 1, the severity at which a violation is fixed, and accepted only in rare cases (Severity Levels). It reads what a file contains and not where it is, so it also catches a Tier 0 file saved under another name or in another folder.

No metadata file of a Tier 0 type is committed to version control. Enforced by ProhibitedMetadataType.

Tier 1 - High Risk: Metadata types where errors have broad, potentially irreversible consequences, typically those that control access, authentication, and the org's security boundary. Changes to Tier 1 metadata trigger mandatory senior reviewer assignment, block auto-merge unconditionally, and may require a linked change management record depending on the organisation's ITSM posture. Any PR containing a destructive changes manifest is treated as Tier 1.

Tier 2 - Standard Risk: The majority of programmatic and declarative metadata. The standard PR quality gate chain applies with no elevated reviewer requirements.

Tier 3 - Low Risk: Metadata unlikely to cause functional regressions. Candidates for expedited review in mature teams.

Appendix B is the canonical classification matrix: it assigns every metadata type to its tier, with the rationale for each. This section defines the tiers and what the pipeline does with them, and deliberately does not repeat the matrix, so that the two cannot drift apart. The pipeline reads a machine-readable copy of the matrix, metadata-risk-tiers.yml, which is a versioned artifact in the configuration repository (Section 8). A required workflow uses it to label every PR with its highest risk tier and to disable auto-merge on Tier 1, and a CODEOWNERS block makes the architect team the code owner of every Tier 1 path. The samples are in Appendix B and Appendix A.

PR-Time: Dependency Analysis and Impact Assessment

For most organisations, a combination of well-chosen PR-time test levels and scheduled full-org quality runs provides sufficient coverage without requiring explicit dependency graph tooling:

  • PR-time test execution using RunRelevantTests (Beta, API 66.0 and later), or RunSpecifiedTests with a computed list, provides fast, targeted feedback on the components being changed.
  • Scheduled full-org Apex test runs - wired into a nightly or cadence-based GitHub Actions workflow - catch regressions that PR-scoped test execution may not surface, including failures in components that depend on recently changed code but were not included in the PR-time test scope.
  • Scheduled Apex compilation checks - running a full org compilation on a schedule confirms that no accumulated changes have introduced compilation failures across the codebase, independent of test coverage.

For organisations that need deeper impact assessment, the sf CLI exposes dependency information via sf data query against the MetadataComponentDependency tooling object, which returns the full dependency graph for any component in the org. This is an advanced capability that introduces meaningful pipeline complexity and is most appropriate for large, highly interconnected orgs where the cost of a missed dependency failure in production justifies the investment. For large orgs where querying the full dependency graph on every PR is prohibitively slow, a pragmatic alternative is to maintain a cached dependency manifest - generated by the scheduled drift detection workflow and committed to the repository - that the PR workflow queries locally rather than hitting the org API on each run.