# Go Agent Exclusions

Use this guide to exclude packages and files from being scanned and reported as part of your [Application.](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/go-agent/go-agent-how-to-use/coverage-listener-mode-application-under-test#using-the-go-agent-in-coverage-listener-mode)

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) | <p>• Config file: <code>packagesExcludes</code> field in <code>slconfig.yaml</code><br>• CLI flag: <code>--excludePackages</code>, <code>--excludes</code>, or <code>--exclude</code><br>• Environment variable: <code>SL\_EXCLUDE\_PACKAGES</code> or <code>SEALIGHTS\_EXCLUDE\_PACKAGES</code> (set in build environment)</p> |
| **.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.

{% hint style="info" %}
Use Go package path syntax with this parameter. Append `/...` to include all subpackages (e.g., `./vendor/...` or `github.com/org/repo/...`).
{% endhint %}

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`

```bash
# 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`:

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

Then run:

```bash
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).

```bash
# 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:

```ignore
# 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 ](https://github.com/kenmueller/gitignore)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`](#using-excludepackages-exclude-go-packages) and [`.slignore`](#using-.slignore-exclude-files-or-directories)) 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

{% hint style="warning" %}
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.
{% endhint %}

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 ](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/go-agent/go-agent-v2/agent-configuration-parameters)documentation.