Configuration

The User Story Coverage Tagging tool uses JSON-based configuration files with environment variable overrides.

Configuration Files

Default Behavior

By default, scripts look for a file named settings in the current directory. You can specify alternative files using the --settings flag:

python3 US1_RPT_create_report_info_files.py --settings my_config

Multiple Configuration Files

You can specify multiple settings files that will be merged together:

python3 US1_RPT_create_report_info_files.py \
  --settings base_config \
  --settings team_config \
  --settings credentials

Merge Rules:

• Single values (strings, numbers, booleans) are overridden by the last file

• Arrays are appended (concatenated)

• Objects are merged recursively

Sample Configuration

A complete sample configuration is available in settings.sample. Copy and modify it:

cp settings.sample settings

Environment Variables

All configuration values can be overridden using environment variables. Environment variables always take precedence over settings files.

Environment Variable Reference

Environment Variable	Settings Path	Type	Description
OUTPUT_FOLDER	output_folder	string	Directory for generated reports
SEALIGHTS_API_TOKEN	sealights.api_token	string	SeaLights API authentication token
SEALIGHTS_DOMAIN	sealights.domain	string	SeaLights domain (e.g., company.sealights.co)
SEALIGHTS_COVERAGE_DAYS_BACK	sealights.coverage_days_back	integer	Days to look back for coverage data
SEALIGHTS_REPORT_TIMEOUT_MINUTES	sealights.report_timeout_minutes	integer	Report generation timeout (default: 30)
SEALIGHTS_USE_REPOSITORY_URL	sealights.use_repository_url	boolean	Use repository URL from SeaLights if available
SEALIGHTS_VERIFY_SSL	sealights.verify_ssl	boolean	Verify SSL certificates (default: true)
KEY_PATTERN_REGEX	scm.key_pattern_regex	string	Regex to extract ticket IDs
GITHUB_API_URL	scm.github_api_url	string	GitHub API URL
GITHUB_TOKEN	scm.github_token	string	GitHub personal access token
GITHUB_OWNER	scm.github_owner	string	GitHub organization or user
SCM_TYPE	scm.type	string	SCM type: github, gitlab, bitbucket, ado
JIRA_AUTHORIZATION	jira.authorization	string	Jira authorization header value
JIRA_GET_LIST_JQL	jira.jql	string	JQL query to fetch tickets
JIRA_CHILD_LEVELS	jira.child_levels	integer	Number of child levels to traverse
JIRA_BASE_URL	jira.base_url	string	Jira instance base URL
JIRA_API_VERSION	jira.api_version	integer	Jira API version (2 or 3)
JIRA_CUSTOM_FIELDS	jira.jira_custom_fields	JSON	Custom field mappings for coverage data
JIRA_EXTRA_TICKET_FIELDS	jira.extra_ticket_fields	JSON array	Additional fields to pull from tickets
ADO_WIQL	ado.wiql	string	WIQL query to fetch work items
ADO_AUTHORIZATION	ado.authorization	string	Azure DevOps authorization header
ADO_ORGANIZATION	ado.organization	string	ADO organization name
ADO_PROJECT	ado.project	string	ADO project name
ADO_CHILD_LEVELS	ado.child_levels	integer	Number of child levels to traverse
ADO_EXTRA_TICKET_FIELDS	ado.extra_ticket_fields	JSON array	Additional work item fields
CONFLUENCE_AUTHORIZATION	confluence.authorization	string	Confluence authorization header
CONFLUENCE_BASE_URL	confluence.base_url	string	Confluence instance URL
CONFLUENCE_SPACE_KEY	confluence.space_key	string	Confluence space key
CONFLUENCE_ANCESTOR_ID	confluence.ancestor_id	string	Parent page ID for reports
CONFLUENCE_NOTE	confluence.note	string	Note text for Confluence pages
CONFLUENCE_EXTRA_SUMMARY_FIELDS	confluence.extra_summary_fields	JSON array	Extra fields for summary table
CONFLUENCE_SUMMARY_PAGE_TITLE	confluence.summary_page_title	string	Title for summary page
CONFLUENCE_DETAILS_PAGE_PREFIX	confluence.details_page_prefix	string	Prefix for detail page titles
TEST_STAGES	test_stages	JSON array	Test stage definitions
GROUPED_TEST_STAGES	grouped_test_stages	JSON array	Aggregated test stage groups
COVERAGE_APP_LIST	coverage_app_list	JSON array	Apps/branches to get coverage from
REPO_LIST	repo_list	JSON array	Repository configurations

Using Environment Variables

Set environment variables before running:

export SEALIGHTS_API_TOKEN="your-token-here"
export JIRA_BASE_URL="https://yourcompany.atlassian.net"
python3 US1_RPT_create_report_info_files.py --settings settings

JSON values in environment variables:

For complex values (arrays, objects), use JSON format:

export TEST_STAGES='[{"name":"Unit","reportJsonKey":"unit","reportTitle":"Unit Tests"}]'

Configuration Sections

Output Configuration

