Installation

Prerequisites

Python Version

This tool requires Python 3.7 or higher. To check your Python version:

python3 --version

Required Python Packages

The tool uses the following Python standard and third-party libraries:

• requests - For API calls to SeaLights, Jira, ADO, GitHub, and Confluence

• Standard library modules: os, re, json, time, logging, argparse, typing, urllib, collections, concurrent.futures

System Requirements

• Network access - To SeaLights, issue tracker APIs, and source control platforms

Optional (only for certain tagging workflows):

• Git - Only required if using US_SRC_tag_repos_by_history.py (clones/pulls repositories). Not needed for:

  • SeaLights auto-tagging (recommended approach)

  • GitHub PR-based tagging (US_SRC_tag_repos_by_github_prs.py)

  • Report generation scripts (US_RPT_*)

• SSH keys - Only if using git-based tagging with private repositories

Platform Support

The tool is platform-independent and runs on:

• Linux

• macOS

• Windows (with Python installed)

Installation Steps

Option 1: Install with pip (Recommended)

1. Extract the script package

You will receive the User Story Coverage Tagging scripts as a package from SeaLights. Extract the package to your desired location:

# Extract the package (adjust filename as needed)
unzip UserStoryCoverageTagging.zip
cd UserStoryCoverageTagging

# Or if received as tar.gz
tar -xzf UserStoryCoverageTagging.tar.gz
cd UserStoryCoverageTagging

1. Create a virtual environment (recommended)

# Create virtual environment
python3 -m venv venv

# Activate on Linux/macOS
source venv/bin/activate

# Activate on Windows
venv\Scripts\activate

1. Install dependencies

pip install requests

Option 2: Manual installation

If you need to install dependencies manually:

1. Extract the script package

# Extract to your desired location
unzip UserStoryCoverageTagging.zip
cd UserStoryCoverageTagging

1. Install requests library

python3 -m pip install --user requests

1. Verify installation

python3 -c "import requests; print(requests.__version__)"

Option 3: Using virtualenv (Legacy)

For older Python installations that use virtualenv instead of venv:

# Navigate to extracted scripts directory
cd UserStoryCoverageTagging

# Install virtualenv if not already installed
pip install virtualenv

# Create virtual environment
virtualenv venv

# Activate
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate  # Windows

# Install dependencies
pip install requests

Verify Installation

Test that the scripts can be executed:

python3 US_common.py --help

If using a settings-based script:

python3 US1_RPT_create_report_info_files.py --help

Expected output should show the script's help text with available options.

Configuration Setup

Before running scripts, you need to create a settings file. See the Configuration Guide for details.

Quick setup:

# Copy the sample settings file
cp settings.sample settings

# Edit the settings file with your credentials and configuration
nano settings  # or your preferred editor

Git Authentication Setup (Only for Git-Based Tagging)

Skip this section if:

• You're using SeaLights auto-tagging

• You're only generating reports (US_RPT_* scripts)

• You're using GitHub PR-based tagging (doesn't clone repos)

Only needed if:

• Using US_SRC_tag_repos_by_history.py which clones/pulls repositories

Configure git authentication:

SSH Key Setup

# Generate SSH key if you don't have one
ssh-keygen -t rsa -b 4096 -C "[email protected]"

# Add SSH key to ssh-agent
eval $(ssh-agent -s)
ssh-add ~/.ssh/id_rsa

# Copy public key to your git provider (GitHub, GitLab, etc.)
cat ~/.ssh/id_rsa.pub

Using SSH Key with Passphrase

For automation 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"
python3 US_SRC_tag_repos_by_history.py --settings settings --days-back 30
ssh-agent -k

Upgrading

To upgrade to the latest version:

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 change, reinstall:

pip install --upgrade requests

Troubleshooting Installation

ImportError: No module named 'requests'

Solution:

pip install requests

Python version too old

If python3 --version shows Python 3.6 or earlier, upgrade Python:

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

# macOS with Homebrew
brew install [email protected]

# Windows: Download from python.org

Permission denied errors

If you encounter permission issues:

# Use --user flag for pip
pip install --user requests

# Or use sudo (not recommended for production)
sudo pip install requests

SSL Certificate errors

If you encounter SSL verification errors during installation:

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

Next Steps

• Quick Start Guide - Run your first coverage report

• Configuration Guide - Set up settings file with your credentials

• CLI Reference - Learn about all available commands