8. Governance at Scale - Multi-Org and Multi-Team Patterns

One Standard, Enforced Everywhere

As a Salesforce engineering organization grows - more repositories, more teams, more orgs - the governance model that worked for a single team with a single repository begins to break down. Quality gate configurations diverge across repositories. Workflow YAML gets copied, locally modified, and never updated when the original changes. One team's PMD ruleset drifts from another's. The pipeline that was supposed to enforce standards becomes a patchwork of inconsistently applied, individually maintained configurations that no single person fully understands.

The architectural response is unambiguous: centralized governance, enforced at the platform level, applied equally across every repository and every org in the organization. This is not a preference: it is the only model that provides the consistency guarantees that quality and security governance require. Larger enterprises with more complex regulatory environments, more teams, and more orgs have more reason to enforce centralized standards rigorously, not less.

The distinction that scale does introduce is not in the standards themselves but in the approval topology: Who is authorized to approve changes at each stage, and how that authorization is structured across a large organization. An enterprise with multiple business units may implement federated approval chains - different senior reviewer teams per business unit, different environment promotion policies per product line - but the underlying quality gates, configuration standards, and enforcement mechanisms are identical. Federated approvals operate within a centralized governance framework; they do not replace it.

The failure mode to avoid is accidental decentralization: Centralization was the intent but enforcement was never implemented, resulting in repositories that started from a shared template and diverged silently over time. The difference between a well-governed large organization and an ungoverned one is not the size of the rulebook; it is whether the rules are enforced automatically and uniformly, or whether they depend on individual team discipline to apply.

A Note on Advanced Automation

The patterns described in this section span a wide range of implementation maturity. The directory structure, reusable workflows, composite actions, and configuration standards represent the core of what a configuration repository should contain and are appropriate for any team to implement from the outset of an engagement. Several capabilities described later - automated synchronization between the templates/ directory and a GitHub configuration repository, automated release tagging via release-please, and cross-repository propagation of configuration changes via Renovate - represent a higher level of platform automation investment. These capabilities compound in value as the number of repositories and projects consuming the template grows, but they introduce operational complexity that is not warranted until the core configuration repository is stable and well-adopted.

Teams should approach the configuration repository as a product with its own maturity progression. Establish the structure and manually maintained standards first. Introduce automated versioning and release management once the change cadence justifies it. Invest in template synchronization automation once the manual process has proven reliable and the volume of changes makes manual mirroring impractical. Each layer of automation should be adopted deliberately, with the operational overhead of maintaining the automation itself factored into the decision.

The Centralized Workflow Configuration repository

The primary mechanism for centralized governance in GitHub is the organization-level .github repository. For Salesforce engineering organizations, this repository becomes the authoritative source for workflow templates, shared configuration files, and organizational quality standards.

What lives in the configuration repository includes reusable workflow definitions, composite actions, configuration standards (code-analyzer.yml, PMD ruleset XML, eslint.config.js, jest.config.js, .prettierrc, secret scanning configuration, Renovate presets), starter workflows, CODEOWNERS templates, and Dependabot and Renovate configuration. The full directory structure is provided in Appendix D.

Governance file protection: The configuration repository's own governance files are protected by a CODEOWNERS entry mapping those paths to the governance team (@<my-org>/admin-team). This ensures that changes to the standards that govern all other repositories require governance team approval, closing the loop on governance of the governance layer itself. Consuming repositories should apply the same pattern to any local copies of governance files - preventing individual teams from silently modifying the configuration files that quality gates depend on.

Reusable workflows vs. composite actions: Reusable workflows (workflow_call) are called as entire jobs - they run in their own execution context and produce their own job status. This is the right pattern for complete, self-contained quality gates. Composite actions are called as steps within a job, executing in the same runner context. This is the right pattern for setup sequences and utility operations that need to share state with surrounding steps. For most Salesforce quality gates, reusable workflows are the correct choice, and a reusable workflow can contain composite actions.

