> 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/data-sources.md).

# Data sources

Connect User Story Coverage to the systems that supply report input. Configure the work item query, SeaLights source, and SCM extraction rules here.

### How data sources are organized

Most setups combine three input types:

1. **Work item source** — choose the Jira or Azure DevOps query that defines the report scope.
2. **SeaLights** — connect to the coverage source and report-generation settings.
3. **Git and SCM** — extract ticket IDs from commits, branches, or pull requests.

### Which section answers which question

* **Which tickets or work items should the report include?** — use **Work item source**.
* **Which SeaLights account and report window should the report use?** — use **SeaLights**.
* **How are ticket IDs extracted from source control activity?** — use **Git and SCM**.

### Work item source

User Story Coverage supports query-based work item selection from Jira and Azure DevOps.

#### Typical use cases

* Report coverage for the current sprint
* Report coverage for a specific epic or release
* Publish coverage for work items changed in a date range

#### Query model

Use a query that returns the exact work items you want in the report.

Keep queries narrow. Start with a sprint, iteration, epic, or recent date range.

Test the query in Jira or Azure DevOps before you run report generation.

Use these settings when Jira or Azure DevOps supplies the work items for your report. Configure the source query here, then keep publishing target settings in [Publication targets](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/publication-targets.md).

{% tabs %}
{% tab title="Jira" %}
Use this when you are using Jira.

#### ✅ Prerequisites

* A Jira base URL
* An authorization header value
* A JQL query that already works in Jira

#### 🚀 Steps

{% stepper %}
{% step %}

### Add the Jira settings block

```json
{
  "jira": {
    "authorization": "Basic base64-encoded-credentials",
    "jql": "project = MYPROJ AND created > startOfMonth(-1)",
    "base_url": "https://yourcompany.atlassian.net",
    "api_version": 3,
    "child_levels": 2,
    "on_prem": false
  }
}
```

{% endstep %}

{% step %}

### Set the required fields

* `authorization` — required authorization header value.
* `jql` — required Jira query.
* `base_url` — required Jira instance URL.
* `api_version` — required REST API version.

Use `child_levels` when parent issues need child issue coverage. Set `on_prem` to `true` for Jira Server or Data Center.
{% endstep %}

{% step %}

### Validate the query

Run the JQL in Jira first. Keep the result set narrow and predictable.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

The query returns the exact Jira issues for the report. Child issue expansion follows `child_levels`.

<details>

<summary>Query examples</summary>

```
project = MYPROJ AND created >= -30d
issueType = Story AND sprint in openSprints()
labels = sprint-42 AND status != Closed
```

</details>
{% endtab %}

{% tab title="Azure DevOps" %}
Use this when you are using Azure DevOps.

#### ✅ Prerequisites

* An Azure DevOps organization and project
* A PAT-based authorization header value
* A WIQL query that already works in Azure DevOps

#### 🚀 Steps

{% stepper %}
{% step %}

### Add the Azure DevOps settings block

```json
{
  "ado": {
    "wiql": "SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType] = 'User Story' AND [System.ChangedDate] >= @Today - 30",
    "authorization": "Basic base64-pat-token",
    "organization": "your-organization",
    "project": "your-project",
    "child_levels": 2
  }
}
```

{% endstep %}

{% step %}

### Set the required fields

* `wiql` — required work item query.
* `authorization` — required PAT-based authorization header.
* `organization` — required Azure DevOps organization.
* `project` — required project name.

Use `child_levels` when parent work items need child work item coverage.
{% endstep %}

{% step %}

### Validate the WIQL

Run the WIQL in Azure DevOps first. Use field names that exist on the returned work item type.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

The query returns the exact work items for the report. Child work item expansion follows `child_levels`.

<details>

<summary>Common field examples</summary>

* `System.TeamProject`
* `System.State`
* `System.AssignedTo`
* `System.IterationPath`

</details>
{% endtab %}
{% endtabs %}

### SeaLights

Use the `sealights` block for authentication and report generation behavior.

{% stepper %}
{% step %}

### Add the SeaLights settings block

```json
{
  "sealights": {
    "api_token": "your-api-token",
    "domain": "yourcompany.sealights.co",
    "coverage_days_back": 14,
    "report_timeout_minutes": 30,
    "use_repository_url": false,
    "verify_ssl": true
  }
}
```

{% endstep %}

{% step %}

### Set authentication and coverage window

* `api_token` — required SeaLights API token.
* `domain` — required SeaLights account domain.
* `coverage_days_back` — required coverage lookback window.
  {% endstep %}

{% step %}

### Set report behavior

* `report_timeout_minutes` — optional wait limit for report generation.
* `use_repository_url` — optional use repository URLs from SeaLights.
* `verify_ssl` — optional SSL verification toggle.
  {% endstep %}
  {% endstepper %}

### Git and SCM

Use the `scm` block to extract ticket IDs from commits and branches.

{% stepper %}
{% step %}

### Add the SCM settings block

```json
{
  "scm": {
    "key_pattern_regex": "PROJ-[0-9]+",
    "github_api_url": "https://api.github.com",
    "github_token": "ghp_xxxxxxxxxxxx",
    "github_owner": "your-organization",
    "type": "github",
    "remove_prefix_regex": "^refs/heads/"
  }
}
```

{% endstep %}

{% step %}

### Set extraction rules

* `key_pattern_regex` — required regex for ticket extraction.
* `type` — required SCM type: `github`, `gitlab`, `bitbucket`, or `ado`.
* `remove_prefix_regex` — optional branch-name cleanup regex.
  {% endstep %}

{% step %}

### Add provider-specific fields

* `github_api_url` — GitHub API endpoint when using GitHub.
* `github_token` — GitHub token when using GitHub.
* `github_owner` — GitHub organization or user.
  {% endstep %}
  {% endstepper %}

#### Regex examples

* Jira keys — `"[A-Z]+-[0-9]+"`
* GitHub issues — `"#[0-9]+"`
* Azure DevOps IDs — `"[0-9]+"`
* Custom multi-type pattern — `"\\[(FEAT|BUG|TASK)-[0-9]+\\]"` — matches commit messages like `[FEAT-123] Add user authentication` or `[BUG-456] Fix login redirect issue`

### Validation tips

* Confirm your regex matches real commit messages.
* Keep `coverage_days_back` long enough for your release cycle.
* Test Jira queries and WIQL queries in the source system first.
* Leave `verify_ssl` enabled unless troubleshooting requires otherwise.

Use [Source Tagging](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#source-tagging) for source-tagging command details and [FAQ](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/faq.md) for common query questions.


---

# 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/data-sources.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.