Installation and first run

Get User Story Coverage running with the shortest working setup.

Get the shortest working setup here. Use Configuration 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.

1

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:

python3 --version

Git is only required for manual git-history tagging.

2

Extract the package and install dependencies

Extract the script package, then install requests.

unzip UserStoryCoverageTagging.zip
cd UserStoryCoverageTagging

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

Verify that the scripts load:

python3 US1_RPT_create_report_info_files.py --help

3

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 for token and permission guidance.

4

Create the base settings file

Start from the sample file:

cp settings.sample settings

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

Create the output folder:

mkdir -p reports

Add the shared settings first:

{
  "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": []
}

When to leave this page

Use Configuration for the full settings model.

Use Deployment patterns for advanced tagging, CI/CD, and end-to-end automation flows.

5

Generate the first local report

Use 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.

Choose your first publication path

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

Use the Jira plugin or ADO plugin when possible. Use Jira custom fields only as a fallback path.

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

1

Add the Jira source settings

{
  "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 for the full Jira query model.

2

Run the first report build

Use Report Generation and choose the Jira example for US1_RPT_create_report_info_files.py.

Generate HTML output after the data files are created.

3

Publish the Jira coverage update

Use Publish Analytics and run the Jira plugin updater flow.

📤 Expected Outcome

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

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

1

Add the Azure DevOps source settings

{
  "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 for the full WIQL model.

2

Run the first report build

Use 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.

3

Publish the Azure DevOps coverage update

Use Publish Analytics and run the ADO plugin updater flow.

📤 Expected Outcome

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

Legacy Jira

Use this when you are using legacy Jira custom fields.

Use this path only when the Jira plugin is not available.

✅ Prerequisites

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

🚀 Steps

1

Add the Jira source and field mapping

{
  "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 for the full legacy field model.

2

Run the first report build

Use Report Generation and choose the Jira example for US1_RPT_create_report_info_files.py.

Generate HTML output after the data files are created.

3

Publish the Jira custom field update

Use Publish Analytics and run the legacy Jira updater flow.

📤 Expected Outcome

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

Optional tagging workflows

Run a tagging script only if SeaLights auto-tagging is not enabled

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

Use Source Tagging for the exact pull request and git-history tagging commands.

Use FAQ if you need help with repo_list, monorepos, or app mapping.

Git and SSH setup is only needed for git-history tagging

Use this only with US_SRC_tag_repos_by_history.py.

ssh-keygen -t rsa -b 4096 -C "[e-mail]"
eval $(ssh-agent -s)
ssh-add ~/.ssh/id_rsa
cat ~/.ssh/id_rsa.pub

For private repos with a passphrase-protected key:

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"

Alternative install options

If you do not use a virtual environment:

python3 -m pip install --user requests

If your Python setup still uses virtualenv:

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

On Windows, activate the environment with:

venv\Scripts\activate

Python version too old

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

# macOS with Homebrew
brew install python@3.9

# Windows: download from python.org

Permission denied installing packages

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

SSL certificate errors during install

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

Common first-run checks

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

• Query returns no tickets — use FAQ
• Reports show 0% coverage — use Troubleshooting
• App or repo mapping looks wrong — use Project analytics scope

Use Troubleshooting when the first run fails and FAQ for common setup questions.

Do not disable SSL verification unless your environment requires it.

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:

pip install --upgrade requests

Next step

After the first run works, move to:

• Configuration
• Deployment patterns
• CLI Reference