Appendix A: Sample GitHub Actions Workflow YAML¶

This appendix provides annotated example GitHub Actions workflow files and composite actions implementing the pipeline architecture described throughout this whitepaper. They are examples to adapt, not files promised to run unchanged. The files follow a modular design: each quality gate lives in its own reusable workflow under .github/workflows/, and repeated step sequences (authentication, environment setup, PR commenting, result parsing) are extracted into composite actions under .github/actions/.

All workflow files follow the conventions established in this whitepaper: Conventional Commits-compatible job naming, structured PR comment output via $GITHUB_STEP_SUMMARY and dedicated PR comment composite actions, and jq for parsing JSON output.

Action version note: every uses: reference on this page names the version that was current at the time of writing. Where a page references the organisation's own reusable workflows and composite actions by tag, the tag is an immutable release tag; third-party actions are shown at their floating major tag, a choice many organisations make for highly trusted actions such as actions/checkout (the trade-off is explained in Appendix G). Newer major versions may introduce breaking changes: review the release notes for an action before upgrading, and validate in a non-production pipeline before promoting to protected branches. Dependabot and Renovate (Section 7) open PRs when new versions are published, providing a structured upgrade path.

The sfdx-git-delta plugin (GitHub) is used throughout for delta package generation, scoping analysis and test execution to changed files rather than the full workspace. The delta package is the folder that sfdx-git-delta writes for a change: a package.xml that lists the changed metadata, and a copy of each changed file. It is not a Salesforce package. The delta package is generated once per PR run by a dedicated reusable workflow and uploaded as a GitHub Actions artifact, then downloaded by every downstream job that needs it: code analysis, Apex tests, Jest tests, and deployment validation. This avoids the cost and inconsistency of regenerating the delta independently in each job.

The Gates at a Glance¶

Each table lists the gates that one kind of trigger runs: the tool behind each gate, what the gate does, and what happens when it finds a violation. The tools a developer runs before any of this, on their own machine, are in Section 4.

On a Pull Request¶

The gates of the pull request callers (A.1.2 and A.1.3), in the order they run. The run has four stages. In stage 1 the seven quick gates run in parallel, each a checkout and a short script, or Prettier. Stage 2 builds the delta package, and it starts only when every stage 1 gate has passed, so a pull request that fails a quick gate ends in seconds, before any org is touched. Stage 3 works on the delta package, with its three gates in parallel. Stage 4 validates the delta package against the org. Stage 5 is the Quality Gates job, the one required check, which waits for every job before it. A Variables job, which is not a gate, runs beside stage 1 and passes the thresholds from the top of the file to the gates that take them. The diagram shows which job waits for which, with each job under the name it has in the callers.

---
config:
  layout: dagre
---
flowchart TB
    accTitle: The stages of a pull request run
    accDescr: Stage 1 runs seven quick gates in parallel: formatting, the pull request title, secrets, prohibited metadata, destructive changes, the risk tier, and the changelog. Stage 2, the delta package, waits for all seven. Stage 3 runs code analysis, the Jest tests, and the Apex test selection in parallel, each on the delta package. Stage 4, the validation against the org, waits for code analysis and the Apex test selection. Stage 5, the Quality Gates job, is the one required check, and it waits for every job.
    subgraph s1 ["Stage 1: the quick gates, in parallel"]
        prettier["Formatting"]
        title["PR Title"]
        secrets["Secrets"]
        tier0["Prohibited Metadata"]
        destructive["Destructive Changes"]
        risk["Risk Tier"]
        changelog["Changelog"]
    end
    subgraph s2 ["Stage 2: the delta package, once every stage 1 gate has passed"]
        delta["Delta Package"]
    end
    subgraph s3 ["Stage 3: the gates on the delta package, in parallel"]
        sca["Code Analysis"]
        jest["Jest Tests"]
        apexsel["Apex Test Selection"]
    end
    subgraph s4 ["Stage 4: the validation against the org"]
        validate["Validation"]
    end
    subgraph s5 ["Stage 5: the one required check"]
        gates["Quality Gates"]
    end
    tier0 ~~~ delta
    s1 --> delta
    delta --> sca
    delta --> jest
    delta --> apexsel
    sca --> validate
    apexsel --> validate
    jest --> gates
    validate --> gates

Two more workflows answer a pull request event. A.1.6 runs the Metadata Risk Tier gate again whenever auto-merge is enabled. A.1.8 gives a pull request from Dependabot a title that the Semantic PR Title Check accepts; it is not a gate.

On a Push¶

The gates of the push baseline (A.1.1), which runs on every push. On a branch whose name starts with feat, only the secret scan and the formatting check run. A push workflow cannot stop a commit that is already pushed, so a failed run flags the problem before a pull request is opened.

On a push to main the same workflow also runs Release Please, which is not a gate.

On Demand¶

One workflow runs only when a person starts it, from the "Run workflow" button (A.1.7). It is a report, not a gate.

On a Schedule¶

The checks of the two scheduled callers (A.1.4 and A.1.5), which look at the org and at the whole repository, and not at a change.