Controls where generated files are saved.

{
  "output_folder": "./reports"
}

• output_folder - Directory path for output files. Leave empty for current directory.

SeaLights Configuration

Connection and authentication for SeaLights platform.

{
  "sealights": {
    "api_token": "your-api-token",
    "domain": "yourcompany.sealights.co",
    "coverage_days_back": 14,
    "report_timeout_minutes": 30,
    "use_repository_url": false,
    "verify_ssl": true
  }
}

Fields:

• api_token (required) - SeaLights API token for authentication

• domain (required) - Your SeaLights account domain

• coverage_days_back (required) - Number of days to look back for coverage data

• report_timeout_minutes (optional, default: 30) - Max wait time for report generation

• use_repository_url (optional, default: false) - Use repository URLs from SeaLights when available

• verify_ssl (optional, default: true) - Verify SSL certificates for API calls

SCM Configuration

Source control management settings for GitHub, GitLab, Bitbucket, or Azure DevOps.

{
  "scm": {
    "key_pattern_regex": "PROJ-[0-9]+",
    "github_api_url": "https://api.github.com",
    "github_token": "ghp_xxxxxxxxxxxx",
    "github_owner": "your-organization",
    "type": "github",
    "remove_prefix_regex": "^refs/heads/"
  }
}

Fields:

• key_pattern_regex (required) - Regex pattern to extract ticket IDs from text

• type (required) - SCM platform: github, gitlab, bitbucket, or ado

• github_api_url (for GitHub) - GitHub API endpoint

• github_token (for GitHub) - Personal access token

• github_owner (for GitHub) - Organization or user name

• remove_prefix_regex (optional) - Regex to remove from branch names

Regex Pattern Examples:

• Jira: "[A-Z]+-[0-9]+"

• GitHub Issues: "#[0-9]+"

• ADO Work Items: "[0-9]+"

• Custom: "(FEAT|BUG|TASK)-[0-9]+"

Jira Configuration

Settings for Jira Cloud or On-Premises integration.

{
  "jira": {
    "authorization": "Basic base64-encoded-credentials",
    "jql": "project = MYPROJ AND created > startOfMonth(-1)",
    "child_levels": 2,
    "base_url": "https://yourcompany.atlassian.net",
    "api_version": 3,
    "jira_custom_fields": {
      "summary": "customfield_10917",
      "coverage": {
        "overall": "customfield_10900",
        "unit_tests": "customfield_10901"
      }
    },
    "extra_ticket_fields": [
      {"name": "Team", "field": "customfield_10400.name"},
      {"name": "Priority", "field": "priority.name"}
    ]
  }
}

Fields:

• authorization (required) - Authorization header value (Basic or Bearer)

• jql (required) - JQL query to fetch tickets

• child_levels (optional, default: 1) - How many levels of child issues to include

• base_url (required) - Jira instance URL

• api_version (required) - Jira REST API version (2 for older, 3 for newer)

• jira_custom_fields (optional) - Custom field IDs for coverage data (Jira Cloud only)

• extra_ticket_fields (optional) - Additional fields to extract from tickets

JQL Examples:

"project = MYPROJ AND created >= -30d"
"issueType = Story AND sprint in openSprints()"
"labels = sprint-42 AND status != Closed"

Azure DevOps Configuration

Settings for Azure DevOps integration.

{
  "ado": {
    "wiql": "SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType] = 'User Story' AND [System.ChangedDate] >= @Today - 30",
    "authorization": "Basic base64-pat-token",
    "organization": "your-organization",
    "project": "your-project",
    "child_levels": 2,
    "extra_ticket_fields": [
      {"name": "Team", "field": "System.TeamProject"}
    ]
  }
}

Fields:

• wiql (required) - WIQL query to fetch work items

• authorization (required) - Authorization header with PAT token

• organization (required) - ADO organization name

• project (required) - Project name

• child_levels (optional, default: 1) - Levels of child work items

• extra_ticket_fields (optional) - Additional fields to extract

WIQL Examples:

"SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType] = 'User Story'"
"SELECT [System.Id] FROM WorkItems WHERE [System.IterationPath] = 'Sprint 42'"

Confluence Configuration

Settings for creating Confluence pages.

{
  "confluence": {
    "authorization": "Basic base64-credentials",
    "base_url": "https://yourcompany.atlassian.net",
    "space_key": "DEV",
    "ancestor_id": "123456789",
    "note": "This page is auto-generated. Changes will be overwritten.",
    "extra_summary_fields": ["Team", "Priority"],
    "summary_page_title": "Sprint Coverage Summary",
    "details_page_prefix": "Coverage -"
  }
}

Fields:

• authorization (required) - Authorization header value

• base_url (required) - Confluence instance URL

• space_key (required) - Confluence space identifier

• ancestor_id (required) - Parent page ID for created pages

• note (optional) - Warning note added to pages

• extra_summary_fields (optional) - Fields to include in summary table

• summary_page_title (optional) - Title for auto-generated summary page

