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
packages-excluded	Go module packages (entire packages/package trees)	• Config file: packagesExcludes field in slconfig.yaml • CLI flag: --packages-excluded, --excludes, or --exclude • Environment variable: SEALIGHTS_PACKAGES_EXCLUDED or SL_PACKAGES_EXCLUDED (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 packages-excluded 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 packages-excluded (Exclude Go Packages)

Use the packages-excluded 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):

• --packages-excluded

• --excludes

• --exclude

# Exclude a single package
slgoagent config --config slconfig.yaml --packages-excluded ./vendor/...
slgoagent scan

# Exclude multiple packages (repeat the flag)
slgoagent config --config slconfig.yaml \
  --packages-excluded ./vendor/... \
  --packages-excluded ./mocks/...
slgoagent scan

Method 2: Configuration File (Recommended)

Add the packagesExcludes field to your slconfig.yaml:

appName: "my-application"
branch: "main"
# ...
packagesExcludes:
  - "./vendor/..."
  - "./mocks/..."

Then run:

slgoagent config --config slconfig.yaml
slgoagent scan

Method 3: Environment Variables

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

# Option 1: SEALIGHTS_PACKAGES_EXCLUDED
export SEALIGHTS_PACKAGES_EXCLUDED="./vendor/...,./mocks/..."
slgoagent config --config slconfig.yaml
slgoagent scan

# Option 2: SL_PACKAGES_EXCLUDED
export SL_PACKAGES_EXCLUDED="./vendor/...,./mocks/..."
slgoagent config --config slconfig.yaml
slgoagent scan

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:

# Comments start with #
# Exclude generated code
**/generated/*.go

# Exclude mock files
**/*_mock.go
**/mocks/**

# Exclude test data
**/testdata/**

# Exclude specific files
internal/legacy/old_code.go

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

Test File Behavior

The SeaLights Go Agent handles test files (*_test.go) like so:

• Test files are NOT included in the build scan/build map by default (without adding these files to your exclusions)

• Test files ARE instrumented during the slgoagent scan command

Unit Test coverage is automatically collected and reported to SeaLights as long as those unit test files were instrumented during the ./slgoagent scan command.

Unit Test files must be instrumented for SeaLights to automatically report Unit Test Coverage to SeaLights

Tips

• Use ./package/... syntax to exclude a package and all its sub-packages (with packages-excluded 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 packages-excluded is too broad

• To manage the packages-excluded parameter with environment variables, these 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.