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

# Installation and first run

Get the shortest working setup here. Use [Configuration](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md) when you need the full settings model.

### How the first run is organized

This page follows the shortest working path:

1. Check prerequisites and install the package.
2. Gather credentials and create a base settings file.
3. Generate the first local report.
4. Choose a publication path and publish the results.

{% stepper %}
{% step %}

### Check the prerequisites

You need:

* Python `3.7` or later
* Network access to SeaLights and your ticket system
* A SeaLights token and domain
* Jira or Azure DevOps access

Check Python:

```bash
python3 --version
```

{% hint style="info" %}
Git is only required for manual git-history tagging.
{% endhint %}
{% endstep %}

{% step %}

### Extract the package and install dependencies

Extract the script package, then install `requests`.

```bash
unzip UserStoryCoverageTagging.zip
cd UserStoryCoverageTagging

python3 -m venv venv
source venv/bin/activate
pip install requests
```

Verify that the scripts load:

```bash
python3 US1_RPT_create_report_info_files.py --help
```

{% endstep %}

{% step %}

### Gather the credentials first

You usually need:

* SeaLights API token and domain
* Jira authorization or Azure DevOps PAT
* SCM token only if you run manual tagging scripts

Use [Security Considerations](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/security-considerations.md) for token and permission guidance.
{% endstep %}

{% step %}

### Create the base settings file

Start from the sample file:

```bash
cp settings.sample settings
```

Then add your credentials, ticket query, SeaLights apps, and output folder.

Create the output folder:

```bash
mkdir -p reports
```

Add the shared settings first:

```json
{
  "output_folder": "./reports",
  "sealights": {
    "api_token": "your-sealights-api-token",
    "domain": "yourcompany.sealights.co",
    "coverage_days_back": 14
  },
  "scm": {
    "key_pattern_regex": "MYKEY-[0-9]*"
  },
  "test_stages": [
    {
      "name": "Unit_Tests",
      "reportJsonKey": "unit_tests",
      "reportTitle": "Unit Tests"
    }
  ],
  "coverage_app_list": [
    {
      "app_regex": "my-app",
      "branch_regex": "main"
    }
  ],
  "repo_list": []
}
```

<details>

<summary>When to leave this page</summary>

Use [Configuration](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md) for the full settings model.

Use [Deployment patterns](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/examples.md) for advanced tagging, CI/CD, and end-to-end automation flows.

</details>
{% endstep %}

{% step %}

### Generate the first local report

