Automatically Execute, Report on, and Enforce your PMD Rules

In the last blog post we discussed how PMD works and gave some instructions on how to define and compile your own custom rules using Maven. That was a great exercise, but the act of explicitly invoking a custom PMD executable jar from the command line is rather clunky:

$JAVA_HOME/bin/java -jar target/pmd-rules-1.0.0-jar-with-dependencies.jar \
    -R category/apex/async-apex.xml \
    -d src/main/default/classes/Example.cls \
    -f json

How can we make the execution of these rules and the surfacing of their findings as effortless as possible? In this post we will share how to compile your custom PMD rules so that they can be registered with the SFDX Scanner CLI plugin, and how to automatically execute, report on, and strictly enforce your organization’s rules.

Project, POM, and Jar

Let’s take a look at our project’s directory structure:

├── config
│   └── project-scratch-def.json
├── force-app
│   └── main
│       └── default
│           └── classes
│               ├── Example.cls
│               └── Example.cls-meta.xml
├── pom.xml
├── sfdx-project.json
└── src
    └── main
        ├── java
        │   └── com
        │       └── mycompany
        │           └── pmd
        │               ├──
        │               └──
        └── resources
            └── category
                └── apex
                    └── async-apex.xml

In this structure, you’ll observe two top level directories of interest; force-app which contains all of the Salesforce parts of our project, and src which contains the Java parts of our project. We are going to change the pom.xml up a little bit from the first post.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns=""






This pom acts slightly differently than before. Instead of compiling everything into one jar file with the maven-assembly-plugin, this uses the maven-jar-plugin to produce a scoped jar which just contains the compiled rule itself.

$ mvn package

Now, the project will have a file called target/pmd-rules-1.0.0.jar. This jar file is not executable on its own. If you inspect the contents, you will see that it only includes the compiled classes and XML files for the specific rules we have written:

$ unzip -l target/pmd-rules-1.0.0.jar

Archive:  target/pmd-rules-1.0.0.jar
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  05-29-2023 17:51   META-INF/
      697  05-29-2023 17:51   META-INF/MANIFEST.MF
        0  05-29-2023 17:51   category/
        0  05-29-2023 17:51   category/apex/
     1240  05-29-2023 17:51   category/apex/async-apex.xml
        0  05-29-2023 17:51   com/
        0  05-29-2023 17:51   com/mycompany/
        0  05-29-2023 17:51   com/mycompany/pmd/
     3263  05-29-2023 17:51   com/mycompany/pmd/RequireFinalizer.class
     1059  05-29-2023 17:51   com/mycompany/pmd/AvoidFuture.class
---------                     -------
     6259                     10 files

We could explicitly run our rules by calling the PMD executable and specifying the classPath to include this additional jar, but there is an easier way. The Salesforce Code Analyzer is a plugin for the SFDX CLI which contains PMD and ESLint and has built-in commands for registering custom rules.

# Install the SFDX CLI
$ npm install sfdx-cli -g

# Install the sfdx-scanner plugin
$ sfdx plugins:install @salesforce/sfdx-scanner

# Register the custom rules
$ sfdx scanner:rule:add -l apex -p target/pmd-rules-1.0.0.jar

# run the scan
$ sfdx scanner:run -t force-app/main/default/classes/Example.cls --json"


  "status": 0,
  "result": [
      "engine": "pmd",
      "fileName": "/Users/mitchellspano/Documents/myProject/force-app/main/default/classes/Example.cls",
      "violations": [
          "line": "6",
          "column": "3",
          "endLine": "6",
          "endColumn": "9",
          "severity": 3,
          "ruleName": "AvoidFuture",
          "category": "AsynchronousApex",
          "message": "Usage of the `@Future` annotation should be limited. Please consider implementing the `Queueable` interface instead."
        } // other findings also included
  "warnings": [
    "We're continually improving Salesforce Code Analyzer. Tell us what you think! Give feedback at"

Awesome! This allows us to run our PMD rules in addition to all of the base PMD rules which are already defined. However, we are still running this explicitly from the command line which is not ideal. What we want to do is have the system automatically execute these rules for us whenever a pull request is created or updated, and report the findings back to us in a way which makes sense.

SFDX Scan Pull Request GitHub Action

The SFDX Scan Pull Request GitHub action (written by yours truly) will execute the SFDX Scanner on the contents of a pull request and report the findings formatted as in-line comments or checks.

To use this action in your repository, just reference it in your project:

name: SFDX Scan Pull Request
    types: [opened, reopened, synchronize]
    runs-on: ubuntu-latest
      - uses: actions/checkout@v3
          fetch-depth: 0

      - name: Install SFDX CLI and Scanner
        run: |
          npm install sfdx-cli -g
          sfdx plugins:install @salesforce/sfdx-scanner

      - name: Run SFDX Scanner - Report findings as comments
        uses: mitchspano/sfdx-scan-pull-request@v0.1.14
          report-mode: comments
          GITHUB_TOKEN: $

The action has an optional input parameter called custom-pmd-rules which will enable you to register custom rules for use within the scan. Simply enter a JSON string to add any custom rules that need to be registered before the scan is executed. Custom rules are identified by the path to their XML/JAR file and their language.

- name: Run SFDX Scanner - Report findings as comments
  uses: mitchspano/sfdx-scan-pull-request@v0.1.14
    report-mode: comments
    custom-pmd-rules: '[{ "path": "target/pmd-rules-1.0.0.jar", "language": "apex" }]'

Now, when the scan is executed, our custom rules will be included in the scan and any findings will be surfaced to the developers during their regular workflow:

This works well for reporting findings, but what if we want to enforce these rules?

Enforcement Mechanisms

There are two mechanisms within the scan that can help you to identify a violation as a warning or an error:

The first is called the severity-threshold. This is an input parameter which defines a threshold for the severity of the finding. Severity 1 is the highest priority and severity 5 is the lowest. If the threshold parameter is defined and the scan produces a finding at the threshold or more severe, then the action will fail.

The second is called strictly-enforced-rules. This is an input parameter which accepts a JSON string which defines the rules which will be strictly enforced regardless of their severity. Enforced rules are identified by their engine, category, and rule name.

[{ "engine": "pmd", "category": "Performance", "rule": "AvoidDebugStatements" }]

If an error is identified, the scan’s run will fail with the message ”One or more errors have been identified within the structure of the code that will need to be resolved before continuing”

Excellent! Now we have some really powerful capabilities. We can define our own rules, automatically execute a scan to detect violations of the rules, surface the findings in a readable way, and strictly enforce the rules we care about. Use these tools to automate a large portion of the code review process and enforce adherence to your organization’s Apex standards.