Catch Salesforce Issues Earlier with Agentia Local Quality Gates

You've made a change to your Salesforce project. Maybe it's an Apex class, a Lightning Web Component, or a small metadata update.

Before you commit your work or submit your User Story to Copado, wouldn't it be better to catch problems right where you're working?

That's what local quality gates in Agentia Headless are for. They let you run your project's checks directly from your terminal or IDE, get feedback early, and fix problems before moving further through your delivery workflow.

Let's see how it works.

What are local quality gates?

Local quality gates are checks that run on your machine against your Salesforce project. They're configured in your repository, so your team can decide which checks matter for its development workflow.

For example, your quality gates might include:

• Salesforce Code Analyzer to identify potential code quality issues.
• Apex tests to verify your Apex logic behaves as expected.
• Jest tests to validate Lightning Web Components.
• Additional checks such as linting or formatting, depending on your team's needs.

Agentia provides the command to run these checks, while your project's quality-gate script defines what actually runs.

This means you can tailor the checks to your project without changing your everyday development workflow.

1. Set up local quality gates

First, make sure Agentia CLI is installed and configured for your Copado environment.

From your Salesforce project's root directory, run:

agentia setup

Follow the prompts and accept the local quality gates setup option.

Agentia generates two scripts:

• .agentia_quality_gates.sh for macOS and Linux.
• .agentia_quality_gates.cmd for Windows.

These scripts are the starting point for your team's local checks. Review them and adapt them to your project's requirements.

For example, the generated script includes Code Analyzer, Apex testing and Jest checks. You can add or remove checks to match your team's standards.

A good practice: Commit the configured scripts to your Git repository. This way, the whole team shares the same quality gates instead of relying on individual developers' local setup.

There's also one Copado configuration to verify. In your Governance Org, a Copado Admin should ensure that Local Quality Gate Extension Configuration exists and is active, with Copado Phase set to Test, Extension Tool set to None, and Test Type set to Unit Test. This allows Agentia to record the result against the User Story.

2. Run your quality gates

Once your project is configured, running the checks is straightforward:

agentia cicd work test

Agentia runs the quality-gate script from your repository root and reports the outcome.

If all checks pass, you can continue with your development workflow. If a check fails, you get feedback while the change is still local, making it easier to investigate and fix the issue before submission.

For Apex-only testing, you can also run:

agentia cicd work test apex --apex-test-classes HelloWorldTest

Replace HelloWorldTest with the Apex test class you want to run.

This command runs the specified Apex tests through Salesforce CLI and includes code coverage. You can use it when you want to focus on a particular Apex test suite without running every check in your project-level script.

3. Fix issues and rerun

A failed check doesn't have to interrupt your workflow. It gives you an opportunity to address the problem immediately.

For example, if an Apex test fails, inspect the failure message and stack trace, correct the underlying issue, and run the test again.

Agentia also supports rerunning previously failed Apex tests:

agentia cicd work test apex --rerun-failed-apex-tests

This can save time when you're iterating on a specific failure rather than rerunning the same failing classes manually.

Once the checks pass, you're ready to continue with your normal Git and Copado workflow.

4. Submit your User Story with confidence

Local quality gates aren't just a separate testing step. They're also part of the local User Story submission workflow.

agentia cicd work submit

When a project quality-gate script is configured, Agentia runs it before continuing with pipeline validation.

That means you can use the same checks during development and submission, helping catch issues earlier and making your workflow more consistent.

Remember that local quality gates complement your pipeline validation; they don't replace it.

The takeaway

Local quality gates help bring quality checks closer to where Salesforce development happens.

Instead of waiting until submission to discover a problem, you can run your checks locally, fix issues while the change is fresh in your mind, and move forward when you're ready.

And because the checks live in your repository, your team can share and maintain the same quality standards across its development workflow.

Less back-and-forth. Faster feedback. A smoother path from code to Copado.

Learn more

• Agentia Headless documentation
• Develop a metadata change: end-to-end training guide
• Agentia CLI: story → Git → Copado without the busywork