Recommendations and Roadmap¶
Context and Starting Point¶
This whitepaper is written from the perspective of a consulting organisation establishing a unified, repeatable DevSecOps standard across Federal Salesforce delivery projects. The roadmap that follows assumes a greenfield starting point - a new project, a new GitHub organization or repository, and a delivery team that may have varying levels of familiarity with source-driven Salesforce development. It is not a migration guide for organisations with existing pipelines, though teams in that position will find the phasing useful as a gap assessment framework.
The three phases below represent a recommended sequence, not a rigid prescription. Projects vary in team size, client constraints, org complexity, and timeline. A small project with a senior team may compress Phases 1 and 2 into the first two weeks of delivery; a large enterprise engagement with multiple workstreams may run certain Phase 2 and Phase 3 activities in parallel. The sequencing reflects dependency order - the things that must be true before other things can be built on top of them - and teams should use that dependency logic, not the calendar labels, as their guide.
Phase 1 - Foundation¶
The goal of Phase 1 is to establish the non-negotiable structural prerequisites that everything else depends on. A project that skips or shortcuts these foundations will accumulate governance debt that becomes progressively harder to address as the codebase and team grow.
Establish source-driven deployment as the only deployment path. Before any pipeline tooling is configured, the team must agree - and the client must understand - that all changes to the Salesforce org flow through the repository. No change sets, no direct CLI deployments outside the pipeline, no manual org modifications that are not immediately committed back to source. The source-driven deployment ratio metric starts at this moment - any deviation from 100% from day one is a signal that the commitment has not been fully adopted.
Initialise the repository structure and branch topology. Set up the Salesforce DX project structure, define the branch strategy appropriate for the project's environment topology, configure the initial sfdx-project.json, and establish the .gitignore and .forceignore patterns. A dedicated GitHub configuration repository marked as a template in GitHub's repository settings - seeded from the consulting organisation's configuration repository - allows the new project to be initialised with all scaffolding files in place from the first commit.
Implement PR convention enforcement. Configure amannn/action-semantic-pull-request or equivalent to enforce Conventional Commits format on PR titles in GitHub. Enable squash merge as the only merge strategy on protected branches. These two controls establish the commit history discipline that the automated changelog and release management infrastructure depends on - and are far easier to enforce from the first PR than to retrofit.
Implement JWT bearer flow authentication. Generate the certificate and private key pair first, because the certificate is uploaded when the flow is enabled. Create the External Client App in each of the client's Salesforce orgs that the pipeline connects to, enable the JWT bearer flow on it and upload the certificate, and pre-authorise the integration user's profile or permission set in its policies. Store the private key as a GitHub Actions secret, and validate that the GitHub Actions runner can authenticate to all required orgs. A Dev Hub from which the pipeline creates scratch orgs is the exception and still needs a Connected App (Section 7).
Wire the basic PR quality gate chain. Stand up the initial GitHub Actions PR workflow with: Prettier formatting verification (prettier --check), Salesforce Code Analyzer static analysis with severity 1 and 2 as blocking, and sf project deploy start --dry-run of the delta package against the CI sandbox, which carries the pull request's Apex tests. Configure these as required status checks on the int branch.
Wire Apex test execution as a PR gate. Add Apex test execution immediately alongside the initial quality gates, inside the validation of the delta package. Run the tests that bear on the change, not every local test: RunRelevantTests if the project deploys at API 66.0 or later and is allowed to use Beta features, and otherwise RunSpecifiedTests with a computed list (Section 5). Instrument test result output as structured PR comments, and schedule a full RunLocalTests run from the start, because the pull request gate relies on it to catch what a scoped run misses.
Add LWC Jest testing if the project includes LWC components. Configure @salesforce/sfdx-lwc-jest, add jest.config.js to the repository root, wire Jest execution into the PR workflow so that it runs when Lightning web components change, and report the failing tests and the coverage on the pull request. Establish the Jest coverage threshold in jest.config.js, for each component that has a test. An existing component library with few tests is then not blocked, and each component is held to the threshold from its first test.
Stand up the push quality baseline workflow. The push baseline - covering Prettier verification, Code Analyzer static analysis, and LWC Jest tests on every branch push - provides immediate feedback to developers on feature branches before a PR is opened. It is not meaningfully more complex to implement than the PR workflow, and it provides value by reinforcing the shift-left model from the first commit of the engagement. A sample implementation is provided in Appendix A.1.1. This workflow also calls the Release Please reusable workflow on pushes to main, so the release infrastructure is in place from day one.
Configure branch protection and CODEOWNERS. Apply the branch protection model to the repository. Create the initial CODEOWNERS file mapping governance configuration files to the governance team (@<my-org>/admin-team). Enable required Code Owner review for governance file paths on all protected branches.
Install local developer tooling. Ensure every team member has the Salesforce Code Analyzer VS Code extension installed and configured against the project's code-analyzer.yml. Install the Salesforce Extension Pack. Set up husky, lint-staged, prettier, and a bash script for pre-commit formatting enforcement. Add VS Code extension recommendations to .vscode/extensions.json.
Configure the centralised configuration repository. If the organisation has an existing configuration repository - which it should, as a direct output of this whitepaper's recommendations - consuming repositories should be wired to it from day one. If the configuration repository does not yet exist, Phase 1 of the first project is the time to build it.
Phase 2 - Hardening¶
Phase 2 builds depth and breadth on the foundation established in Phase 1. The basic pipeline is running; the goal now is to close the gaps, increase the signal quality, and extend coverage to the full change surface of the project.
Implement the structured Code Analyzer feedback pattern. Move beyond raw scanner output to the two-table PR comment pattern - blocking violations and non-blocking violations presented separately, updated on each push. Upload SARIF output to GitHub Code Scanning.
Stand up the metadata drift detection scheduled workflow. Configure the drift detection job of the weekly project scan against the project's sandbox or production org. Start with the alerting pattern - post a structured drift report as a GitHub issue and Slack notification when drift is detected.
Implement secret scanning. Wire a secret scanning tool into Husky pre-commit hooks and as a CI workflow step, using the same configuration file centralised in the configuration repository. Enable GitHub secret scanning, with push protection, where the client's GitHub plan has it: it is free for a public repository, and a private repository needs GitHub Secret Protection.
Configure Renovate and Dependabot. Install the Renovate app for the organisation, write the central Renovate file, and give each repository the one-line renovate.json that extends it. Switch on Dependabot alerts and security updates in the settings of each repository. Ensure the shared Prettier configuration npm package, if used, is tracked as a dependency. The central Renovate file gives every update a Conventional Commit title (Version Control: Renovate and Dependabot).
Implement the metadata type risk classification. Add the path-based trigger conditions and automated PR labelling logic that routes Tier 1 metadata changes to mandatory senior reviewer assignment and unconditional auto-merge block (Section 6, Appendix B).
Phase 3 - Strategic Governance Buildout¶
Phase 3 represents the transition from a well-instrumented delivery pipeline to a mature, self-improving governance system.
Evaluate and adopt RunRelevantTests. If the project started on the computed RunSpecifiedTests list, because it could not use Beta features or deployed below API 66.0, evaluate RunRelevantTests (introduced in Section 5) when either constraint lifts, against the PR cycle time and gate pass rate metrics from Phase 2. Instrument the @IsTest(testFor='...') annotation across Apex tests to improve Salesforce's dependency inference accuracy, and mark critical tests with @IsTest(critical=true).
Implement the full dependency analysis baseline. Establish the scheduled full-org Apex test run and scheduled Apex compilation check workflows (Section 6). If the project's org is large and highly interconnected, evaluate the MetadataComponentDependency (beta) Tooling API advanced pattern. By Phase 3 the team has enough operational context to assess whether the implementation cost is justified. (Only do this if the organisation is cleared to use beta features.)
Contribute improvements back to the configuration repository. Patterns that worked well on this project - reusable workflow improvements, new composite actions, refined configuration standards, additions to the metadata risk classification matrix - should be contributed back as PRs to the consulting organisation's central configuration repository. This is how the configuration repository matures across projects.
Revisit release cadence as a business decision. With a stable, fully automated pipeline in place, the engineering constraint on deployment frequency has been removed. Work with the client to evaluate whether the existing release cadence reflects a genuine business or product need, or is an artifact of the deployment friction that the pipeline has now eliminated. Story-level or on-demand production deployments become viable options where the business and client approval processes support them.
Evaluate the third-party and AI tooling placeholder. By Phase 3 the team has enough production pipeline data to evaluate whether complementary tools - CodeRabbit, Hubbl, AI-assisted code review platforms - would add material value over the baseline Code Analyzer output.
Establish pipeline metrics reporting. Instrument the metrics from Section 9 - gate pass rates, PR cycle time segmented by outcome, source-driven deployment ratio, drift frequency, security finding trends, test suite health - as a recurring report delivered to the technical lead and client stakeholders.
A Note on Cross-Project Learning¶
For a consulting organisation, each project is simultaneously a delivery engagement and a learning opportunity. The configuration repository accumulates best practices across projects; the metrics framework reveals patterns across engagements; the governance standards evolve as the organisation encounters new client environments, new regulatory requirements, and new Salesforce platform capabilities.
The architecture described in this whitepaper is a starting point, not a finished artifact. Salesforce Code Analyzer reached GA in April 2025 but continues to evolve: the Salesforce Graph Engine is in Developer Preview, RunRelevantTests is in beta, new engines will be added, and the CLI interface will continue to change. GitHub's Rulesets and Actions platform continues to add capabilities. Teams that treat the pipeline as a product - with its own backlog, its own improvement cycle, and its own metrics - will extract compounding value from the investment over the life of the engagement and across the portfolio of engagements that follow.