Governance at Scale - Multi-Org and Multi-Team Patterns¶

One Standard, Enforced Everywhere¶

As a Salesforce engineering organisation 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: centralised governance, enforced at the platform level, applied equally across every repository and every org in the organisation. 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 centralised standards rigorously, not less. This is the governance principle Standards Are Enforced, Not Hoped For applied at scale.

The distinction that scale does introduce is not in the standards themselves but in the approval topology: Who is authorised to approve changes at each stage, and how that authorisation is structured across a large organisation. 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 centralised governance framework; they do not replace it.

The failure mode to avoid is accidental decentralisation: Centralisation 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 organisation 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 synchronisation 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 synchronisation 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 Centralised Workflow Configuration Repository¶

The primary mechanism for centralised governance in GitHub is the organization-level .github repository. For Salesforce engineering organisations, this repository becomes the authoritative source for workflow templates, shared configuration files, and organisational 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, the Prettier configuration file, secret scanning configuration, Renovate presets), starter workflows, CODEOWNERS templates, and Dependabot and Renovate configuration. The full directory structure is provided in Appendix D, and the GitHub mechanics behind it (reusable workflows, composite actions, starter workflow templates and how they are versioned) are explained in Appendix G.

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 workflow upgrades while keeping the upgrade path explicit and automatable via Renovate. Renovate's github-actions manager tracks tagged references to the organisation's reusable workflows (owner/repo/.github/workflows/<file>.yml@<tag>, which for the organization's .github repository reads <my-org>/.github/.github/workflows/<file>.yml@<tag>) by default, provided the Renovate app has read access to that repository. The same manager tracks third-party actions, and it keeps each reference's precision: a floating major tag is offered only the next major version, and an immutable release tag every release. The workflow dependency type (via matchDepTypes: ["workflow"]) lets the organisation give its own workflows a separate update policy (schedule, automerge, digest pinning) from third-party actions.

A breaking change policy should be defined: minor and patch versions are backward compatible; major versions may introduce new required inputs or changed behaviour 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 synchronisation 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 decentralisation pattern described above.

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

• Required status checks: Protected branches require the Quality Gates check, a final job in each PR workflow that passes only when every reusable workflow gate has passed or had nothing to check; a PR cannot be merged until it passes (Appendix C).
• 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 branch 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 organisations 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 behaviour, 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 organisations 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. The same platform receives the org's runtime logs and Salesforce Shield events, as set out in the Observability standard.

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.