Examples

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

Table of Contents

• Complete End-to-End Workflow

• Tagging Workflows

• Reporting Workflows

• CI/CD Integration

• Advanced Scenarios

---

Complete End-to-End Workflow

Sprint Coverage Report Generation

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

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

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

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

Settings Requirements:

{
  "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.

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.

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

Settings Requirements:

{
  "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.

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.

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.

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

{
  "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.

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.

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.

python3 US4_RPT_update_jira_plugin.py \
  --settings settings

Settings Requirements:

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

---

CI/CD Integration

Example 10: GitHub Actions Workflow

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

// 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

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

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

./multi_env_report.sh staging
./multi_env_report.sh production

Example 14: Integration Build Processing

Handle integration builds with multiple components.

Settings:

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

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.

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

{
  "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.

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

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

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

#!/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

{
  "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 - Common issues and solutions

• CLI Reference - Detailed command documentation

• Configuration - Settings reference