Versioning and change management: Configuration repository changes follow the same PR-based change process as application code. Consuming repositories pin to a specific version tag rather than referencing @main directly. This gives teams control over when they absorb template changes while keeping the upgrade path explicit and automatable via Renovate. For Renovate to automatically open upgrade PRs in consuming repositories, the organization's renovate.json preset must include an explicit github-actions manager entry scoped to the organization's own .github repository - without this entry, Renovate tracks external GitHub Actions dependencies but does not monitor internal template workflow references.

A breaking change policy should be defined: minor and patch versions are backward compatible; major versions may introduce new required inputs or changed behavior and require coordinated upgrade across consuming repositories.

GitHub configuration repository as a complement: Maintaining a dedicated GitHub configuration repository - a separate repository marked as a template in GitHub's repository settings - allows new projects and packages to be created from it with a single click or API call, copying all files and directory structure automatically. The templates/ directory in the .github repository remains the authoritative, reviewed source for scaffolding content, while the GitHub configuration repository itself reflects its current state for consumption. Automating this synchronization via a GitHub Actions workflow is achievable but represents advanced-level automation - teams should establish the manual pattern first.

GitHub Rulesets as the Enforcement Layer

Workflow templates and shared configuration files establish standards; GitHub Rulesets enforce them. Without enforcement, template adoption is voluntary - teams that are under pressure take shortcuts, and the governance model degrades to the accidental decentralization pattern described above.

The key Salesforce-relevant rules to enforce at the organizational level are:

• Required status checks: The reusable workflow jobs are configured as required status checks on protected branches; a PR cannot be merged if any required check has not passed.
• Required workflows: Specific workflow files from the configuration repository are designated as required - any controlled repository in the organization that receives a PR against a protected branch must run these workflows.
• Branch protection rules: The tiered protection model from Section 4 is defined once at the organization level and applied by branch name pattern across all repositories.
• Bypass lists: Rulesets support explicit bypass lists for service accounts and automation users that legitimately need to push to protected branches - hotfix deployment accounts, automated release tooling - without granting bypass to human contributors.

The full Rulesets configuration reference is provided in Appendix C.

Enforcing Standards Across Multiple Salesforce Orgs

For organizations with multiple Salesforce orgs, the configuration repository pattern extends naturally. The reusable workflow accepts the target org credentials as inputs, and the calling repository's workflow passes the appropriate environment-scoped secrets. This pattern means the validation logic is identical across all orgs - the only variable is the credential set used to authenticate. Org-specific behavior, where genuinely required, is expressed as workflow inputs rather than workflow forks. The metadata type risk classification matrix should be maintained in the configuration repository and consumed by all Salesforce repositories, ensuring that a Tier 1 metadata change in any org triggers the same elevated governance response.

Audit Trails as an Operational Asset

Every GitHub Actions workflow run produces a timestamped, immutable record. For Salesforce deployments, this record is the foundation of operational traceability - the ability to answer precisely: what changed and when did it deploy; which PR introduced the change and who approved it; what tests were run and did they all pass; what was the last known-good deployment state for rollback purposes.

Making this audit trail operationally useful requires deliberate instrumentation:

Deployment records as GitHub Deployments: The GitHub Deployments API (documentation) allows workflows to create structured deployment records linked to a specific commit, environment, and deployment status. These appear in the repository's deployment history and are queryable via the API for incident investigation.

Linking deployments to work items: Deployment workflow steps should write back to the work item system - Jira, Azure DevOps, GitHub Issues - linking the deployment record to the stories or bugs that triggered the change. This closes the traceability chain from business requirement through code change through deployment.

Retention and searchability: GitHub Actions logs are retained for 90 days by default. For organizations where longer retention is required, log forwarding to an external observability platform should be configured as a workflow step that runs on every deployment, independent of deployment success or failure.

Rollback evidence: The audit trail should capture not just successful deployments but partial failures - which components were deployed before the failure, which were not, and what the recovery action was. This record is the input to the rollback decision.