> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md).

# Configuration

User Story Coverage uses JSON settings files with environment variable overrides. Build the configuration in three parts: data sources, analytics scope, and publication targets.

{% hint style="info" %}
Use [Installation and first run](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/installation.md) for the first working setup.
{% endhint %}

### How configuration is organized

Use the child pages in this order:

{% stepper %}
{% step %}

### Choose your data sources

Start with [Data sources](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/data-sources.md).

This page defines where User Story Coverage reads source data from.

Use it to choose:

* Jira or Azure DevOps as the ticket source
* JQL or WIQL queries
* SeaLights, Git, and SCM connection settings
  {% endstep %}

{% step %}

### Define the analytics scope

Then use [Project analytics scope](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/project-analytics-scope.md).

This page defines what coverage data is included in the result.

Use it to choose:

* which SeaLights apps are in scope
* which repositories are included
* which test stages or grouped stages are reported
  {% endstep %}

{% step %}

### Choose the publication targets

Finish with [Publication targets](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/publication-targets.md).

This page defines where the output is published.

Use it to choose:

* Jira plugin, ADO plugin, or legacy Jira custom fields for KPIs
* Confluence for detailed reports
* target-specific publishing behavior and templates
  {% endstep %}
  {% endstepper %}

### Which page answers which question

Use these quick rules when you are not sure where a setting belongs:

* If you are asking **where does the source data come from?** — use [Data sources](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/data-sources.md)
* If you are asking **what coverage data is included?** — use [Project analytics scope](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/project-analytics-scope.md)
* If you are asking **where do the results go?** — use [Publication targets](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/publication-targets.md)

### Configuration files

By default, scripts look for a file named `settings` in the current directory.

You can also pass one or more `--settings` files.

Use [CLI Reference](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md) for exact command syntax and flag usage.

#### Multiple settings files

You can layer several settings files in one run.

#### Merge rules

* Single values are replaced by the last file.
* Arrays are appended.
* Objects are merged recursively.

#### Sample file

Start from `settings.sample` when you need a complete example.

### Environment variables

All settings can be overridden with environment variables.

Environment variables always win over settings files.

{% hint style="info" %}
Use [Environment variables](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#environment-variables) for the full variable table, JSON examples, and CI/CD patterns.
{% endhint %}

### Shared settings

#### Output folder

Use `output_folder` to control where generated files are saved.

```json
{
  "output_folder": "./reports"
}
```

Leave it empty to use the current directory.

### Validation

Scripts validate configuration at startup.

Check these first when a run fails:

* missing required fields
* invalid regex patterns
* invalid URLs
* invalid JSON passed through environment variables

### Best practices

* Split shared settings and secrets into different files.
* Prefer environment variables in CI/CD.
* Keep credentials out of version control.

{% hint style="warning" %}
Do not commit API tokens, passwords, or production credentials.
{% endhint %}

Use [Security Considerations](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/security-considerations.md) for credential, network, and CI/CD security practices.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.