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

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

# Exclude multiple packages (repeat the flag)
slgoagent config --config slconfig.yaml \
  --excludePackages ./vendor/... \
  --excludePackages ./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 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).

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

# Option 2: SEALIGHTS_EXCLUDE_PACKAGES
export SEALIGHTS_EXCLUDE_PACKAGES="./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

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.