# Installation

## Prerequisites

### Python Version

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

```bash
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:

```bash
# 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
```

2. **Create a virtual environment** (recommended)

```bash
# Create virtual environment
python3 -m venv venv

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

# Activate on Windows
venv\Scripts\activate
```

3. **Install dependencies**

```bash
pip install requests
```

### Option 2: Manual installation

If you need to install dependencies manually:

1. **Extract the script package**

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

2. **Install requests library**

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

3. **Verify installation**

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

### Option 3: Using virtualenv (Legacy)

For older Python installations that use `virtualenv` instead of `venv`:

```bash
# 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:

```bash
python3 US_common.py --help
```

If using a settings-based script:

```bash
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](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md) for details.

Quick setup:

```bash
# 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

```bash
# Generate SSH key if you don't have one
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# 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:

```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"
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:

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

## Troubleshooting Installation

### ImportError: No module named 'requests'

Solution:

```bash
pip install requests
```

### Python version too old

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

```bash
# 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 errors

If you encounter permission issues:

```bash
# 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:

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

## Next Steps

* [Quick Start Guide](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/quick-start.md) - Run your first coverage report
* [Configuration Guide](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md) - Set up settings file with your credentials
* [CLI Reference](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md) - Learn about all available commands


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.