# Examples

Real-world usage examples and workflows for the User Story Coverage Tagging tool.

## Table of Contents

* [Complete End-to-End Workflow](#complete-end-to-end-workflow)
* [Tagging Workflows](#tagging-workflows)
* [Reporting Workflows](#reporting-workflows)
* [CI/CD Integration](#cicd-integration)
* [Advanced Scenarios](#advanced-scenarios)

***

## Complete End-to-End Workflow

### Sprint Coverage Report Generation

Generate comprehensive coverage reports for all user stories in a sprint.

```bash
#!/bin/bash
# sprint_coverage_report.sh

# Configuration
export SETTINGS_FILE="settings"
export DAYS_BACK=30

# Step 1: Tag code changes from GitHub PRs
echo "==> Tagging code changes from pull requests..."
python3 US_SRC_tag_repos_by_github_prs.py \
  --settings ${SETTINGS_FILE} \
  --days-back ${DAYS_BACK} \
  --log-level INFO

# Step 2: Generate report data files from Jira
echo "==> Generating coverage report data..."
python3 US1_RPT_create_report_info_files.py \
  --settings ${SETTINGS_FILE} \
  --ticket-source jira \
  --log-level INFO

# Step 3: Create HTML reports
echo "==> Creating HTML reports..."
python3 US2_RPT_create_html_reports.py \
  --settings ${SETTINGS_FILE} \
  --log-level INFO

# Step 4: Create Confluence pages
echo "==> Publishing to Confluence..."
python3 US3_RPT_create_confluence_reports.py \
  --settings ${SETTINGS_FILE} \
  --log-level INFO

# Step 5: Update Jira tickets with coverage
echo "==> Updating Jira tickets..."
python3 US4_RPT_update_jira.py \
  --settings ${SETTINGS_FILE} \
  --log-level INFO

echo "==> Sprint coverage report complete!"
echo "View reports in: $(grep -o '"output_folder"[^,]*' ${SETTINGS_FILE} | cut -d'"' -f4)"
```

**Expected Output:**

```
==> Tagging code changes from pull requests...
2026-02-02 10:00:00 INFO: Reading settings file 'settings
2026-02-02 10:00:01 INFO: Working on frontend-app PR #123
2026-02-02 10:00:02 INFO: Tagged 15 files for PROJ-456
...
==> Generating coverage report data...
2026-02-02 10:05:00 INFO: Found 12 tickets matching JQL query
2026-02-02 10:05:05 INFO: Generating report, id=abc123
...
==> Creating HTML reports...
2026-02-02 10:10:00 INFO: Created reports/PROJ-456.html
2026-02-02 10:10:01 INFO: Created reports/Summary.html
...
==> Publishing to Confluence...
2026-02-02 10:12:00 INFO: Created page: Sprint 42 Coverage - PROJ-456
...
==> Updating Jira tickets...
2026-02-02 10:15:00 INFO: Updated PROJ-456 with 78% coverage
...
==> Sprint coverage report complete!
View reports in: ./reports
```

### Sprint Coverage Report (with SeaLights Auto-Tagging)

If SeaLights auto-tagging is enabled, skip the manual tagging step:

```bash
#!/bin/bash
# sprint_coverage_report_autotagged.sh

# Configuration
export SETTINGS_FILE="settings"

# Note: Tagging happens automatically in SeaLights when builds are reported

# Step 1: Generate report data files from Jira
echo "==> Generating coverage report data..."
python3 US1_RPT_create_report_info_files.py \
  --settings ${SETTINGS_FILE} \
  --ticket-source jira \
  --log-level INFO

# Step 2: Create HTML reports
echo "==> Creating HTML reports..."
python3 US2_RPT_create_html_reports.py \
  --settings ${SETTINGS_FILE} \
  --log-level INFO

# Step 3: Create Confluence pages
echo "==> Publishing to Confluence..."
python3 US3_RPT_create_confluence_reports.py \
  --settings ${SETTINGS_FILE} \
  --log-level INFO

# Step 4: Update Jira tickets with coverage
echo "==> Updating Jira tickets..."
python3 US4_RPT_update_jira.py \
  --settings ${SETTINGS_FILE} \
  --log-level INFO

echo "==> Sprint coverage report complete!"
```

**Benefits:**

* Simpler workflow—no tagging scripts to maintain
* Faster execution—one less phase
* Tagging happens automatically with each build

**Requirements:**

* SeaLights auto-tagging configured by Customer Success
* CI/CD pipeline reports builds with git commit information

***

## Tagging Workflows

### Example 1: Tag from GitHub Pull Requests

Tag code changes from PRs merged in the last 14 days.

```bash
python3 US_SRC_tag_repos_by_github_prs.py \
  --settings settings \
  --days-back 14 \
  --log-level INFO
```

**Settings Requirements:**

```json
{
  "scm": {
    "github_api_url": "https://api.github.com",
    "github_token": "ghp_xxxxxxxxxxxx",
    "github_owner": "mycompany",
    "key_pattern_regex": "PROJ-[0-9]+"
  },
  "repo_list": [
    {
      "repoName": "frontend-app",
      "SealightsAppName": "frontend",
      "SealightsBranchName": "main"
    }
  ]
}
```

### Example 2: Tag from Git Commit History

Tag code changes by analyzing commit history.

```bash
python3 US_SRC_tag_repos_by_history.py \
  --settings settings \
  --since-date 2026-01-01 \
  --log-level INFO
```

**Use Case:** When PRs aren't used, or you need to capture direct commits.

### Example 3: Tag from Jira-Linked PRs

Process only PRs linked to specific Jira tickets.

```bash
python3 US_SRC_tag_repos_by_jira_github_prs.py \
  --settings settings \
  --days-back 30
```

**Settings Requirements:**

```json
{
  "jira": {
    "jql": "project = PROJ AND sprint in openSprints()"
  }
}
```

**Use Case:** Focus tagging on actively worked tickets in current sprint.

### Example 4: Dry Run - Generate Files Without Tagging

Preview what would be tagged without actually calling SeaLights API.

```bash
python3 US_SRC_tag_repos_by_history.py \
  --settings settings \
  --days-back 7 \
  --only_create_files
```

**Output:** Creates JSON files in output folder without making API calls.

### Example 5: Tag Specific Build by BSID

Tag an entire build session with a ticket ID.

```bash
python3 US_SRC_tag_build_in_sealights.py \
  --domain company.sealights.co \
  --token your-api-token \
  --ticket PROJ-789 \
  --bsid abc123def456789 \
  --log-level INFO
```

**Use Case:** Manually associate a build with a ticket after the fact.

***

## Reporting Workflows

### Example 6: Generate Reports for Azure DevOps

Create coverage reports for ADO work items.

```bash
# Step 1: Generate report data
python3 US1_RPT_create_report_info_files.py \
  --settings settings \
  --ticket-source ado

# Step 2: Create HTML reports
python3 US2_RPT_create_html_reports.py \
  --settings settings

# Step 3: Update ADO plugin
python3 US4_RPT_update_ado_plugin.py \
  --settings settings
```

**Settings Requirements:**

```json
{
  "ado": {
    "wiql": "SELECT [System.Id] FROM WorkItems WHERE [System.IterationPath] = 'Sprint 42'",
    "organization": "mycompany",
    "project": "MyProject"
  }
}
```

### Example 7: Reuse Existing Coverage Report

Skip report generation and use an existing report ID.

```bash
python3 US1_RPT_create_report_info_files.py \
  --settings settings \
  --report-id abc123def456789 \
  --ticket-source jira
```

**Use Case:** When regenerating report files without waiting for new coverage analysis.

### Example 8: Create Only HTML Reports

Generate HTML without updating issue trackers or Confluence.

```bash
python3 US2_RPT_create_html_reports.py \
  --settings settings \
  --log-level DEBUG
```

**Output:** HTML files in output folder, viewable in any browser.

### Example 9: Update Jira On-Premises Plugin

Push coverage to Jira On-Prem plugin instead of Cloud custom fields.

```bash
python3 US4_RPT_update_jira_plugin.py \
  --settings settings
```

**Settings Requirements:**

```json
{
  "jira": {
    "base_url": "https://jira.mycompany.com",
    "api_version": "1.0",
    "authorization": "Basic base64-credentials"
  }
}
```

***

## CI/CD Integration

### Example 10: GitHub Actions Workflow

```yaml
# .github/workflows/coverage-report.yml
name: User Story Coverage Report

on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM
  workflow_dispatch:

jobs:
  generate-coverage-report:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'

      - name: Install dependencies
        run: pip install requests

      - name: Tag PRs
        env:
          SEALIGHTS_API_TOKEN: ${{ secrets.SEALIGHTS_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          JIRA_AUTHORIZATION: ${{ secrets.JIRA_AUTH }}
        run: |
          python3 US_SRC_tag_repos_by_github_prs.py \
            --settings settings \
            --days-back 30

      - name: Generate reports
        env:
          SEALIGHTS_API_TOKEN: ${{ secrets.SEALIGHTS_TOKEN }}
          JIRA_AUTHORIZATION: ${{ secrets.JIRA_AUTH }}
        run: |
          python3 US1_RPT_create_report_info_files.py \
            --settings settings \
            --ticket-source jira
          python3 US2_RPT_create_html_reports.py \
            --settings settings

      - name: Upload reports
        uses: actions/upload-artifact@v3
        with:
          name: coverage-reports
          path: reports/*.html

      - name: Update Jira
        env:
          JIRA_AUTHORIZATION: ${{ secrets.JIRA_AUTH }}
        run: |
          python3 US4_RPT_update_jira.py --settings settings
```

### Example 11: Jenkins Pipeline

```groovy
// Jenkinsfile
pipeline {
    agent any

    environment {
        SEALIGHTS_API_TOKEN = credentials('sealights-token')
        JIRA_AUTHORIZATION = credentials('jira-auth')
        GITHUB_TOKEN = credentials('github-pat')
    }

    stages {
        stage('Setup') {
            steps {
                sh 'pip install requests'
            }
        }

        stage('Tag Code Changes') {
            steps {
                sh '''
                    python3 US_SRC_tag_repos_by_github_prs.py \
                        --settings settings \
                        --days-back 30 \
                        --log-level INFO
                '''
            }
        }

        stage('Generate Reports') {
            steps {
                sh '''
                    python3 US1_RPT_create_report_info_files.py \
                        --settings settings \
                        --ticket-source jira
                    python3 US2_RPT_create_html_reports.py \
                        --settings settings
                '''
            }
        }

        stage('Publish') {
            parallel {
                stage('Confluence') {
                    steps {
                        sh 'python3 US3_RPT_create_confluence_reports.py --settings settings'
                    }
                }
                stage('Jira') {
                    steps {
                        sh 'python3 US4_RPT_update_jira.py --settings settings'
                    }
                }
            }
        }
    }

    post {
        always {
            archiveArtifacts artifacts: 'reports/**/*.html', fingerprint: true
        }
    }
}
```

### Example 12: GitLab CI/CD

```yaml
# .gitlab-ci.yml
variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

cache:
  paths:
    - .cache/pip

stages:
  - tag
  - report
  - publish

tag_code_changes:
  stage: tag
  image: python:3.9
  before_script:
    - pip install requests
  script:
    - |
      python3 US_SRC_tag_repos_by_github_prs.py \
        --settings settings \
        --days-back 30
  only:
    - schedules

generate_reports:
  stage: report
  image: python:3.9
  before_script:
    - pip install requests
  script:
    - |
      python3 US1_RPT_create_report_info_files.py \
        --settings settings \
        --ticket-source jira
      python3 US2_RPT_create_html_reports.py \
        --settings settings
  artifacts:
    paths:
      - reports/
    expire_in: 7 days
  only:
    - schedules

publish_confluence:
  stage: publish
  image: python:3.9
  before_script:
    - pip install requests
  script:
    - python3 US3_RPT_create_confluence_reports.py --settings settings
  only:
    - schedules

publish_jira:
  stage: publish
  image: python:3.9
  before_script:
    - pip install requests
  script:
    - python3 US4_RPT_update_jira.py --settings settings
  only:
    - schedules
```

***

## Advanced Scenarios

### Example 13: Multi-Environment Configuration

Use different settings for different environments.

```bash
#!/bin/bash
# multi_env_report.sh

ENVIRONMENT=${1:-staging}

case $ENVIRONMENT in
  staging)
    SETTINGS="settings_staging"
    ;;
  production)
    SETTINGS="settings_production"
    ;;
  *)
    echo "Unknown environment: $ENVIRONMENT"
    exit 1
    ;;
esac

echo "Running reports for environment: $ENVIRONMENT"

python3 US1_RPT_create_report_info_files.py \
  --settings base_settings \
  --settings ${SETTINGS} \
  --ticket-source jira

python3 US2_RPT_create_html_reports.py \
  --settings base_settings \
  --settings ${SETTINGS}
```

**Usage:**

```bash
./multi_env_report.sh staging
./multi_env_report.sh production
```

### Example 14: Integration Build Processing

Handle integration builds with multiple components.

**Settings:**

```json
{
  "coverage_app_list": [
    {
      "app_regex": "my-integration-build",
      "branch_regex": "main",
      "integration_build": true
    }
  ],
  "repo_list": [
    {
      "repoName": "component-a",
      "SealightsAppName": "component-a",
      "SealightsBranchName": "main"
    },
    {
      "repoName": "component-b",
      "SealightsAppName": "component-b",
      "SealightsBranchName": "main"
    }
  ]
}
```

**Usage:**

```bash
python3 US_SRC_tag_repos_by_history.py \
  --settings settings \
  --days-back 30
```

The tool automatically validates all components are configured in `repo_list`.

### Example 15: Cleanup Old Coverage Data

Delete coverage data for completed sprints.

```bash
#!/bin/bash
# cleanup_old_coverage.sh

# Delete coverage for specific tickets
for ticket in PROJ-100 PROJ-101 PROJ-102; do
  echo "Deleting coverage for $ticket"
  python3 US_RPT_jira_plugin_delete_coverage.py $ticket --settings settings
done

# Or delete entire project coverage
# python3 US_RPT_jira_plugin_delete_project_coverage.py PROJ --settings settings
```

### Example 16: Custom Ticket Extraction

Extract tickets from commit messages with custom format.

**Settings:**

```json
{
  "scm": {
    "key_pattern_regex": "\\[(FEAT|BUG|TASK)-[0-9]+\\]"
  }
}
```

**Matches commits like:**

```
[FEAT-123] Add user authentication
[BUG-456] Fix login redirect issue
```

### Example 17: Parallel Processing for Large Repos

Process multiple repositories in parallel using GNU Parallel.

```bash
#!/bin/bash
# parallel_tagging.sh

# Create list of repos
cat > repo_list.txt <<EOF
frontend-app
backend-api
mobile-app
admin-portal
EOF

# Tag repos in parallel (4 at a time)
cat repo_list.txt | parallel -j 4 '
  echo "Processing {}"
  python3 US_SRC_tag_repos_by_github_prs.py \
    --settings settings_{} \
    --days-back 30
'
```

### Example 18: Report with Custom Date Range

Generate reports for specific historical period.

```bash
# Tag code changes from Jan 1 - Jan 31, 2026
python3 US_SRC_tag_repos_by_github_prs.py \
  --settings settings \
  --since-date 2026-01-01 \
  --log-level INFO

# Update settings temporarily
export SEALIGHTS_COVERAGE_DAYS_BACK=60

# Generate reports looking back 60 days
python3 US1_RPT_create_report_info_files.py \
  --settings settings \
  --ticket-source jira
```

### Example 19: Conditional Reporting Based on Coverage

Fail CI build if coverage is below threshold.

```bash
#!/bin/bash
# coverage_gate.sh

THRESHOLD=70
FAILED=false

# Generate reports
python3 US1_RPT_create_report_info_files.py --settings settings --ticket-source jira
python3 US2_RPT_create_html_reports.py --settings settings

# Check coverage for each ticket
for report in reports/ReportInfo_*.json; do
  ticket=$(basename "$report" | sed 's/ReportInfo_//;s/.json//')
  coverage=$(jq -r '.overallResults.overall_coverage // 0' "$report")

  if (( $(echo "$coverage < $THRESHOLD" | bc -l) )); then
    echo "❌ $ticket: ${coverage}% (below ${THRESHOLD}%)"
    FAILED=true
  else
    echo "✅ $ticket: ${coverage}%"
  fi
done

if [ "$FAILED" = true ]; then
  echo "Coverage gate failed!"
  exit 1
fi

echo "Coverage gate passed!"
```

### Example 20: Notification on Low Coverage

Send Slack notification when coverage is low.

```bash
#!/bin/bash
# notify_low_coverage.sh

THRESHOLD=60
SLACK_WEBHOOK="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

python3 US1_RPT_create_report_info_files.py --settings settings --ticket-source jira

for report in reports/ReportInfo_*.json; do
  ticket=$(basename "$report" | sed 's/ReportInfo_//;s/.json//')
  coverage=$(jq -r '.overallResults.overall_coverage // 0' "$report")
  title=$(jq -r '.title' "$report")

  if (( $(echo "$coverage < $THRESHOLD" | bc -l) )); then
    message="⚠️ Low coverage alert: $ticket - $title has ${coverage}% coverage (threshold: ${THRESHOLD}%)"

    curl -X POST "$SLACK_WEBHOOK" \
      -H 'Content-Type: application/json' \
      -d "{\"text\": \"$message\"}"
  fi
done
```

***

## Sample Output

### HTML Report Sample Structure

```
reports/
├── Summary.html                  # Summary of all tickets
├── PROJ-123.html                # Individual ticket report
├── PROJ-124.html
├── ReportInfo_PROJ-123.json     # Raw data
├── ReportInfo_PROJ-124.json
└── confluence_links.json         # Confluence page URLs
```

### ReportInfo JSON Structure

```json
{
  "key": "PROJ-123",
  "title": "Implement user authentication",
  "overallResults": {
    "overall_coverage": 78.5,
    "overall_count": 120,
    "unit_tests_coverage": 85.0,
    "unit_tests_count": 80,
    "integration_tests_coverage": 65.0,
    "integration_tests_count": 40
  },
  "methods": [
    {
      "signature": "com.example.auth.AuthService.login",
      "coverage": 100,
      "testStages": ["Unit_Tests", "Integration_Tests"]
    }
  ]
}
```

***

## Next Steps

* [Troubleshooting](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/troubleshooting.md) - Common issues and solutions
* [CLI Reference](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md) - Detailed command documentation
* [Configuration](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md) - Settings reference


---

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