Ctrlk
Contact SupportProduct

Go Agent Exclusions

How to exclude Go packages (modules), files, or directories from the SeaLights scan and instrumentation

Use this guide to exclude packages and files from being scanned and reported as part of your Application.

When you run slgoagent scan, the agent scans your project structure and reports it to SeaLights, while also instrumenting the code in your project workspace. If you see vendor code, generated files, mocks, or other code in your scan results (on your coverage report in SeaLights) that cannot or should not be tested, you can use exclusions to prevent them from being included in the scan.

Quick Reference

The Sealights Go Agent supports two types of exclusions:

Exclusion Type
What It Excludes
How to Apply

excludePackages

Go module packages (entire packages/package trees)

• Config file: packagesExcludes field in slconfig.yaml • CLI flag: --excludePackages, --excludes, or --exclude • Environment variable: SL_EXCLUDE_PACKAGES or SEALIGHTS_EXCLUDE_PACKAGES (set in build environment)

.slignore file

Specific files and directories (glob patterns)

• Create a .slignore file in your project root directory

When to Use Which

  • Use excludePackages for: vendor dependencies, third-party modules, entire go.mod package subtrees

  • Use .slignore for: specific files, generated code, mock files, test data directories, individual legacy files

Using excludePackages (Exclude Go Packages)

Use the excludePackages parameter to exclude entire Go packages (Go modules) from being scanned and reported to SeaLights. This is the recommended approach for excluding vendor code, third-party modules, or entire package directories that appear in your scan results.

Use Go package path syntax with this parameter. Append /... to include all subpackages (e.g., ./vendor/... or github.com/org/repo/...).

The typical workflow is:

  1. Run slgoagent config to configure the agent (to apply exclusions during the next step)

  2. Run slgoagent scan to scan and instrument your code

Method 1: Command Line Flags

You can use any of these flag names (they all do the same thing):

  • --excludePackages

Method 2: Configuration File (Recommended)

Add the packagesExcludes field to your slconfig.yaml:

Then run:

Method 3: Environment Variables

The environment variables SL_EXCLUDE_PACKAGES and SEALIGHTS_EXCLUDE_PACKAGES do the same thing. Set these in your build environment where the slgoagent commands run (e.g., in your CI pipeline configuration).

Note: When using environment variables, separate multiple packages with commas.

Using .slignore (Exclude Files or Directories)

Use a .slignore file to exclude specific files and directories from being scanned. This works like a .gitignore file and is useful when you need more granular control than package-level exclusions.

Creating a .slignore File

Create a .slignore file in your project root directory:

Pattern Syntax

The .slignore file follows the same syntax as .gitignore :

  • ** matches any number of directories

  • * matches any characters within a directory

  • Lines starting with # are comments

  • Empty lines are ignored

How Exclusions Are Applied

The two exclusion mechanisms (excludePackages and .slignore) operate at different levels and are evaluated in a specific order during slgoagent scan:

  1. Package-level filtering happens first. The excludePackages (and includePackages) parameters are set during slgoagent config and take effect when slgoagent scan runs. Any package that matches an exclude pattern (or falls outside the include patterns) is dropped entirely -- none of its files are processed.

  2. File-level filtering happens second. For each package that passed the package-level filter, the agent checks every source file against the .slignore patterns. Matching files are skipped while the rest of the package is scanned normally.

This layered approach means the two mechanisms complement each other rather than overlap. Use excludePackages to remove broad sections of your codebase at the package level, and use .slignore for surgical, file-level exclusions within packages you otherwise want scanned. For example, you might exclude ./vendor/... entirely with excludePackages, while using .slignore to skip a handful of generated protobuf files (**/*.pb.go) inside your own internal/ package.

Test File Behavior

If you expect SeaLights to collect and report unit test coverage, do not exclude test files (*_test.go) from the scan. Excluding test files prevents their instrumentation, and their coverage will not be reported.

The SeaLights Go Agent handles test files (*_test.go) in the following way:

  • Test files are NOT included in the build scan/build map by default. This happens automatically and does not require adding _test.go files to your exclusions.

  • Test files ARE instrumented during the slgoagent scan command. This enables the agent to capture their execution and coverage.

Unit Test coverage is automatically collected and reported to SeaLights as long as the corresponding test files were instrumented during the slgoagent scan step.

Tips

  • Use ./packagename/... syntax to exclude a package and all its sub-packages (with --excludePackages only)

  • Start with minimal exclusions and add more as needed

  • Test your exclusions by running slgoagent config --log-level debug and slgoagent scan to see what's being scanned

  • Use .slignore for file-level or directory-level control when --excludePackages is too broad

  • To manage the --excludePackages parameter with environment variables, the variables must be set in the build environment where slgoagent config and slgoagent scan run

For more information about configuration options, see the Go Agent Configuration Parameters documentation.

PreviousGo Agent Parameter Reference TableNextGo Agent V1 (Deprecated)

Last updated

Was this helpful?