Use [Report Generation](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#report-generation) for the exact `US1_RPT_create_report_info_files.py` and `US2_RPT_create_html_reports.py` commands.

Choose `jira` when your ticket source is Jira. Choose `ado` when your ticket source is Azure DevOps.

#### Expected output sample

```
Loading settings from settings
Collecting ticket data
Creating coverage report data
Writing ReportInfo files to ./reports
Generating Summary.html
Done
```

Open `reports/Summary.html` after the run.
{% endstep %}
{% endstepper %}

### Choose your first publication path

Pick the target that matches your environment. Each path adds the source-specific settings, then publishes the first result.

{% hint style="info" %}
Use the Jira plugin or ADO plugin when possible. Use Jira custom fields only as a fallback path.
{% endhint %}

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

#### ✅ Prerequisites

* The base settings file already exists
* Jira access already works
* The Jira plugin is installed

#### 🚀 Steps

{% stepper %}
{% step %}

### Add the Jira source settings

```json
{
  "jira": {
    "authorization": "Basic your-base64-encoded-credentials",
    "jql": "project = MYPROJECT AND created > startOfMonth(-1)",
    "child_levels": 1,
    "base_url": "https://yourcompany.atlassian.net",
    "api_version": 3,
    "notify_users": false
  },
  "scm": {
    "key_pattern_regex": "MYKEY-[0-9]*",
    "type": "github"
  }
}
```

Use [Data sources](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/data-sources.md) for the full Jira query model.
{% endstep %}

{% step %}

### Run the first report build

Use [Report Generation](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#report-generation) and choose the Jira example for `US1_RPT_create_report_info_files.py`.

Generate HTML output after the data files are created.
{% endstep %}

{% step %}

### Publish the Jira coverage update

Use [Publish Analytics](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#publish-analytics) and run the Jira plugin updater flow.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

```
Loaded Jira issues from JQL
Created ReportInfo files
Generated Summary.html
Updated Jira plugin coverage fields
Done
```

{% endtab %}

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

#### ✅ Prerequisites

* The base settings file already exists
* Azure DevOps organization, project, and PAT are ready
* The ADO plugin is installed

#### 🚀 Steps

{% stepper %}
{% step %}

### Add the Azure DevOps source settings

```json
{
  "ado": {
    "wiql": "SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType] = 'User Story' AND [System.ChangedDate] >= @Today - 30",
    "authorization": "Basic your-pat-token",
    "organization": "your-org",
    "project": "your-project",
    "child_levels": 1
  },
  "scm": {
    "key_pattern_regex": "[0-9]+",
    "type": "ado"
  }
}
```

Your PAT must allow work item read access and extension data read/write access. Use [Data sources](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/data-sources.md) for the full WIQL model.
{% endstep %}

{% step %}

### Run the first report build

Use [Report Generation](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#report-generation) and choose the Azure DevOps example for `US1_RPT_create_report_info_files.py`.

Generate HTML output after the data files are created.
{% endstep %}

{% step %}

### Publish the Azure DevOps coverage update

Use [Publish Analytics](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#publish-analytics) and run the ADO plugin updater flow.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

```
Loaded Azure DevOps work items from WIQL
Created ReportInfo files
Generated Summary.html
Updated Azure DevOps plugin coverage fields
Done
```

{% endtab %}

{% tab title="Legacy Jira" %}
Use this when you are using legacy Jira custom fields.

{% hint style="warning" %}
Use this path only when the Jira plugin is not available.
{% endhint %}

#### ✅ Prerequisites

* The base settings file already exists
* Jira access already works
* The target Jira custom field IDs are known

#### 🚀 Steps

{% stepper %}
{% step %}

### Add the Jira source and field mapping

```json
{
  "jira": {
    "authorization": "Basic your-base64-encoded-credentials",
    "jql": "project = MYPROJECT AND created > startOfMonth(-1)",
    "child_levels": 1,
    "base_url": "https://yourcompany.atlassian.net",
    "api_version": 3,
    "notify_users": false,
    "jira_custom_fields": {
      "summary_rich": {
        "id": "customfield_10918",
        "template_file": "summary_template.json"
      },
      "coverage": {
        "overall": "customfield_10900",
        "unit_tests": "customfield_10901"
      }
    }
  },
  "scm": {
    "key_pattern_regex": "MYKEY-[0-9]*",
    "type": "github"
  }
}
```

Use [Publication targets](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/publication-targets.md) for the full legacy field model.
{% endstep %}

{% step %}

### Run the first report build

Use [Report Generation](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#report-generation) and choose the Jira example for `US1_RPT_create_report_info_files.py`.

Generate HTML output after the data files are created.
{% endstep %}

{% step %}

### Publish the Jira custom field update

Use [Publish Analytics](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#publish-analytics) and run the legacy Jira updater flow.
{% endstep %}
{% endstepper %}

#### 📤 Expected Outcome

```
Loaded Jira issues from JQL
Created ReportInfo files
Generated Summary.html
Updated Jira custom fields
Done
```

{% endtab %}
{% endtabs %}

### Optional tagging workflows

<details>

<summary>Run a tagging script only if SeaLights auto-tagging is not enabled</summary>

If SeaLights already tags ticket IDs from build metadata, skip this section.

Use [Source Tagging](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#source-tagging) for the exact pull request and git-history tagging commands.

Use [FAQ](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/faq.md) if you need help with `repo_list`, monorepos, or app mapping.

</details>

<details>

<summary>Git and SSH setup is only needed for git-history tagging</summary>

Use this only with `US_SRC_tag_repos_by_history.py`.

```bash
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
eval $(ssh-agent -s)
ssh-add ~/.ssh/id_rsa
cat ~/.ssh/id_rsa.pub
```

For private repos with a passphrase-protected key:

```bash
export GIT_SSH_KEYFILE=~/.ssh/id_rsa
export GIT_PASSPHRASE="your-passphrase"

eval $(ssh-agent -s -t 1800)
ssh-add -t 1800 ${GIT_SSH_KEYFILE} <<< "$GIT_PASSPHRASE"
```

</details>

<details>

<summary>Alternative install options</summary>

If you do not use a virtual environment:

```bash
python3 -m pip install --user requests
```

If your Python setup still uses `virtualenv`:

```bash
pip install virtualenv
virtualenv venv
source venv/bin/activate
pip install requests
```

On Windows, activate the environment with:

```bash
venv\Scripts\activate
```

</details>

<details>

<summary>Python version too old</summary>

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install python3.9

# macOS with Homebrew
brew install python@3.9

# Windows: download from python.org
```

</details>

<details>

<summary>Permission denied installing packages</summary>

```bash
pip install --user requests
# or, not recommended for production:
sudo pip install requests
```

</details>

<details>

<summary>SSL certificate errors during install</summary>

```bash
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org requests
```

</details>

<details>

<summary>Common first-run checks</summary>

If the run completes but the results are wrong, start here:

* Query returns no tickets — use [FAQ](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/faq.md)
* Reports show `0%` coverage — use [Troubleshooting](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/troubleshooting.md)
* App or repo mapping looks wrong — use [Project analytics scope](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/project-analytics-scope.md)

</details>

Use [Troubleshooting](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/troubleshooting.md) when the first run fails and [FAQ](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/faq.md) for common setup questions.

{% hint style="warning" %}
Do not disable SSL verification unless your environment requires it.
{% endhint %}

#### Upgrade the tool

1. Contact your SeaLights Customer Success representative to receive the updated script package.
2. Extract the new package to replace your existing scripts.
3. If dependencies changed, reinstall them:

```bash
pip install --upgrade requests
```

### Next step

After the first run works, move to:

* [Configuration](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md)
* [Deployment patterns](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/examples.md)
* [CLI Reference](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md)


---

# 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/installation.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.