• details_page_prefix (optional) - Prefix for detail page titles

Test Stages Configuration

Defines test stages/phases for coverage reporting.

{
  "test_stages": [
    {
      "name": "Unit_Tests",
      "reportJsonKey": "unit_tests",
      "reportTitle": "Unit Tests"
    },
    {
      "name": "Integration_Tests",
      "reportJsonKey": "integration_tests",
      "reportTitle": "Integration Tests"
    },
    {
      "name": "E2E_Tests",
      "reportJsonKey": "e2e_tests",
      "reportTitle": "E2E Tests"
    }
  ]
}

Fields per stage:

• name (required) - Stage name as it appears in SeaLights TGA report

• reportJsonKey (required) - JSON key in generated report files

• reportTitle (required) - Display title in HTML/Confluence reports

Grouped Test Stages Configuration

Creates aggregated coverage metrics from multiple test stages.

{
  "grouped_test_stages": [
    {
      "name": "Overall",
      "reportJsonKey": "overall",
      "reportTitle": "Overall Coverage",
      "stages": ["Unit_Tests", "Integration_Tests", "E2E_Tests"],
      "show_gate": true,
      "severity": 2
    },
    {
      "name": "Pre_Prod",
      "reportJsonKey": "pre_prod",
      "reportTitle": "Pre-Production",
      "stages": ["Integration_Tests", "E2E_Tests"],
      "show_gate": true,
      "severity": 1
    }
  ]
}

Fields per group:

• name (required) - Group identifier

• reportJsonKey (required) - JSON key in report files

• reportTitle (required) - Display title

• stages (required) - Array of stage names to aggregate

• show_gate (optional) - Show pass/fail gate in reports

• severity (optional) - 1 (orange) or 2 (red) for failed gates

Coverage App List Configuration

Specifies which applications and branches to collect coverage from.

{
  "coverage_app_list": [
    {
      "app_regex": "my-app",
      "branch_regex": "main",
      "integration_build": false
    },
    {
      "app_regex": "my-integration-build",
      "branch_regex": "develop",
      "integration_build": true
    }
  ]
}

Fields per entry:

• app_regex (required) - Regex matching SeaLights application name

• branch_regex (required) - Regex matching branch name

• integration_build (optional, default: false) - If true, treats as integration build with components

Regex Matching:

• Use exact names: "my-app"

• Use patterns: "app-.*"

• Match any: ".*"

Repository List Configuration

Maps git repositories to SeaLights applications.

{
  "repo_list": [
    {
      "repoName": "frontend-app",
      "baseUrl": "[email protected]:mycompany/",
      "branchName": "main",
      "SealightsAppName": "frontend",
      "SealightsBranchName": "main",
      "ignore": false
    },
    {
      "repoName": "backend-api",
      "baseUrl": "https://github.com/mycompany/",
      "branchName": "develop",
      "SealightsAppName": "api-service",
      "SealightsBranchName": "dev"
    }
  ]
}

Fields per repository:

• repoName (required) - Repository name in git

• baseUrl (required) - Git base URL (SSH or HTTPS)

• branchName (required) - Branch to process

• SealightsAppName (required) - Application name in SeaLights

• SealightsBranchName (required) - Branch name in SeaLights

• ignore (optional, default: false) - Skip this repository

Complete Configuration Example

See settings.sample for a fully commented example with all options.

Configuration Validation

Scripts validate configuration at startup. Common validation errors:

• Missing required fields - Check that all required settings are present

• Invalid regex patterns - Test regex patterns using online tools

• Invalid URLs - Ensure URLs include protocol (https://)

• Invalid JSON in env vars - Validate JSON format for array/object values

Best Practices

1. Separate Sensitive Data

Split configuration into multiple files:

# base_config - Non-sensitive settings
{
  "output_folder": "./reports",
  "test_stages": [...]
}

# credentials - Sensitive tokens (gitignored)
{
  "sealights": {"api_token": "..."},
  "jira": {"authorization": "..."}
}

# Usage
python3 script.py --settings base_config --settings credentials

2. Use Environment Variables for CI/CD

In CI/CD pipelines, use environment variables instead of files:

# GitHub Actions example
env:
  SEALIGHTS_API_TOKEN: ${{ secrets.SEALIGHTS_TOKEN }}
  JIRA_AUTHORIZATION: ${{ secrets.JIRA_AUTH }}

3. Version Control Settings

• Commit: Base configuration, structure, regex patterns

• Ignore: Credentials, tokens, production URLs

settings
credentials
*_credentials.json

4. Document Custom Fields

When using custom fields, document them in comments:

{
  "jira": {
    "jira_custom_fields": {
      "// Note: customfield_10917 = Coverage Summary Text Field": "",
      "summary": "customfield_10917",
      "coverage": {
        "// Note: customfield_10900 = Overall Coverage %": "",
        "overall": "customfield_10900"
      }
    }
  }
}

Next Steps

• Examples - See configuration in action

• Security Considerations - Protect sensitive data

• Troubleshooting - Configuration issues and solutions